MCP Server (Model Context Protocol)

Das Model Context Protocol (MCP) ist Anthropics offener Standard, mit dem AI-Agents (Claude Desktop, Cursor, Custom-Agents auf Basis des Anthropic-SDK) sich an externe Tool-Server anbinden. Rankion stellt einen MCP-Endpoint bereit, der die wichtigsten Plattform-Funktionen (Tracking, Backlinks, Keywords, Articles) als MCP-Tools exposed — der Agent ruft sie nativ als JSON-RPC-Calls auf, ohne dass du selbst REST-Endpoints orchestrieren musst.

Status: noch nicht ausgerollt. Der MCP-Endpoint ist in Planung, voraussichtlich unter /mcp. Aktuell ist im Code-Repo (routes/web.php, routes/api.php) keine Route registriert — dieser Artikel beschreibt das geplante Verhalten und Tool-Layout. Für produktive AI-Agent-Anbindung nutze bis dahin die REST-API direkt oder den rankion-agent Companion-Skill.

Modul-Kontext: Agentic Chat · Auth-Grundlagen: Auth-API.

Endpoint

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

Hinweis: Der genaue Pfad kann sich je nach Deploy ändern (/mcp oder /mcp/v1). Aktuelle URL bestätigt der Settings-Bereich /settings/api-tokens oder die README im mcp-server-Ordner. Tokens werden im UI unter Settings → API Tokens angelegt — derselbe Token, der für REST-Calls verwendet wird, gilt auch für MCP.

Was ist MCP — kurz

• Tools: ausführbare Funktionen, die der Agent aufrufen kann (get_tracking_scores, pull_backlinks, generate_article, ...).
• Resources: read-only Daten-Quellen (z.B. Projekt-Liste, KB-Einträge, Wiki-Pages).
• Prompts: vordefinierte Prompt-Templates (z.B. "Konkurrenz-Analyse für Domain X").

Kommunikation läuft über JSON-RPC 2.0 — entweder per stdio (lokaler Prozess) oder per http (remote Server, in unserem Fall HTTPS).

Verbinden mit 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"
      }
    }
  }
}

Claude Desktop neu starten — die Rankion-Tools erscheinen im Tool-Picker.

Verbinden mit Cursor

In Cursor unter Settings → MCP:

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

Verbinden mit 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": "Wie ist der AVI-Score für Projekt 12?"}
    ],
)

Exposed Tools (Auswahl)

Tools sind in zwei Klassen aufgeteilt — read-only (kostenlos) und write/dispatch (verbrauchen Credits, Job-dispatchend).

Read-only Tools

Write / Dispatch Tools

Die vollständige Liste lädt der Agent beim Connect via tools/list selbst — kein manuelles Pflegen nötig.

JSON-RPC-Beispiele (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 (Auszug):

{
  "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-basiert. Derselbe Token, den du für die REST-API nutzt.
• Team-Scoping ist hart. Jeder Tool-Call wird gegen team_id des Tokens validiert — Cross-Team-Zugriff → JSON-RPC-Error -32603 mit "forbidden".
• Rate-Limits identisch zur REST-API. 60 Requests/Minute pro Token.
• Credit-Verbrauch identisch. Write-Tools ziehen Credits genauso wie der zugehörige REST-Call.

Hinweise & Pitfalls

• MCP ≠ REST. MCP ist JSON-RPC, kein klassisches REST. Standard-curl-Snippets gelten nicht 1:1.
• Streaming-Tools brauchen SSE. Tools die long-running sind (Audit, Tracking-Run) returnen sofort eine Job-ID — der Agent muss explizit pollen.
• Token nicht in Code committen. MCP-Tokens haben den vollen Team-Scope. In .env halten oder via Secret-Manager injecten.
• Companion-Skill für Claude Code: rankion-agent Skill (siehe Repo) wrappt MCP-Calls für Workflow-Automation.

Verwandt: Auth-API · API-Übersicht · Agentic Chat.