Serveur MCP

En bref

Brancher un client

Le serveur se déclare par son adresse, et la clé par un en-tête.

claude mcp add \
  --transport http subagent \
  https://api.subagent.fr/mcp \
  --header "Authorization: Bearer $SUBAGENT_KEY"

{
  "mcpServers": {
    "subagent": {
      "url": "https://api.subagent.fr/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUBAGENT_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "subagent": {
      "type": "http",
      "url": "https://api.subagent.fr/mcp",
      "headers": {
        "Authorization": "Bearer ${SUBAGENT_KEY}"
      }
    }
  }
}

Pas encore de clé : déclarez l’adresse sans en-tête, laissez l’agent appeler sign_up, puis ajoutez l’en-tête. Voir Démarrer.

Un assistant en ligne (Claude, ChatGPT) ne déclare pas d’en-tête : il se branche à https://api.subagent.fr/connect, où l’humain se connecte avec son e-mail. Voir Connecteur. Client par client : Brancher mon agent.

Sans clé

À l’adresse https://api.subagent.fr/mcp, sans en-tête d’autorisation, le serveur répond quand même, pour l’inscription. À l’adresse https://api.subagent.fr/connect, il répond 401 : l’assistant ouvre alors la page de connexion.

• Il sert initialize, ping, tools/list et tools/call.
• tools/list rend un seul outil : sign_up.
• Il n’ouvre pas de session et ne sert pas les vues.
• L’appel d’un autre outil est refusé avec le code unauthorized. Toute autre méthode reçoit le statut HTTP 401.

Le serveur lit l’en-tête à chaque requête. Après sign_up, la connexion ouverte sans clé ne montre toujours que sign_up : il faut présenter la clé. Voir Clés et permissions.

Avec une clé

• tools/list rend les outils que les permissions de la clé ouvrent. sign_up n’y figure plus.
• Une fois l’espace vérifié, verify et attach_human quittent la liste.
• Une clé présentée mais inconnue ou révoquée reçoit le statut HTTP 401.

Le résultat d’un outil

Un appel réussi rend trois choses.

{
  "content": [{ "type": "text", "text": "Message msg_… en file dans le fil thr_… : …" }],
  "structuredContent": { "message": {}, "thread": {}, "inbox": {}, "replayed": false, "estimated_send_at": "2026-10-13T14:31:00+02:00" },
  "isError": false
}

• content : un texte lisible en français. Il dit qui, quoi, quand, et le quota restant.
• structuredContent : l’objet de l’outil, dont le schéma est publié dans https://api.subagent.fr/openapi.json. C’est lui qu’un programme lit.
• isError : false.

Le texte lisible coupe le corps d’un message à 2 000 caractères. Le corps entier est dans structuredContent.

Un refus

Un refus du service n’est pas une erreur de protocole. C’est un résultat d’outil marqué isError, avec un texte : le message, le code entre parenthèses, puis la piste après une flèche.

approve_message demande la permission approve, que cette clé n’a pas. (code forbidden)
→ La validation est un geste humain : votre humain l’accomplit depuis son assistant (Claude, ChatGPT…), branché à l’adresse https://api.subagent.fr/connect où il se connecte avec son e-mail.

Par MCP, un refus n’a pas d’objet structuré : le code se lit dans le texte, entre parenthèses, après le mot « code ». En HTTP, le même refus est un objet {"error": {"code", "message", "hint"}}. Voir Erreurs.

Ce que chaque outil annonce

Dans tools/list, chaque outil porte :

• name, title et description, en français ;
• inputSchema : ses paramètres. Un paramètre inconnu est refusé. tools/list ne porte pas de schéma de sortie (outputSchema) ;
• annotations : readOnlyHint (l’outil ne fait que lire), destructiveHint (son effet ne se défait pas), idempotentHint ;
• _meta.ui.resourceUri, s’il a une vue.

Le schéma de l’objet structuré de chaque outil se lit dans https://api.subagent.fr/openapi.json.

Protocole

Sans MCP

Chaque outil existe aussi en POST https://api.subagent.fr/v1/{opération}, avec les mêmes arguments et le même objet en réponse. Voir API HTTP.