Dialoguer en JSON-RPC avec le serveur MCP hébergé

Traite les messages JSON-RPC MCP (initialize, tools/list, ping) pour le serveur hébergé du workspace.

Requête exemple

{
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    },
    "protocolVersion": "2024-11-05"
  },
  "jsonrpc": "2.0"
}

Réponse exemple

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

POST/v1/mcp/hosted/{workspaceId}Point d'entrée JSON-RPC du serveur MCP hébergé : handshake et découverte d'outils.

Ce POST traite les messages JSON-RPC 2.0 du protocole MCP pour le serveur hébergé du workspace. Trois méthodes sont reconnues : initialize (handshake, renvoie serverInfo + capabilities + un bloc coffrify), tools/list (catalogue d'outils MCP exposés) et ping (réponse vide pour le keep-alive). Toute autre méthode (ou un corps sans method) retourne le descriptif du point d'accès hébergé (identique au payload du GET). Le corps est parsé de façon tolérante : un JSON invalide est traité comme null et tombe sur ce comportement par défaut. Toutes les réponses sont 200 et portent l'en-tête X-Coffrify-MCP-Hosted: control-v1.

Authentification

Comme pour le GET, une clé API valide suffit, aucun scope spécifique n'est exigé par ce point d'accès. Fournissez Authorization: Bearer ... avec un préfixe accepté (cof_live_, cof_test_, cof_rk_*, cof_mcp_*). Le workspaceId du token doit correspondre au {workspaceId} de l'URL, sinon 403 forbidden. Note : ce point d'accès de contrôle ne vérifie pas, par outil, le scope required_scope du catalogue ; ces scopes sont enforced lors de l'exécution réelle des outils sur le transport hébergé mcp.coffrify.com.

Corps de la requête

Champ	Type	Requis	Description
jsonrpc	string	Recommandé	Version JSON-RPC ; doit valoir "2.0" selon la spec MCP.
id	number \| string \| null	Non	Identifiant de corrélation ; renvoyé tel quel (ou null si absent).
method	string	Non	Méthode MCP : "initialize", "tools/list" ou "ping". Toute autre valeur (ou champ absent) renvoie le descriptif du point d'accès.
params	object	Non	Paramètres de la méthode (ex. protocolVersion, clientInfo pour initialize). Non strictement validés par ce point de contrôle.

Réponse

Pour initialize : enveloppe { jsonrpc, id, result } avec result.protocolVersion: "2024-11-05", result.serverInfo (name: "coffrify-hosted", version: "1.0.0"), result.capabilities (tools, resources, prompts) et un bloc result.coffrify reprenant le descriptif complet du point d'accès. Pour tools/list : result.tools est un tableau d'objets { name, description, inputSchema }, où inputSchema est un squelette { type: "object", properties: {} }. Pour ping : result est un objet vide {}. Pour toute autre méthode : l'objet mcp_hosted_endpoint brut (sans enveloppe JSON-RPC).

Erreurs

Code	Quand	Résolution
401 invalid_api_key	Token absent, préfixe non reconnu, ou introuvable.	Présentez un Bearer valide (cof_live_, cof_test_, cof_rk_, cof_mcp_).
401 revoked_api_key	Token révoqué ou désactivé.	Émettez un nouveau token MCP depuis app.coffrify.com/mcp.
401 expired_api_key	Token expiré.	Renouvelez le token.
403 forbidden	Le workspace du token ne correspond pas à l'URL.	Utilisez le token émis pour ce workspace.
403 ip_not_allowed	IP appelante hors allowlist du token.	Appelez depuis une IP autorisée.
429 rate_limited	Limite d'usages du token atteinte.	Réessayez plus tard ou émettez un token sans plafond d'usages.
500 internal_error	Exception interne (RPC de validation, etc.).	Réessayez ; contactez le support si persistant.

Voir aussi

GET /v1/mcp/hosted/{workspaceId} — sonde de santé et descriptif du point d'accès hébergé.
GET /v1/mcp/tokens — lister les tokens MCP du workspace et leurs scopes.
POST /v1/mcp/tokens — émettre un token MCP scoppé pour ce serveur hébergé.