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

1. Initialize the connection

   Send an initialize request to confirm the server is reachable and check the protocol version.

   curl

   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": {}
     }'
   

   Response

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

   Call tools/list to retrieve every tool the server exposes, including their input schemas.

   curl

   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": {}
     }'
   
3. Call a tool

   Use tools/call to execute a specific tool. Pass the tool name and any required arguments in params.

   curl

   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:

   Response

   {
     "jsonrpc": "2.0",
     "id": 3,
     "result": {
       "content": [
         {
           "type": "text",
           "text": "{\"visibilityScore\": 72, ...}"
         }
       ]
     }
   }
   

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.

Claude Desktop

Add Rankahead as a custom MCP server in Claude Desktop settings.

Cursor

Configure Rankahead MCP in your Cursor project’s MCP settings.

Any MCP client

Any client that supports stateless HTTP MCP transport and JSON-RPC 2.0 will work.

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.

Next steps

Authentication

Learn how to create and use MCP tokens securely.

Tool reference

Browse the full per-tool documentation with input schemas and response examples.