Servidor MCP (Model Context Protocol)

El Model Context Protocol (MCP) es el estándar abierto de Anthropic con el que los AI agents (Claude Desktop, Cursor, custom agents sobre el SDK de Anthropic) se conectan a servidores de tools externos. Rankion ofrece un endpoint MCP que expone las funciones clave de la plataforma (Tracking, Backlinks, Keywords, Articles) como tools MCP — el agent las invoca nativamente como llamadas JSON-RPC, sin que tengas que orquestar tú los endpoints REST.

Estado: aún no desplegado. El endpoint MCP está en planificación, previsiblemente bajo /mcp. Actualmente, en el repo de código (routes/web.php, routes/api.php), no hay ruta registrada — este artículo describe el comportamiento previsto y el layout de tools. Para integraciones AI agent en producción, usa hasta entonces la API REST directa o el skill compañero rankion-agent.

Contexto del módulo: Agentic Chat · fundamentos de auth: API de Auth.

Endpoint

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

Nota: el path exacto puede cambiar según el deploy (/mcp o /mcp/v1). La URL actual la confirma la sección Settings /settings/api-tokens o el README de la carpeta mcp-server. Los tokens se crean en la UI bajo Settings → API Tokens — el mismo token que usas para REST sirve también para MCP.

¿Qué es MCP — en breve?

• Tools: funciones ejecutables que el agent puede invocar (get_tracking_scores, pull_backlinks, generate_article, ...).
• Resources: fuentes de datos read-only (p. ej. lista de proyectos, entradas KB, páginas Wiki).
• Prompts: plantillas de prompt predefinidas (p. ej. «Análisis de competencia para el dominio X»).

La comunicación corre sobre JSON-RPC 2.0 — bien por stdio (proceso local) o por http (servidor remoto, en nuestro caso HTTPS).

Conectar con 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"
      }
    }
  }
}

Reinicia Claude Desktop — las tools de Rankion aparecen en el tool picker.

Conectar con Cursor

En Cursor bajo Settings → MCP:

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

Conectar con 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?"}
    ],
)

Tools expuestas (selección)

Las tools se dividen en dos clases — read-only (gratis) y write/dispatch (consumen créditos, dispatchan jobs).

Tools read-only

Tools write / dispatch

La lista completa la carga el agent al conectar mediante tools/list — sin mantenimiento manual.

Ejemplos JSON-RPC (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 (extracto):

{
  "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 y scoping

• Basado en token Sanctum. El mismo token que usas para la API REST.
• Team-scoping es duro. Cada tool call se valida contra el team_id del token — un acceso cross-team → JSON-RPC error -32603 con "forbidden".
• Rate limits idénticos a la API REST. 60 requests/minuto por token.
• Consumo de créditos idéntico. Las tools de escritura cobran créditos exactamente igual que la llamada REST equivalente.

Notas y pitfalls

• MCP ≠ REST. MCP es JSON-RPC, no REST clásico. Los snippets curl estándar no aplican 1:1.
• Las tools streaming necesitan SSE. Las tools long-running (audit, tracking run) devuelven inmediatamente un job ID — el agent debe hacer polling explícito.
• No commitear tokens. Los tokens MCP llevan el scope completo del team. Mantén en .env o inyecta vía secret manager.
• Skill compañero para Claude Code: el skill rankion-agent (ver repo) envuelve llamadas MCP para automatización de workflows.

Relacionado: API de Auth · Visión general de la API · Agentic Chat.