> ## Documentation Index
> Fetch the complete documentation index at: https://rankahead.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Open Settings">
    In the Rankahead dashboard, click **Settings** in the sidebar.
  </Step>

  <Step title="Go to the MCP section">
    Select **MCP** (or **API Keys**, depending on your account view) from the settings navigation.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  MCP tokens grant full access to your organisation's data and tools. Revoke any token you no longer need from **Settings > MCP**.
</Warning>

## Step 2: Initialise the connection

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

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "protocolVersion": "2024-11-05",
      "capabilities": { "tools": {} },
      "serverInfo": { "name": "rankahead-mcp", "version": "0.1.0" }
    }
  }
  ```
</CodeGroup>

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

```bash cURL theme={null}
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.

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 2
  }
  ```

  ```json Response (truncated) theme={null}
  {
    "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"]
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

See the [MCP Reference](/mcp/overview) 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

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {}
    },
    "id": 3
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 3,
    "result": {
      "content": [
        {
          "type": "text",
          "text": "{\"visibilityScore\": 68, \"shareOfVoice\": 0.34, \"citationCount\": 142, \"topModels\": [\"perplexity\", \"chatgpt\", \"gemini\"]}"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Example: trigger a prompt run

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "trigger_prompt_run",
    "arguments": {
      "promptId": "prompt_abc123"
    }
  },
  "id": 4
}
```

### Example: generate a blog post

```json theme={null}
{
  "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`          |

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Invalid or revoked MCP token"
  }
}
```

## Connect Claude Desktop

<Steps>
  <Step title="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`
  </Step>

  <Step title="Add the Rankahead MCP server">
    Add the following entry to the `mcpServers` object, replacing `YOUR_MCP_TOKEN` with the token you created in Settings:

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "rankahead": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://app.rankahead.ai/api/mcp"],
          "env": {
            "AUTHORIZATION": "Bearer YOUR_MCP_TOKEN"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen Claude Desktop. The Rankahead tools will appear in the tool selector when you start a new conversation.
  </Step>

  <Step title="Verify the connection">
    In a new Claude conversation, ask: *"List my Rankahead tracking prompts."* Claude will call `list_prompts` and return your prompt data.
  </Step>
</Steps>

## Connect Cursor

<Steps>
  <Step title="Open Cursor settings">
    In Cursor, go to **Settings > MCP** (or press `Cmd+Shift+P` and search for **MCP**).
  </Step>

  <Step title="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`
  </Step>

  <Step title="Save and reload">
    Save the configuration. Cursor will connect to the server and load the available tools automatically.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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](/mcp/overview) tab.

<CardGroup cols={2}>
  <Card title="Analytics" icon="chart-bar">
    `get_dashboard`, `get_gaps`, `get_citations`, `get_trends`, `get_prompt_analytics`
  </Card>

  <Card title="Prompts" icon="search">
    `list_prompts`, `get_prompt`, `create_prompt`, `update_prompt`, `delete_prompt`, `list_runs`, `get_run`, `trigger_prompt_run`
  </Card>

  <Card title="Domains" icon="globe">
    `list_domains`, `get_domain`, `create_domain`, `list_competitors`, `get_competitor`, `add_competitor`, `delete_competitor`
  </Card>

  <Card title="Blog" icon="file-text">
    `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`
  </Card>

  <Card title="Google Search Console" icon="trending-up">
    `get_gsc_connection`, `get_gsc_dashboard`, `get_gsc_alerts`, `mark_gsc_alert_read`
  </Card>

  <Card title="GEO tasks" icon="list-checks">
    `list_geo_tasks`, `get_geo_task`, `create_geo_task`, `update_geo_task`, `delete_geo_task`
  </Card>

  <Card title="Organisation" icon="users">
    `get_organisation`, `list_members`, `send_invite`, `revoke_invite`, `list_pending_invites`
  </Card>

  <Card title="Content & persona" icon="settings">
    `get_content_settings`, `update_content_settings`, `get_persona`, `upsert_persona`
  </Card>
</CardGroup>

## Built-in agent vs. MCP

<Note>
  If you want to use natural language with Rankahead inside the dashboard itself, use the built-in [AI Agent](/agent/overview). The MCP server is for connecting external tools and building custom automations outside of Rankahead's interface.
</Note>

|                | 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 |