Connect a client

There are two ways to connect an MCP client to Ranktracker:

• OAuth (recommended) — paste the endpoint URL into your client and approve access in your browser. No token to copy or store. This is the easiest path for Claude, Cursor, ChatGPT and any other interactive client.
• API token — a long-lived credential you create in the app and paste into a config file or Authorization header. Best for CI pipelines, scripts, and clients that don't support OAuth.

Both require the account plan to have API access enabled — without it, the connection is refused. If you haven't yet, read the MCP overview for what the server does and which tools it exposes.

Option A — Connect with OAuth (recommended)

1. Point your client at the endpoint — https://api.ranktracker.com/mcp. Don't paste a token; leave auth blank and let the client discover it.
2. Approve in the browser. Your client opens a consent screen at app.ranktracker.com/authorize showing which application is asking, which permissions it wants, and which Ranktracker account it will connect to.
3. Done. The client stores the connection and refreshes its access token automatically. You should see the Ranktracker tools in the client's tool picker right away.

:::warning An administrator must approve Connecting an AI client grants it access to the whole account, so only an account administrator can approve the consent screen. If a non-admin attempts it, they see an "ask your account administrator" screen instead of the consent prompt. :::

Client	Setup
Claude Code	claude mcp add --transport http ranktracker https://api.ranktracker.com/mcp
Claude Desktop	Add the JSON block below to claude_desktop_config.json, then connect — it opens the consent screen in your browser
Cursor	Add the JSON block below to ~/.cursor/mcp.json, then connect
ChatGPT (Settings → Connectors → Add custom connector)	Paste https://api.ranktracker.com/mcp as the server URL — no auth field needed
MCP Inspector	npx @modelcontextprotocol/inspector → choose Streamable HTTP → paste the endpoint URL → Connect

For Claude Desktop and Cursor, the config block is:

{
  "mcpServers": {
    "ranktracker": {
      "url": "https://api.ranktracker.com/mcp"
    }
  }
}

No headers block — the client discovers the OAuth flow from the endpoint itself and opens the browser consent screen the first time it connects.

Scopes

The consent screen asks for two scopes:

Scope	What it grants
mcp:read	Read your projects, keywords, rankings, competitors and reports
mcp:write	Re-run your existing reports (no new data is bought, nothing is emailed)

Access tokens last 1 hour and refresh automatically in the background; the connection itself persists until it's revoked, so you won't be asked to re-approve on every session.

Option B — Connect with an API token

Use an API token for CI pipelines, scripts, or any client that can't run an OAuth flow.

1. In the Ranktracker app, go to Account → API and create a new MCP token. This requires an administrator role and a plan with API access enabled.
2. Copy the token — it looks like tkn_mcp_usr_… and is shown once.
3. Send it as a Bearer credential: Authorization: Bearer <TOKEN>.

:::note A distinct kind of key An MCP token works only on /mcp — never on /graphql or the REST API — and a REST API key (tkn_usr_…) will not work on /mcp. It's revocable independently of your other keys. :::

Client	Setup
Claude Code	claude mcp add --transport http ranktracker https://api.ranktracker.com/mcp --header "Authorization: Bearer <TOKEN>"
Claude Desktop	Add the JSON block below to claude_desktop_config.json
Cursor	Add the JSON block below to ~/.cursor/mcp.json
ChatGPT (Settings → Connectors → Add custom connector)	Paste the endpoint URL and add the Authorization header
VS Code / clients without native HTTP+header support	npx -y mcp-remote https://api.ranktracker.com/mcp --header "Authorization: Bearer <TOKEN>"

For Claude Desktop and Cursor, the config block is:

{
  "mcpServers": {
    "ranktracker": {
      "url": "https://api.ranktracker.com/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Restart the client after editing its config.

Verify the connection

Ask your assistant something that needs your data — for example "list my tracked domains" — and it should call list_domains.

To test without a client, curl the endpoint directly. The Streamable HTTP transport requires an Accept header of application/json, text/event-stream (real clients send it automatically — a raw curl without it gets HTTP 406):

curl -s https://api.ranktracker.com/mcp \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A healthy response lists the available tools. (This curl form uses an API token — the OAuth flow needs a real client to complete the browser step, so it isn't a one-liner.)

Troubleshooting

Symptom	Cause	Fix
HTTP 401	Missing, malformed, or expired/revoked credential — or you used a REST API key.	Reconnect via OAuth, or send a valid tkn_mcp_usr_… token as Authorization: Bearer <TOKEN>. A REST key (tkn_usr_…) will not work on /mcp.
HTTP 403	The credential is valid but your plan doesn't have API access.	Check apiEnabled — see Authentication — and upgrade if needed.
"Ask your account administrator"	A non-admin tried to approve the OAuth consent screen.	Have an account administrator complete the connection instead.
HTTP 406	The Accept header is missing on a raw curl.	Add -H "Accept: application/json, text/event-stream". Real MCP clients set this for you.
HTTP 429	Over the rate limit (200/min per credential, 300/min per IP).	Back off and retry.
Tools don't appear	Client hasn't reloaded since connecting, or the config wasn't saved.	Restart the client; for token setups, confirm the Authorization header is present in its config.

Revoking access

• API token: delete the key in Account → API. It stops working immediately.
• OAuth connection: disconnect it from within the client — this calls POST /oauth/revoke and immediately invalidates the connection.

:::warning No self-serve "connected applications" screen yet Ranktracker doesn't yet have a UI for reviewing or revoking OAuth connections from the account side. If you lose access to the device or client that holds the connection, you can't revoke it yourself — contact support and we'll revoke it for you. :::

Next steps

• MCP overview — the full tool surface and how MCP compares to REST.
• Tool reference — every tool's arguments and return fields.