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

# Rankahead MCP Server — Overview & Available Tools

> Connect any MCP-compatible AI agent to Rankahead. Automate visibility tracking, content generation, and GEO workflows via JSON-RPC 2.0 over HTTP.

Rankahead exposes a Model Context Protocol (MCP) server that lets external AI agents interact with every feature of the platform — analytics, prompts, domains, content, GSC, and more. You send standard JSON-RPC 2.0 requests over HTTP, and the server executes the corresponding tool on your behalf. This means you can drive Rankahead from Claude Desktop, Cursor, or any other MCP-compatible client without writing custom integration code.

## Endpoint

All MCP requests go to a single HTTP endpoint:

```
POST https://app.rankahead.ai/api/mcp
```

The server is stateless. Each HTTP call is a self-contained JSON-RPC request — there is no session or streaming connection to maintain. Every request must include your MCP token in the `Authorization` header. See the [authentication page](/mcp/authentication) for details.

## Protocol details

| Property         | Value                       |
| ---------------- | --------------------------- |
| Transport        | Streamable HTTP (stateless) |
| RPC format       | JSON-RPC 2.0                |
| Protocol version | `2024-11-05`                |
| Server name      | `rankahead-mcp`             |
| Server version   | `0.1.0`                     |

### Supported methods

| Method            | Description                                       |
| ----------------- | ------------------------------------------------- |
| `initialize`      | Handshake. Returns server info and capabilities.  |
| `ping`            | Health check. Returns an empty object.            |
| `tools/list`      | Returns the full list of available tools.         |
| `tools/call`      | Executes a specific tool and returns its result.  |
| `notifications/*` | Accepted silently with HTTP 202; no action taken. |

Any other method returns JSON-RPC error code `-32601` (method not found).

## Quick start

The examples below show the three requests you need to get oriented with the MCP server.

<Steps>
  <Step title="Initialize the connection">
    Send an `initialize` request to confirm the server is reachable and check the protocol version.

    ```bash curl theme={null}
    curl -s -X POST https://app.rankahead.ai/api/mcp \
      -H "Authorization: Bearer YOUR_MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {}
      }'
    ```

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

  <Step title="List available tools">
    Call `tools/list` to retrieve every tool the server exposes, including their input schemas.

    ```bash curl theme={null}
    curl -s -X POST https://app.rankahead.ai/api/mcp \
      -H "Authorization: Bearer YOUR_MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/list",
        "params": {}
      }'
    ```
  </Step>

  <Step title="Call a tool">
    Use `tools/call` to execute a specific tool. Pass the tool name and any required arguments in `params`.

    ```bash curl theme={null}
    curl -s -X POST https://app.rankahead.ai/api/mcp \
      -H "Authorization: Bearer YOUR_MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": 3,
        "method": "tools/call",
        "params": {
          "name": "get_dashboard",
          "arguments": {}
        }
      }'
    ```

    Tool results are returned as a `content` array with a single `text` item containing JSON-encoded data:

    ```json Response theme={null}
    {
      "jsonrpc": "2.0",
      "id": 3,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "{\"visibilityScore\": 72, ...}"
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## Available tools

The server exposes tools across eight functional categories. All tools operate within your organisation's data.

### Analytics

| Tool                   | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| `get_dashboard`        | Retrieve your AI visibility dashboard summary.                           |
| `get_gaps`             | Fetch gap analysis data — topics where competitors appear but you don't. |
| `get_citations`        | List citations where your domain appears in AI-generated answers.        |
| `get_trends`           | Return visibility trend data over time.                                  |
| `get_prompt_analytics` | Get per-prompt performance metrics.                                      |

### Prompts

| Tool                 | Description                                     |
| -------------------- | ----------------------------------------------- |
| `list_prompts`       | List all tracking prompts in your organisation. |
| `get_prompt`         | Retrieve a single prompt by ID.                 |
| `list_runs`          | List run history for a prompt.                  |
| `get_run`            | Retrieve the result of a specific prompt run.   |
| `create_prompt`      | Create a new tracking prompt.                   |
| `update_prompt`      | Update an existing prompt.                      |
| `delete_prompt`      | Delete a prompt.                                |
| `trigger_prompt_run` | Manually trigger a prompt run immediately.      |

### Domains

| Tool                | Description                            |
| ------------------- | -------------------------------------- |
| `list_domains`      | List all domains in your organisation. |
| `get_domain`        | Retrieve a single domain by ID.        |
| `list_competitors`  | List competitors tracked for a domain. |
| `get_competitor`    | Retrieve a specific competitor.        |
| `add_competitor`    | Add a competitor to a domain.          |
| `create_domain`     | Add a new domain to your organisation. |
| `delete_competitor` | Remove a competitor from a domain.     |

### Blog

| Tool                      | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `list_blog_posts`         | List all blog posts.                                    |
| `get_blog_post`           | Retrieve a single blog post by ID.                      |
| `generate_blog_post`      | Generate a new AI-optimized blog post.                  |
| `update_blog_post`        | Update an existing blog post.                           |
| `publish_blog_post`       | Publish a blog post to your connected CMS.              |
| `delete_blog_post`        | Delete a blog post.                                     |
| `get_blog_gsc_metrics`    | Retrieve Google Search Console metrics for a blog post. |
| `get_blog_publish_status` | Check the publish status of a blog post.                |

### Google Search Console (GSC)

| Tool                  | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `get_gsc_connection`  | Check the GSC connection status for a domain.            |
| `get_gsc_dashboard`   | Retrieve GSC performance data.                           |
| `get_gsc_alerts`      | List active GSC alerts (ranking drops, traffic changes). |
| `mark_gsc_alert_read` | Mark a GSC alert as read.                                |

### GEO tasks

| Tool              | Description                      |
| ----------------- | -------------------------------- |
| `list_geo_tasks`  | List all GEO optimization tasks. |
| `get_geo_task`    | Retrieve a specific GEO task.    |
| `create_geo_task` | Create a new GEO task.           |
| `update_geo_task` | Update an existing GEO task.     |
| `delete_geo_task` | Delete a GEO task.               |

### Organisation

| Tool                   | Description                            |
| ---------------------- | -------------------------------------- |
| `get_organisation`     | Retrieve your organisation details.    |
| `list_members`         | List all members in your organisation. |
| `send_invite`          | Send a team invitation by email.       |
| `revoke_invite`        | Revoke a pending invitation.           |
| `list_pending_invites` | List all pending invitations.          |

### Settings & persona

| Tool                      | Description                                |
| ------------------------- | ------------------------------------------ |
| `get_content_settings`    | Retrieve your content generation settings. |
| `update_content_settings` | Update content generation settings.        |
| `get_persona`             | Retrieve your organisation's AI persona.   |
| `upsert_persona`          | Create or update the AI persona.           |

## Compatible clients

The Rankahead MCP server works with any client that supports the Model Context Protocol over HTTP.

<CardGroup cols={3}>
  <Card title="Claude Desktop" icon="bot" href="https://claude.ai/download">
    Add Rankahead as a custom MCP server in Claude Desktop settings.
  </Card>

  <Card title="Cursor" icon="code" href="https://cursor.com">
    Configure Rankahead MCP in your Cursor project's MCP settings.
  </Card>

  <Card title="Any MCP client" icon="plug">
    Any client that supports stateless HTTP MCP transport and JSON-RPC 2.0 will work.
  </Card>
</CardGroup>

<Tip>
  When configuring a client, set the server URL to `https://app.rankahead.ai/api/mcp` and supply your MCP token as the Bearer token. No other configuration is required.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/mcp/authentication">
    Learn how to create and use MCP tokens securely.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/tools/analytics">
    Browse the full per-tool documentation with input schemas and response examples.
  </Card>
</CardGroup>