Connect your AI agent (MCP)

Nextrank runs an MCP server. Connect your AI agent to it and the agent can list your projects, research keywords and read your saved lists — drawing on the same organisation, plan and credit balance as the web app. A read costs nothing; keyword research and metric refresh draw credits at the same price the app shows on the button.

The first thing to ask an agent once it is connected:

whoami

That returns your plan, credit balance and projects, and confirms the key works.

Get an API key

1. Sign in to Nextrank and open Settings → API keys (the menu under your avatar).
2. Create key, give it a name like Claude Code — laptop, and copy it. It is shown once — nr_…. If you lose it, revoke it and make a new one.
3. A key belongs to one organisation and uses that organisation's plan and credits. MCP is available on every plan, including Free — reads cost nothing, and paid tools like keyword research draw from whatever credit balance the organisation already has.

Keep the key out of shell history and out of git. Most clients read it from an environment variable or their own secret store — the snippets below do.

Claude Code

claude mcp add --transport http --scope user nextrank \
  https://mcp.trynextrank.com/mcp \
  --header "Authorization: Bearer ${NEXTRANK_API_KEY}"

Server prompts show up as slash commands: /nextrank:keyword-research-plan, /nextrank:weekly-rank-review.

Cursor

Or add it by hand to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nextrank": {
      "url": "https://mcp.trynextrank.com/mcp",
      "headers": { "Authorization": "Bearer ${env:NEXTRANK_API_KEY}" }
    }
  }
}

Set NEXTRANK_API_KEY in your environment. The Add to Cursor button installs the same config.

Codex CLI

codex mcp add nextrank --url https://mcp.trynextrank.com/mcp \
  --bearer-token-env-var NEXTRANK_API_KEY

VS Code

Or .vscode/mcp.json in your workspace:

{
  "servers": {
    "nextrank": {
      "type": "http",
      "url": "https://mcp.trynextrank.com/mcp",
      "headers": { "Authorization": "Bearer ${input:nextrank_api_key}" }
    }
  }
}

The Install in VS Code button does this and prompts for the key on first use, storing it in VS Code's secret storage.

Gemini CLI

gemini mcp add --transport http nextrank https://mcp.trynextrank.com/mcp \
  --header "Authorization: Bearer ${NEXTRANK_API_KEY}"

Cline, Zed, opencode, and anything else

Any client that speaks Streamable HTTP takes the same two fields — a URL and an Authorization header:

{
  "url": "https://mcp.trynextrank.com/mcp",
  "headers": { "Authorization": "Bearer ${NEXTRANK_API_KEY}" }
}

For a stdio-only client, wrap the endpoint with a shim:

npx mcp-remote@latest --http https://mcp.trynextrank.com/mcp \
  --header "Authorization: Bearer ${NEXTRANK_API_KEY}"

Claude.ai, Claude Desktop, ChatGPT

These need OAuth rather than a pasted key. It is coming in the next release — this page will get the connect steps when it ships. Until then, use one of the CLI or editor clients above.

Example prompts

• "Research keywords for trynextrank.com and save the ten best to the project."
• "What's my credit balance and which projects do I have?"
• "Estimate what a 300-row keyword search would cost before running it."

Troubleshooting

The server connects but never appears / "no tools". Some clients send Accept: application/json only and a strict MCP server answers 406. Nextrank's server is lenient about this, so update the client first — most shipped a fix. Re-add the server (/mcp in Claude Code, "MCP: Reset Cached Tools" in VS Code) after upgrading.

401 after it worked before. The key was revoked or expired — make a new one in Settings → API keys. For OAuth-based shims, a stale token cache is the usual cause: rm -rf ~/.mcp-auth and reconnect.

"Too many requests". The server allows 30 requests per minute per organisation. The error tells the agent how long to wait; it will retry.

Some tools are missing. Clients cap how many tools they load across all servers (VS Code 128, others lower). Disable servers you are not using, or use a tool-filtering setting if the client has one.