MCP Server (Model Context Protocol)

The Model Context Protocol (MCP) is Anthropic's open standard that lets AI agents (Claude Desktop, Cursor, custom agents based on the Anthropic SDK) connect to external tool servers. Rankion exposes an MCP endpoint that surfaces the most important platform functions (tracking, backlinks, keywords, articles) as MCP tools — the agent calls them natively as JSON-RPC requests, without you orchestrating REST endpoints yourself.

Status: not yet rolled out. The MCP endpoint is in planning, expected at /mcp. Currently no route is registered in the code repo (routes/web.php, routes/api.php) — this article describes the planned behavior and tool layout. For productive AI-agent connections, use the REST API directly or the rankion-agent companion skill in the meantime.

Module context: Agentic Chat · auth basics: Auth API.

Endpoint

POST https://rankion.ai/mcp
Authorization: Bearer <SANCTUM_TOKEN>
Content-Type: application/json

Note: the exact path can change per deploy (/mcp or /mcp/v1). The current URL is confirmed in the settings area /settings/api-tokens or in the README of the mcp-server folder. Tokens are created in the UI under Settings → API Tokens — the same token used for REST calls also works for MCP.

What is MCP — quick summary

• Tools: executable functions the agent can call (get_tracking_scores, pull_backlinks, generate_article, ...).
• Resources: read-only data sources (e.g. project list, KB entries, wiki pages).
• Prompts: predefined prompt templates (e.g. "Competitor analysis for domain X").

Communication runs over JSON-RPC 2.0 — either via stdio (local process) or http (remote server, in our case HTTPS).

Connect with Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rankion": {
      "transport": "http",
      "url": "https://rankion.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RANKION_TOKEN"
      }
    }
  }
}

Restart Claude Desktop — the Rankion tools appear in the tool picker.

Connect with Cursor

In Cursor under Settings → MCP:

{
  "mcp.servers": {
    "rankion": {
      "url": "https://rankion.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_RANKION_TOKEN" }
    }
  }
}

Connect with custom agents (Anthropic SDK)

from anthropic import Anthropic

client = Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    mcp_servers=[{
        "type": "url",
        "url": "https://rankion.ai/mcp",
        "name": "rankion",
        "authorization_token": "YOUR_RANKION_TOKEN",
    }],
    messages=[
        {"role": "user", "content": "What is the AVI score for project 12?"}
    ],
)

Exposed tools (selection)

Tools split into two classes — read-only (free) and write/dispatch (consume credits, dispatch jobs).

Read-only tools

Write / dispatch tools

The agent loads the full list itself on connect via tools/list — no manual maintenance required.

JSON-RPC examples (raw)

tools/list

curl -X POST https://rankion.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/list"
  }'

tools/call

curl -X POST https://rankion.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params": {
      "name":"get_backlinks_summary",
      "arguments": { "domain":"example.com" }
    }
  }'

Response (excerpt):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"rank\":42,\"total_backlinks\":1240,\"referring_domains\":187,\"dofollow_ratio\":0.61,\"avg_spam_score\":12}" }
    ]
  }
}

Auth & scoping

• Sanctum token-based. The same token you use for the REST API.
• Team scoping is hard. Every tool call is validated against the token's team_id — cross-team access → JSON-RPC error -32603 with "forbidden".
• Rate limits identical to the REST API. 60 requests/minute per token.
• Credit consumption identical. Write tools deduct credits the same way as the corresponding REST call.

Notes & pitfalls

• MCP ≠ REST. MCP is JSON-RPC, not classic REST. Standard curl snippets do not apply 1:1.
• Streaming tools need SSE. Long-running tools (audit, tracking run) immediately return a job ID — the agent has to poll explicitly.
• Do not commit tokens to code. MCP tokens have full team scope. Keep them in .env or inject via secret manager.
• Companion skill for Claude Code: the rankion-agent skill (see repo) wraps MCP calls for workflow automation.

Related: Auth API · API overview · Agentic Chat.