Connecter un MCP server hébergé à votre workspace

Coffrify héberge un MCP server public accessible à l'adresse mcp.coffrify.com. L'endpoint de contrôle /api/v1/mcp/hosted/{workspaceId} est la surface authentifiée qui permet à votre application, à votre agent IA ou au routeur hébergé de vérifier la disponibilité du server, d'obtenir les URL de transport (streamable-http et sse), de récupérer le catalogue des outils disponibles et d'initialiser une session JSON-RPC conforme à la spécification MCP 2024-11-05. Toutes les réponses incluent l'en-tête X-Coffrify-MCP-Hosted: control-v1 pour distinguer ce plan de contrôle du trafic MCP proprement dit.

Authentification

L'endpoint exige un Bearer token dans l'en-tête Authorization. Trois familles de clés sont acceptées : les clés API complètes (cof_live_… / cof_test_… / cof_sandbox_…), les clés restreintes (cof_rk_live_…) et les MCP tokens (cof_mcp_live_… / cof_mcp_test_… / cof_mcp_sandbox_…). Pour un usage en production depuis un agent ou un client MCP, nous recommandons de provisionner un MCP token dédié via POST /v1/mcp/tokens : le token est lié à un client_hint (claude-desktop, claude, cursor, cline, continue ou custom), limitable en IP et en nombre d'utilisations. Le handler vérifie ensuite que le workspace_id encodé dans l'URL correspond au workspace du token : un token appartenant au workspace ws_A ne peut pas interroger l'endpoint du workspace ws_B (erreur 403 forbidden). Aucun scope spécifique n'est requis par cet endpoint de contrôle : le scope * accordé par une session dashboard ou un token large-scope est suffisant.

Paramètre de chemin

Corps de la requête (POST)

En POST, le corps est un objet JSON-RPC 2.0. Le champ method détermine le comportement du server. Si le corps est absent ou si method ne correspond à aucune méthode reconnue, le payload de contrôle standard est renvoyé.

# GET - vérifier l'état du MCP server hébergé
curl -s https://api.coffrify.com/v1/mcp/hosted/YOUR_WORKSPACE_ID \
  -H "Authorization: Bearer cof_mcp_live_..."
 
# POST - handshake initialize JSON-RPC
curl -s -X POST https://api.coffrify.com/v1/mcp/hosted/YOUR_WORKSPACE_ID \
  -H "Authorization: Bearer cof_mcp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

Réponse (GET)

Le GET retourne un objet mcp_hosted_endpoint décrivant l'état du server hébergé pour votre workspace, les URL de transport et le catalogue d'outils.

{
  "object": "mcp_hosted_endpoint",
  "status": "available",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transport": "streamable-http",
  "spec_version": "2024-11-05",
  "endpoints": {
    "streamable_http": "https://mcp.coffrify.com/u/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sse": "https://mcp.coffrify.com/sse",
    "local_fallback": "npx @coffrify/mcp"
  },
  "catalog": {
    "tools": 207,
    "families": 38,
    "disabled_by_default": 0
  },
  "authenticated_as": "cof_mcp_live_a1b2c3d4...",
  "scopes": ["transfers:read", "transfers:write", "webhooks:read"]
}

Réponse (POST initialize)

Le POST avec method: "initialize" retourne une réponse JSON-RPC 2.0 conforme à la spec MCP 2024-11-05, incluant les capacités du server et le payload de contrôle Coffrify dans le champ coffrify.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "coffrify-hosted",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "coffrify": {
      "object": "mcp_hosted_endpoint",
      "status": "available",
      "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "transport": "streamable-http",
      "spec_version": "2024-11-05",
      "endpoints": {
        "streamable_http": "https://mcp.coffrify.com/u/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "sse": "https://mcp.coffrify.com/sse",
        "local_fallback": "npx @coffrify/mcp"
      },
      "catalog": {
        "tools": 207,
        "families": 38,
        "disabled_by_default": 0
      },
      "authenticated_as": "cof_mcp_live_a1b2c3d4...",
      "scopes": ["transfers:read", "transfers:write"]
    }
  }
}

Réponse (POST tools/list)

Le POST avec method: "tools/list" retourne le catalogue complet des 207 outils MCP Coffrify. Chaque outil inclut son name, sa description et un inputSchema JSON Schema. Cette réponse est destinée aux clients MCP qui souhaitent découvrir les outils avant d'ouvrir la connexion Streamable HTTP.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "coffrify_list_transfers",
        "description": "Lister tous les transferts du workspace, avec pagination cursor.",
        "inputSchema": { "type": "object", "properties": {} }
      },
      {
        "name": "coffrify_create_transfer",
        "description": "Créer un nouveau transfert (presigned upload URLs).",
        "inputSchema": { "type": "object", "properties": {} }
      }
    ]
  }
}

Erreurs

Voir aussi

• Créer un MCP token
• Catalogue complet des outils MCP
• Créer une clé API avec scopes
• Rotation d'un secret Webhook
• Diagnostic et checklist d'intégration