Connect your AI client
Every client uses the same server URL. Pick yours below, follow three to five steps, and you're done.
Before you start
- Create a RankLens account by signing in with the Google account that has access to your Search Console properties.
- In the dashboard, open Properties and enable the sites your assistant should see.
- Copy the server URL:
https://api.ranklens.app/mcp Client setup
Claude
Works in Claude.ai and Claude Desktop through custom connectors, and in Claude Code from the terminal.
- Open Settings, then Connectors.
- Choose Add custom connector.
- Name it RankLens and paste the server URL.
- Select Add, then Connect. A RankLens window opens: sign in and approve the connection.
- In a chat, open the tools menu and make sure RankLens is turned on.
claude mcp add --transport http ranklens https://api.ranklens.app/mcp In Claude Code, run /mcp after adding the server and pick RankLens to sign in. On Team and Enterprise plans, an owner may need to add the connector for the organization first.
ChatGPT
ChatGPT connects to remote MCP servers through connectors in developer mode.
- Open Settings, then Apps and Connectors, then Advanced settings, and turn on Developer mode.
- Back in Apps and Connectors, choose Create.
- Name it RankLens, paste the server URL, and set Authentication to OAuth.
- Confirm and create the connector. Sign in to RankLens and approve the connection when asked.
- In a new chat, open the + menu, choose Developer mode and enable RankLens.
Developer mode and custom connectors depend on your ChatGPT plan and workspace settings. Menu names change from time to time; look for connectors or apps in Settings.
Cursor
Add RankLens to your global Cursor config, or to .cursor/mcp.json in a single project.
- Open ~/.cursor/mcp.json, or create it.
- Add the ranklens entry below and save.
- Open Cursor Settings, then MCP. RankLens shows as needing login: select it to sign in and approve.
{
"mcpServers": {
"ranklens": {
"url": "https://api.ranklens.app/mcp"
}
}
} Windsurf
Windsurf reads remote MCP servers from its Cascade config file.
- Open ~/.codeium/windsurf/mcp_config.json, or use the MCP settings in Cascade to open it.
- Add the ranklens entry below and save.
- Refresh the MCP server list in Cascade and sign in when prompted.
{
"mcpServers": {
"ranklens": {
"serverUrl": "https://api.ranklens.app/mcp"
}
}
} If your Windsurf version doesn't offer a sign-in, use an API key header instead. See Using an API key below.
Zed
Zed calls MCP servers context servers. Add RankLens to your Zed settings.
- Open the command palette and run zed: open settings.
- Add the context_servers entry below and save.
- Open the Agent panel settings and check that RankLens is listed and enabled.
{
"context_servers": {
"ranklens": {
"url": "https://api.ranklens.app/mcp",
"headers": {
"Authorization": "Bearer rl_your_api_key"
}
}
}
} This example uses an API key, which works in every Zed version. Newer versions can sign in with OAuth: remove the headers block and Zed will prompt you.
Codex CLI
Codex reads MCP servers from its TOML config, shared by the CLI and the IDE extension.
- Open ~/.codex/config.toml, or create it.
- Add the server entry below and save.
- Run codex mcp login ranklens to sign in, then start Codex.
[mcp_servers.ranklens]
url = "https://api.ranklens.app/mcp" codex mcp login ranklens To use an API key instead, add bearer_token_env_var = "RANKLENS_API_KEY" under the same table and export that variable in your shell.
Gemini CLI
Gemini CLI connects to streamable HTTP servers listed in its settings file.
- Open ~/.gemini/settings.json, or create it.
- Add the ranklens entry below and save.
- Start Gemini CLI and run /mcp auth ranklens to sign in.
{
"mcpServers": {
"ranklens": {
"httpUrl": "https://api.ranklens.app/mcp"
}
}
} /mcp auth ranklens Using an API key
For clients without OAuth, scripts and CI. Create a key in the dashboard under
API keys. It starts with rl_ and is shown once, so store it somewhere safe. Send it as a bearer token:
Authorization: Bearer rl_your_api_key {
"mcpServers": {
"ranklens": {
"url": "https://api.ranklens.app/mcp",
"headers": {
"Authorization": "Bearer rl_your_api_key"
}
}
}
} curl https://api.ranklens.app/mcp \
-H "Authorization: Bearer rl_your_api_key" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' A key has the same access as your account. Treat it like a password: don't commit it to a repository, and revoke it from the dashboard if it leaks.
First questions to try
- What can you do with RankLens? List my properties.
- How did example.com do in the last 28 days compared with the 28 before?
- Find striking-distance keywords for my blog and suggest which pages to update.
- Inspect my five most important URLs and tell me if any aren't indexed.
Troubleshooting
- The assistant says it has no properties.
- Open the dashboard, go to Properties and make sure the site is enabled. Only enabled properties are visible to AI clients. If the list is empty, sync properties from your Google account.
- A tool says my plan doesn't include it.
- Some tools need Starter or Pro. Ask the assistant to run get_capabilities to see what's on your plan, or compare plans on the pricing page.
- Requests fail with 401 Unauthorized.
- The connection or API key was revoked or has expired. Reconnect from your client, or create a new API key in the dashboard.
- The client never opens a sign-in window.
- Some clients and older versions don't support OAuth for remote servers. Use an API key in the Authorization header instead.