MCP Server Setup

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude connect to outside tools and data. Once RankNest is connected over MCP, you can work in plain language ("list my clients and show their experiment counts", "crawl acme.com and generate a Linking Plan"), and the assistant calls RankNest on your behalf. Every call uses your account's access, so the assistant can only see and change what you can.

Where to find it

Open Account Settings, go to the Integrations tab, and click Developer API. The MCP tab is selected by default and generates the exact setup for your situation:

• Client: choose Claude Desktop or Claude Code.
• Scope: choose the User option, which limits the connection to your own data. The Admin option is for RankNest platform administrators and isn't covered here.

Connecting Claude Desktop

Claude Desktop connects to RankNest's hosted MCP server and authenticates through your browser. There is no token to copy.

1. In Claude Desktop, go to Settings → Integrations and click Add custom connector.
2. Enter the details the generator shows:
   • Name: RankNest
   • Remote MCP server URL: https://www.ranknest.io/api/mcp
   • Leave OAuth Client ID and OAuth Client Secret blank.
3. Click Add. Claude opens a browser window. Log in to your RankNest account and click Approve.
4. Open a new conversation and try: "List all my RankNest clients and show me their experiment counts."

Connecting Claude Code

Claude Code runs the MCP server locally and authenticates with a Personal Access Token instead of a browser login.

1. Create a User-scope token. See Personal Access Tokens.

2. Add the configuration the generator shows to your project's .mcp.json file in the project root, pasting your token as RANKNEST_TOKEN:

   {
     "mcpServers": {
       "ranknest": {
         "command": "npx",
         "args": ["-y", "tsx", "tools/mcp-server.ts"],
         "env": {
           "RANKNEST_API_URL": "https://www.ranknest.io",
           "RANKNEST_TOKEN": "rnk_live_XXXXXXXXXXXXXXXX"
         }
       }
     }
   }
   

3. Claude Code auto-detects the server the next time it starts in that project. Verify the connection by asking it to run the ranknest_health tool.

What the tools can do

The server exposes more than 50 tools, all named ranknest_<verb>_<resource>. Together they cover most of what the dashboard does:

• Clients: list, create, update, and delete clients.
• SEO tests: manage experiments and generate AI test variations. See SEO Testing.
• Link maps: manage link maps plus their pages, links, and topic clusters, and trigger a site crawl. See Link Mapping.
• Linking Plan: generate recommendations and update their status. See Linking Plan.
• Site Audit: run a technical SEO audit of a site. See Site Audit.
• Search Console: pull performance data for a connected property. See Google Search Console.
• Tasks and SEO variables: manage client tasks and your test variable library.

All calls inherit your subscription limits.

Tips

• Give the assistant IDs when you have them ("generate a linking plan for map <id>"). It skips a lookup round-trip and avoids ambiguity between similarly named clients.
• Treat destructive requests carefully: delete tools remove real data, exactly as the dashboard would.
• If you use both Claude Desktop and Claude Code, you can connect both at the same time. They authenticate independently.

Troubleshooting

Claude Desktop's browser window never shows the Approve screen. Make sure you're logged in to RankNest in that browser, then remove and re-add the connector.

Claude Code doesn't list any ranknest tools. Check that .mcp.json is in the project root, the JSON is valid, and RANKNEST_TOKEN contains a current token. A revoked token fails every call. See Personal Access Tokens for revoking and re-creating.

Tools return "Invalid or expired token". The token was revoked or mistyped. Create a fresh User-scope token and update your configuration.

Related

• Personal Access Tokens
• CLI