Serveur MCP (Model Context Protocol)

Le Model Context Protocol (MCP) est le standard ouvert d'Anthropic permettant aux agents IA (Claude Desktop, Cursor, agents custom basés sur le SDK Anthropic) de se connecter à des serveurs d'outils externes. Rankion propose un endpoint MCP qui expose les principales fonctions de la plateforme (Tracking, Backlinks, Mots-clés, Articles) en tant qu'outils MCP — l'agent les invoque nativement par appels JSON-RPC, sans que tu aies à orchestrer toi-même les endpoints REST.

Statut : pas encore déployé. L'endpoint MCP est en planification, prévu sous /mcp. Actuellement, dans le repo de code (routes/web.php, routes/api.php), aucune route n'est enregistrée — cet article décrit le comportement et le layout d'outils prévus. Pour la connexion d'agents IA en production, utilise d'ici là directement la REST API ou le skill compagnon rankion-agent.

Contexte du module : Agentic Chat · Bases auth : API Auth.

Endpoint

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

Note : le path exact peut varier selon le déploiement (/mcp ou /mcp/v1). L'URL courante est confirmée dans la zone Settings /settings/api-tokens ou dans le README du dossier mcp-server. Les tokens se créent dans l'UI sous Settings → API Tokens — le même token utilisé pour les appels REST vaut aussi pour MCP.

Qu'est-ce que MCP — en bref

• Tools : fonctions exécutables que l'agent peut appeler (get_tracking_scores, pull_backlinks, generate_article, ...).
• Resources : sources de données en lecture seule (par ex. liste de projets, entrées KB, pages wiki).
• Prompts : templates de prompts prédéfinis (par ex. « Analyse de concurrence pour le domaine X »).

La communication passe par JSON-RPC 2.0 — soit via stdio (processus local), soit via http (serveur distant, dans notre cas en HTTPS).

Connexion avec 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"
      }
    }
  }
}

Redémarre Claude Desktop — les outils Rankion apparaissent dans le picker d'outils.

Connexion avec Cursor

Dans Cursor sous Settings → MCP :

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

Connexion avec des agents custom (SDK Anthropic)

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

Outils exposés (sélection)

Les outils sont répartis en deux classes — read-only (gratuits) et write/dispatch (consomment des crédits, dispatchent un job).

Outils read-only

Outils write / dispatch

La liste complète est chargée par l'agent à la connexion via tools/list — pas de maintenance manuelle nécessaire.

Exemples 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" }
    }
  }'

Réponse (extrait) :

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

• Basé sur token Sanctum. Le même token que pour la REST API.
• Le scoping par équipe est strict. Chaque appel d'outil est validé contre le team_id du token — accès cross-team → erreur JSON-RPC -32603 avec "forbidden".
• Rate-limits identiques à la REST API. 60 requêtes/minute par token.
• Consommation de crédits identique. Les outils write consomment des crédits exactement comme l'appel REST correspondant.

Notes & pièges

• MCP ≠ REST. MCP est du JSON-RPC, pas du REST classique. Les snippets curl standards ne s'appliquent pas 1:1.
• Les outils streaming nécessitent SSE. Les outils long-running (audit, run de tracking) renvoient immédiatement un job ID — l'agent doit poller explicitement.
• Ne jamais commit de token dans le code. Les tokens MCP ont le scope complet de l'équipe. Garde-les en .env ou injecte-les via gestionnaire de secrets.
• Skill compagnon pour Claude Code : le skill rankion-agent (voir le repo) wrappe les appels MCP pour l'automatisation de workflow.

Voir aussi : API Auth · Vue d'ensemble API · Agentic Chat.