Conseils & astuces de configuration — CMA en tant que serveur MCP

Choses qui ne sont pas évidentes dans la doc et qui coûtent du temps en débogage.

Modèle mental

Claude Desktop est le frontend, CMA est le backend

Le Claude auquel tu écris dans Desktop est un relais. Il appelle send_message avec tes paroles, appelle wait_for_idle pour bloquer jusqu'à la fin de l'agent CMA, puis t'affiche la réponse. Le travail réel — tool use, exécution de code, éditions de repo — se passe dans la session CMA, pas dans Desktop.

Huit outils 1:1, une shim

list_agents, get_agent, create_session, send_message, interrupt, get_session, list_events, archive_session sont des wrappers d'endpoint directs. wait_for_idle est la seule rédaction : MCP est request/response et la completion CMA est SSE, donc quelque chose doit stream-to-idle à l'intérieur d'un appel tool.

session_id est le seul état, et Claude le détient

create_session le retourne ; Claude le transmet à chaque appel suivant. Le serveur MCP lui-même est sans état.

Deux transports, un ensemble d'outils

src/tools.ts enregistre les neuf outils. src/server.ts l'enveloppe en stdio (Claude Desktop le lance comme sous-processus) ; src/server-http.ts l'enveloppe en HTTP Streamable (claude.ai web le rejoint via le réseau). Choisis l'un ou l'autre.

Configuration — Claude Desktop (stdio, local)

1. Environnement (une seule fois — les sessions ont besoin d'un environment_id) :

   ant beta:environments create --name cma-mcp \
     --config '{type: cloud, networking: {type: unrestricted}}' --transform id -r

2. Agents : ce serveur ne crée pas d'agents — il pilote ceux déjà dans ton workspace. Créez/mettez à jour via le CLI ant ou la Console.
3. .env.local :

   ANTHROPIC_API_KEY=sk-ant-...
   CLAUDE_ENVIRONMENT_ID=env_...

4. Enregistre avec Claude Desktop — ajoute à ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) et redémarre Desktop :

   {
     "mcpServers": {
       "cma": {
         "command": "bun",
         "args": ["run", "/absolute/path/to/managed_agents/cma-mcp/src/server.ts"],
         "env": {
           "ANTHROPIC_API_KEY": "sk-ant-...",
           "CLAUDE_ENVIRONMENT_ID": "env_..."
         }
       }
     }
   }

5. Test : dans un nouveau chat Desktop, demande « liste mes agents gérés, démarre une session avec le premier, et relaye ce message vers celui-ci : hello. »

Configuration — claude.ai web (HTTP Streamable, distant)

Mêmes outils, mais le serveur tourne sur une URL publique et claude.ai s'y connecte en tant que Connector personnalisé.

1. Token — génère-le et conserve-le ; quiconque possède ce token peut piloter tes agents :

   export CMA_MCP_TOKEN=$(openssl rand -hex 32)

2. Exécute localement d'abord (ngrok/cloudflared pour une URL publique pendant le test) :

   bun run http   # → :3000/mcp

3. Déploie — le Dockerfile cible Fly / Railway / Render ; définis ANTHROPIC_API_KEY, CLAUDE_ENVIRONMENT_ID, CMA_MCP_TOKEN comme secrets. (Cloudflare Workers fonctionne aussi — WebStandardStreamableHTTPServerTransport est fetch-natif ; remplace process.env → env et Bun.serve → export default { fetch }.)

4. claude.ai → Paramètres → Connectors → Ajouter un connector personnalisé :

   Champ	Valeur
   Nom	CMA
   URL	https://<ton-deploy>/mcp
   Authentification	Bearer token → ton CMA_MCP_TOKEN

   Orgs Équipe / Entreprise : ajouter un connector par URL est généralement réservé aux admins org — les utilisateurs individuels voient un répertoire curé, pas un champ URL. Un admin ajoute l'URL + token une fois dans les paramètres org ; il apparaît ensuite dans la liste Connectors de chaque membre pour activation. (C'est la forme que tu veux pour déployer vers des utilisateurs non techniques de toute façon.)

5. Test : nouveau chat → active le connector CMA → même prompt qu'en haut.

Mode relais (instructions de Projet recommandées)

Sans orientation, le Desktop Claude essaiera de répondre lui-même plutôt que de relayer. Mets ceci dans les instructions personnalisées d'un Projet :

Tu es un frontend pour un backend Managed Agent atteint via les outils MCP cma. Au premier tour utilisateur : list_agents (si nécessaire) → create_session → send_message(texte utilisateur littéralement) → wait_for_idle → retourne la reply littéralement. Aux tours suivants : send_message → wait_for_idle. Ne réponds pas à partir de tes propres connaissances ; ne reformule pas la réponse du backend. Si wait_for_idle retourne status: "timeout", dis à l'utilisateur que c'est encore en cours et offre-toi à continuer d'attendre.

Pièges

stdio = Desktop seulement ; HTTP = l'internet

Le navigateur claude.ai ne peut pas lancer un processus local, donc stdio ne fonctionne qu'avec Claude Desktop / Claude Code. Le chemin HTTP te donne claude.ai web, mais maintenant l'URL est publique — le bearer token est la seule barrière devant ta clé ANTHROPIC_API_KEY et le quota CMA. Ne déploie pas sans, ne la journalise pas, fais-la tourner comme n'importe quelle clé API.

Longs tours vs timeout tool

wait_for_idle bloque. Si l'agent CMA tourne pendant des minutes (gros clone de repo, nombreux appels tool), le client MCP peut timeout l'appel tool. Atténuations : passe un timeout_sec plus petit et boucle (wait_for_idle retourne status: "timeout" + last_event_id ; appelle à nouveau), ou fais que Claude interroge get_session + list_events(after_id=...) à la place.

Facturation

Tout usage CMA facture la clé ANTHROPIC_API_KEY intégrée dans la config serveur — pas au compte de l'utilisateur Desktop. C'est le point (utilisateurs non techniques, pas de clés), mais dimensionne les limites du workspace de la clé en conséquence.

Délibérément non exposés

Ajouter l'un d'eux, c'est quelques lignes dans src/cma.ts + src/server.ts si ton cas d'usage en a besoin.

Débogage