MCP Integration: Connect External AI Agents to Rankahead

Use the Rankahead MCP server to connect Claude Desktop, Cursor, or any MCP-compatible AI agent to your visibility data, prompts, and content tools.

Rankahead exposes a Model Context Protocol (MCP) server that lets external AI agents and tools interact with your account programmatically. MCP is an open protocol that standardises how AI models connect to external tools and data sources. With Rankahead’s MCP server, you can give any MCP-compatible client — Claude Desktop, Cursor, a custom agent, or your own code — direct access to your visibility data, prompts, blog posts, tasks, and more.

How it works

The Rankahead MCP server runs as a stateless HTTP endpoint. Each request is a JSON-RPC call authenticated with a bearer token. Your AI agent calls the endpoint, lists the available tools, and invokes them by name with structured arguments. The server returns structured JSON responses that the agent can reason about and act on.

• Endpoint: POST https://app.rankahead.ai/api/mcp
• Protocol: MCP JSON-RPC, version 2024-11-05
• Authentication: Authorization: Bearer <YOUR_MCP_TOKEN>
• Server name: rankahead-mcp (version 0.1.0)

Step 1: Create an MCP token

You need an MCP token to authenticate requests. Tokens are scoped to your organisation.

1. Open Settings

   In the Rankahead dashboard, click Settings in the sidebar.

2. Go to the MCP section

   Select MCP (or API Keys, depending on your account view) from the settings navigation.

3. Create a new token

   Click Create token, give it a name (for example, claude-desktop or cursor), and confirm. The token is shown once — copy it now.

4. Store the token securely

   Treat your MCP token like a password. Do not commit it to version control. You can revoke it from the same settings page at any time.

MCP tokens grant full access to your organisation’s data and tools. Revoke any token you no longer need from Settings > MCP.

Step 2: Initialise the connection

Before calling tools, your client must send an initialize request to establish the session and confirm protocol compatibility.

Request

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "rankahead-mcp", "version": "0.1.0" }
  }
}

Send this as an HTTP POST with your token in the Authorization header:

cURL

curl --request POST \
  --url https://app.rankahead.ai/api/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }'

Step 3: List available tools

After initialising, call tools/list to retrieve the full catalogue of tools your client can invoke.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_dashboard",
        "description": "Retrieve overall AI visibility dashboard data including scores and trends.",
        "inputSchema": { "type": "object", "properties": {} }
      },
      {
        "name": "list_prompts",
        "description": "List all tracking prompts for the organisation.",
        "inputSchema": { "type": "object", "properties": {} }
      },
      {
        "name": "trigger_prompt_run",
        "description": "Trigger a manual run for a specific prompt.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "promptId": { "type": "string", "description": "The ID of the prompt to run." }
          },
          "required": ["promptId"]
        }
      }
    ]
  }
}

See the MCP Reference tab for the complete list of tools with full input schemas.

Step 4: Call a tool

Use tools/call to invoke any tool by name, passing arguments as a JSON object.

Example: get your dashboard

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_dashboard",
    "arguments": {}
  },
  "id": 3
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"visibilityScore\": 68, \"shareOfVoice\": 0.34, \"citationCount\": 142, \"topModels\": [\"perplexity\", \"chatgpt\", \"gemini\"]}"
      }
    ]
  }
}

Example: trigger a prompt run

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "trigger_prompt_run",
    "arguments": {
      "promptId": "prompt_abc123"
    }
  },
  "id": 4
}

Example: generate a blog post

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "generate_blog_post",
    "arguments": {
      "domainId": "domain_xyz789",
      "mode": "FROM_GSC_KEYWORD",
      "keyword": "AI SEO tools"
    }
  },
  "id": 5
}

Authentication errors

If your request is missing a token or uses an invalid one, the server returns an HTTP 401 with a JSON-RPC error:

Condition	Error code	Message
No Authorization header	-32000	Missing Authorization: Bearer <token>
Invalid or revoked token	-32000	Invalid or revoked MCP token

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Invalid or revoked MCP token"
  }
}

Connect Claude Desktop

1. Open your Claude Desktop config

   Find the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the Rankahead MCP server

   Add the following entry to the mcpServers object, replacing YOUR_MCP_TOKEN with the token you created in Settings:

   claude_desktop_config.json

   {
     "mcpServers": {
       "rankahead": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://app.rankahead.ai/api/mcp"],
         "env": {
           "AUTHORIZATION": "Bearer YOUR_MCP_TOKEN"
         }
       }
     }
   }
   
3. Restart Claude Desktop

   Quit and reopen Claude Desktop. The Rankahead tools will appear in the tool selector when you start a new conversation.

4. Verify the connection

   In a new Claude conversation, ask: “List my Rankahead tracking prompts.” Claude will call list_prompts and return your prompt data.

Connect Cursor

1. Open Cursor settings

   In Cursor, go to Settings > MCP (or press Cmd+Shift+P and search for MCP).

2. Add a new MCP server

   Click Add MCP server and fill in the following:

   • Name: rankahead
   • URL: https://app.rankahead.ai/api/mcp
   • Auth header: Authorization: Bearer YOUR_MCP_TOKEN
3. Save and reload

   Save the configuration. Cursor will connect to the server and load the available tools automatically.

In Cursor’s Composer or chat, you can now ask questions like “What are my top visibility gaps this week?” and Cursor will use the Rankahead MCP tools to fetch and surface the data.

Available tool categories

The following categories are available through the MCP server. For full tool reference including input schemas and response shapes, see the MCP Reference tab.

Analytics

get_dashboard, get_gaps, get_citations, get_trends, get_prompt_analytics

Prompts

list_prompts, get_prompt, create_prompt, update_prompt, delete_prompt, list_runs, get_run, trigger_prompt_run

Domains

list_domains, get_domain, create_domain, list_competitors, get_competitor, add_competitor, delete_competitor

Blog

list_blog_posts, get_blog_post, generate_blog_post, update_blog_post, publish_blog_post, delete_blog_post, get_blog_gsc_metrics, get_blog_publish_status

Google Search Console

get_gsc_connection, get_gsc_dashboard, get_gsc_alerts, mark_gsc_alert_read

GEO tasks

list_geo_tasks, get_geo_task, create_geo_task, update_geo_task, delete_geo_task

Organisation

get_organisation, list_members, send_invite, revoke_invite, list_pending_invites

Content & persona

get_content_settings, update_content_settings, get_persona, upsert_persona

Built-in agent vs. MCP

If you want to use natural language with Rankahead inside the dashboard itself, use the built-in AI Agent. The MCP server is for connecting external tools and building custom automations outside of Rankahead’s interface.

	Built-in AI agent	MCP server
Access	Rankahead dashboard	Any MCP-compatible client
Auth	Your Rankahead login	MCP token
Use case	Interactive, ad-hoc queries	Automated workflows, external agents
Setup required	None	Create a token, configure your client