Skip to main content
Glama

mcp-agent-harness

Un provider de mcp-broker qui publie les agents de code locaux, Codex d'abord puis Claude Code, chacun dans son propre slot (codex, claude). Les slots partagent un contrat MCP commun, asynchrone par construction : démarrer un thread, le suivre par abonnement ou par long-poll, répondre aux approbations, le reprendre depuis un autre client.

Statut : lots 1 et 2a. Le contrat agent/v0, le journal, les approbations, les propriétés, le raccordement au broker, l'état dans mcp-persistence, les secrets dans mcp-vault et l'adaptateur Codex (App Server, connexion par clé ou par ChatGPT) sont faits et testés. Restent le lot 2b (fork, reprise des threads après redémarrage du provider), Claude (lot 3) et l'autorisation (lot 4). Voir l'ADR-0001.

En bref

  • Un provider, pas un client : il occupe des slots, et les clients MCP s'y connectent en http://<hôte>/<slot>/mcp.

  • Aucun appel bloquant : le broker coupe une requête au bout de 60 s, alors qu'un turn d'agent dure des minutes.

  • Le provider est la source de vérité : un threadId explicite, indépendant de toute session MCP.

  • Les approbations sont un état : le broker ne relaie pas les requêtes du serveur vers le client.

  • Les valeurs par défaut sont des propriétés réglables par contrat, dans des bornes fixées par l'opérateur.

  • Hors de _all, et sur un slot protégé : ce provider exécute du code sur le poste.

Related MCP server: t3code-mcp

Le slot codex

Codex 0.170.0 (npm install -g @openai/codex@0.170.0). Une autre version est refusée tant qu'elle n'est pas testée, sauf codex.allowUntestedVersion.

Le slot a son propre CODEX_HOME (codex.home), jamais votre ~/.codex : il ne touche ni à votre configuration ni à votre connexion Codex personnelles. Deux façons de le connecter :

Avec votre compte ChatGPT (examples/codex.chatgpt.config.json). Démarrez le provider, puis, depuis un client MCP connecté au slot :

  1. codex_login_start { "method": "browser" } rend authUrl. Ouvrez-la dans un navigateur sur la machine où tourne le provider : le retour de connexion arrive sur un port local de cette machine. Ou { "method": "deviceCode" } : une URL et un code à saisir, depuis n'importe quel appareil.

  2. codex_account confirme : loggedIn: true, le compte, la formule.

Codex garde les jetons dans codex.home ("store": "file") ou dans le trousseau du système ("keyring"). La connexion survit aux redémarrages. codex_logout la retire.

Avec une clé API dans mcp-vault (examples/codex.vault.config.json). La clé est lue dans le vault à chaque démarrage de Codex et lui est passée par stdio. Codex tourne alors avec un stockage éphémère : la clé n'est jamais écrite sur disque, ni dans un environnement que les commandes de l'agent pourraient lire. codex_login_start est refusé dans ce mode : on change la clé dans le vault.

Dans les deux cas, Codex ne reçoit jamais le secret du provider ni le bearer client : le provider les retire de son environnement.

Questions de Codex. Les formulaires des serveurs MCP que Codex utilise sont relayés par défaut. Les questions en milieu de turn demandent une fonction que Codex 0.170.0 marque « under development » : "enableFeatures": ["default_mode_request_user_input"] dans la section codex. Sans elle, Codex pose ses questions dans son message de fin de turn.

codex.command vaut codex (sur le PATH) par défaut. Sous Windows, si codex n'est qu'un raccourci .cmd, préférez le chemin du bin/codex.js du paquet npm, que le provider lance avec son propre Node.

tool natif

rôle

codex_account

mode de connexion, compte, connexion en cours, résultat de la dernière ; jamais de secret

codex_login_start

connexion ChatGPT : browser ou deviceCode

codex_login_cancel, codex_logout

annule la connexion en cours ; déconnecte le slot

codex_thread_archive

archive un thread dans Codex ; il ne prend plus de turn

Essayer avec le moteur factice

Node 22 ou plus récent. Un broker sur le port 3000 :

npx @cyanmycelium/mcp-broker

Le provider, depuis ce dépôt :

npm install
npm run build
node dist/bin.js --config examples/fake.config.json

Le slot est alors http://127.0.0.1:3000/fake/mcp. Dans Claude Code (.mcp.json) :

{
    "mcpServers": {
        "fake-agent": { "type": "http", "url": "http://127.0.0.1:3000/fake/mcp" }
    }
}

Le moteur factice répète le prompt. Un prompt qui contient run, command ou approval demande d'abord une approbation.

Le contrat agent/v0

tool

rôle

agent_start

démarre un thread sur un répertoire ; rend threadId tout de suite

agent_send

nouveau turn sur un thread au repos

agent_wait

long-poll : les événements après sinceSeq, dès qu'il y en a, ou au bout de timeoutMs

agent_approve

répond à une approbation en attente (accept, acceptForSession, decline)

agent_answer

répond à une question de l'agent en attente (état awaiting_input)

agent_interrupt

arrête le turn en cours ; le thread reste

agent_list

les threads du slot

agent_property_get / agent_property_set

lit et règle les propriétés, par slot ou par thread

ressource

contenu

agent://threads

la liste des threads

agent://threads/{threadId}

un thread : état, approbations et questions en attente, derniers événements, lastSeq

agent://properties

les propriétés : défaut, bornes, portées, valeur du slot

Les trois ressources sont abonnables : chaque changement envoie notifications/resources/updated sur l'URI exacte. Un refus est un résultat isError lisible par le modèle, { error: { code, message, detail? } } ; les codes sont dans l'ADR.

Converser avec l'agent

Le client d'un slot est souvent un autre agent. Deux façons de lui répondre :

  • À la fin d'un turn, l'agent a dit quelque chose, parfois une question : agent_send lui répond, c'est le turn suivant.

  • Au milieu d'un turn, l'agent pose une question et attend : le thread passe en awaiting_input, la question est dans pendingQuestions (ses options, ou le formulaire d'un serveur MCP, ou une page à visiter), et agent_answer y répond. Sans réponse, elle est déclinée au bout de inputTimeoutMs.

Une question marquée secrète n'est pas relayée, sauf allowSecretQuestions : passez plutôt le secret par mcp-vault.

Boucle type d'un client :

agent_start { cwd, prompt }                  -> { threadId, turnId, state: "running" }
agent_wait  { threadId, sinceSeq: 0 }        -> { events, lastSeq: 3, state: "awaiting_approval", pendingApprovals }
agent_approve { threadId, approvalId, decision: "accept" }
agent_wait  { threadId, sinceSeq: 3 }        -> { events, lastSeq: 7, state: "idle" }

Configuration

Le fichier passé à --config. Les chemins relatifs partent du fichier. Une clé inconnue arrête le démarrage.

clé

rôle

broker

URL WebSocket du broker. Défaut ws://127.0.0.1:3000. Le provider se connecte à <broker>/provider/<slot>

slot

slot publié. Défaut : le nom du moteur

engine

codex, ou fake pour essayer le contrat sans agent

codex

avec engine: "codex" : command, home (le CODEX_HOME du slot, requis), auth ({ "mode": "apiKey", "apiKey": <référence vault> } ou { "mode": "chatgpt", "store"?: "file" | "keyring" }), model, allowUntestedVersion, requestTimeoutMs, enableFeatures (fonctions de Codex à activer)

secretEnv

nom de la variable d'environnement qui contient le secret du provider. Un secret en clair est refusé

clientTokenEnv

nom de la variable qui contient le bearer avec lequel le harness appelle les slots persistence et vault. Requis par state.persistence et credentials

workspaceRoots

répertoires où un thread peut travailler. Un cwd hors de ces racines est refusé

sandbox, approvalPolicy

{ default, ceiling } : ce qu'un client obtient sans rien demander, et le plus qu'il peut demander

properties

bornes par propriété : { "<nom>": { default?, min?, max? } }

waitCeilingMs

plafond de waitMaxMs. Défaut 50 000. Doit rester sous le providerRequestTimeoutMs du broker (60 000 par défaut), que le provider ne peut pas lire

state

où les propriétés de portée slot survivent au redémarrage : { "file": "<chemin>" } (développement, poste isolé) ou { "persistence": { slot?, namespace? } } (un document mcp-persistence). Absent : en mémoire

credentials

{ "vault": { slot?, prefix?, vaultKid? } } : le slot mcp-vault d'où viennent les secrets des moteurs, et le préfixe sous lequel le harness peut lire (agent-harness par défaut)

allowSecretQuestions

relaie les questions que l'agent marque secrètes. Désactivé par défaut : leur réponse traverserait le broker en clair

engineSecrets

variable d'environnement du moteur vers référence vault : { "OPENAI_API_KEY": { "slot": "vault", "path": "agent-harness/openai", "key": "apiKey" } }. Résolues au démarrage ; une seule manquante arrête le démarrage

Avec les slots de la famille

En production, l'état et les secrets passent par les slots mcp-persistence et mcp-vault du même broker (ADR, D12). Voir examples/family.config.json. Il faut installer les deux paquets, dépendances optionnelles de celui-ci :

npm install @cyanmycelium/mcp-persistence @cyanmycelium/mcp-vault
  • État : un document properties.<slot> dans le namespace agent-harness. Chaque écriture porte la révision lue : si une autre instance a écrit entre-temps, la modification est refusée (state_conflict) et l'état rechargé, jamais écrasé. Si le slot est injoignable, rien ne change (store_unavailable).

  • Secrets : lus scellés de bout en bout, pour une paire de clés neuve à chaque processus. Le broker ne voit que du chiffré, et les valeurs ne vont qu'au moteur.

  • Politique du broker pour l'identité du bearer client : persistence.read et persistence.write sur son namespace, vault.read sous son préfixe, rien d'autre.

propriété

défaut

bornes par défaut

portées

approvalTimeoutMs

900 000

10 000 à 86 400 000

slot, thread

inputTimeoutMs

900 000

10 000 à 86 400 000

slot, thread

waitDefaultMs

25 000

1 000 à waitMaxMs

slot, thread

waitMaxMs

45 000

1 000 à waitCeilingMs

slot

journalMaxEvents

1 000

100 à 100 000

slot

Sécurité

Ce slot fait exécuter du code sur le poste. Avec le moteur factice, rien ne s'exécute vraiment ; avec Codex (lot 2), si. Avant de brancher un vrai moteur :

  • un broker lié à 127.0.0.1 ;

  • l'authentification client active sur le broker, et ce slot déclaré protégé (authorization.protectedSlots) ;

  • une identité de provider dans le fichier de sécurité du broker, et son secret dans secretEnv ;

  • les clés des moteurs dans mcp-vault (engineSecrets), pas dans l'environnement du provider ;

  • des workspaceRoots aussi étroits que possible.

Une montée WebSocket ne passe par aucun contrôle d'origine, et les endpoints HTTP sont anonymes tant que l'authentification client est coupée.

Développement

npm test

Les tests tournent sur les sources, contre un vrai broker (startTestBroker) pour le bout en bout. npm run typecheck, npm run format et npm run build complètent ce que fait la CI.

Documents

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to asynchronously submit tasks to a persistent coding agent already running on a development machine, disconnect, and retrieve results later through a secure, policy-controlled gateway.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables external agents to list T3 environments and projects, start coding threads, monitor progress, send follow-up instructions, and interrupt running turns via MCP.
      7
      3
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables any MCP-compatible client to run reusable, Markdown-defined coding agents (such as reviewers, test writers, or investigators) through a configurable coding CLI backend, returning results into the same conversation. Agent definitions and backend/model settings can be shared across clients, and sessions can persist across multiple calls for longer work.
      127 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Lets any MCP client hand work to external coding agents from multiple vendors over the Agent Client Protocol, running them in parallel with approvals, questions, session snapshots and a read-only web monitor.
      17
      220 npm
      1
      Apache 2.0