🇬🇧 English version
Intégration MCP (Model Context Protocol)
Statut : expérimental (
[Experimental("ORKEXP004")]sur chaque type MCP — voir APIs expérimentales). Bi-génération : client et serveur parlent les deux lignées du protocole. Code :src/core/Orkeon.Infrastructure/MCP/.
L'intégration MCP fonctionne dans les deux sens :
- Client —
McpClientparle JSON-RPC à un serveur MCP externe ;McpToolProviderse connecte à un nombre quelconque de serveurs, liste leurs outils et enregistre chacun dans l'IToolRegistryd'Orkeon sous forme d'McpToolAdapter(IBaseTool). LeToolAccessde l'adaptateur ne vient desannotationsMCP de l'outil que pour un serveur auquel l'opérateur fait confiance (MCP:Servers:<name>:TrustAnnotations = true) :ReadpourreadOnlyHint: true,Executepour des annotations qui ne le portent pas. Un serveur est non fiable par défaut : n'importe quel serveur peut étiqueter en lecture seule un outil destructeur, que le modeplanlaisserait alors passer ; ses outils restent doncUnspecified(la classification fail-closed de la permission gate) quoi que disent leurs indications — comme ceux d'un serveur qui n'envoie aucune annotation.DisconnectServerAsyncles désenregistre. Un agent de crew liste un tel outil par son nom, comme n'importe quel autre — voir Outils MCP et crews. - Serveur —
McpServerexpose les outils de l'IToolRegistryd'Orkeon aux clients MCP externes (tools/list/tools/call, avec conversionToolSchema→ JSON Schema), sur stdio (RunStdioAsync) ou par traitement de requêtes individuelles (ProcessRequestAsync). Chaquetools/callfranchit le point d'invocation que franchissent les appels d'un agent de crew — garde, troncature, assainisseur de résultat, audit. Seule la capacité outils est annoncée, plus desresourcesen lecture seule quand/outputest exposé (opt-in), plus lespromptset les outils de crew quand--crewnomme des crews. La boucle stdio traite les requêtes en concurrence et honorenotifications/cancelled.orkeon mcp servele sert sur stdio — voir Servir les outils avecorkeon mcp serve.
Négociation de version : deux lignées de protocole
McpProtocol déclare ce que les deux côtés parlent :
- Lignée moderne, sans état —
ModernVersion = "2026-07-28". Pas de handshake : chaque requĂŞte porte_meta(io.modelcontextprotocol/protocolVersion,clientInfo,clientCapabilities) ; la dĂ©couverte des capacitĂ©s est la mĂ©thodeserver/discover. - LignĂ©e legacy Ă
initialize—SupportedLegacyVersions = ["2025-11-25", "2025-06-18", "2024-11-05"]: handshakeinitializeclassique suivi dunotifications/initializedobligatoire.2025-03-26est délibérément exclue : c'est la seule révision qui impose le batching JSON-RPC, que cette implémentation ne parle pas.
Client (McpClient.ConnectAsync)
- Sonde avec
server/discover(en déclarant2026-07-28dans_meta). - Succès avec
supportedVersions→ serveur moderne ; adoption de la révision la plus récente supportée des deux côtés. Un succès sanssupportedVersionsest un serveur legacy répondant avec indulgence à une méthode inconnue → repli surinitialize. - Erreur
-32022UnsupportedProtocolVersionError→ serveur moderne quand même ; lecture de sa liste supportée dans les données de l'erreur, renégociation, nouvelle tentative deserver/discover. - Toute autre erreur → serveur legacy ; handshake
initialize, qui négocie réellement (la révision choisie par le serveur est acceptée si le client la supporte) et se termine parnotifications/initialized.
Sur une connexion moderne établie, chaque requête porte son _meta ; un -32022 en cours
de route déclenche une renégociation + une nouvelle tentative avec une révision
supportée des deux côtés (McpClient.SendAsync).
Ce que le client garde du schéma d'un outil distant
McpToolAdapter lit l'inputSchema d'un outil distant pour en faire le schéma montré au modèle d'un agent, entier
et à toute profondeur. De chaque propriété il garde le type, la description, le default comme la valeur JSON
qu'il est (null n'est pas un défaut), l'enum (chaque valeur scalaire telle quelle : une chaîne, un nombre, un
booléen) ou un const (un enum d'une valeur), le format, les bornes (minimum, maximum, exclusiveMinimum,
exclusiveMaximum — la forme booléenne du draft 04 aussi —, minLength, maxLength, pattern, minItems,
maxItems), les items d'un tableau — un tableau de tableaux compris —, les properties et le required d'un
objet, ses additionalProperties (le schéma des valeurs d'un dictionnaire, ou false) et les alternatives
d'anyOf et de oneOf (montrées comme anyOf). La racine est lue comme tout autre schéma : un $ref, un allOf
ou un anyOf / oneOf nullable qui tient lieu d'un objet donne les propriétés de cet objet ; de ses
additionalProperties, la racine ne garde que false. Un $ref local (#/$defs/X, #/definitions/X, tout
pointeur JSON dans le document, # la racine) est le schéma qu'il nomme, la description, le default et le
format écrits à côté l'emportant sur ceux de la définition, l'enum et les bornes écrits à côté valant là où la
définition n'en a pas. Un type écrit comme un tableau est lu comme son seul membre autre que "null"
(["string", "null"], un paramètre nullable, est un string) ; un anyOf / oneOf dont la seule alternative
hormis le schéma nul est X — l'Optional[X] de Pydantic — est X, comme un allOf d'un seul schéma X ; le schéma
nul s'écrit {"type": "null"}, {"type": ["null"]}, {"const": null} ou {"enum": [null]}. Un allOf dont les
membres sont tous des objets (leur $ref suivi), à côté d'un schéma qui est un objet ou ne nomme aucun type, est un
seul objet : l'union de leurs propriétés (le premier qui en nomme une l'emporte), l'union de leurs required, et
additionalProperties: false dès que l'un d'eux le dit. Une propriété qui a des properties sans type est un
objet. Un tuple (items en tableau, ou prefixItems avec les items qui le suivent) est lu comme les alternatives
de ses positions, et items: false comme maxItems. Restent perdus, entre autres : la position des éléments d'un
tuple, un allOf dont un membre n'est pas un objet, une ancre (#nom) ou une référence à un autre document et une
référence coupée sur un cycle (un arbre dont le nœud contient des nœuds), qui acceptent n'importe quelle valeur JSON,
not, if / then / else, patternProperties, uniqueItems, multipleOf, dependentRequired,
additionalItems, title, minProperties / maxProperties, propertyNames, contains, un membre d'enum qui
est null ou n'est pas un scalaire, et ce qui se trouve Ă plus de 32 niveaux de profondeur (n'importe quelle valeur
JSON). Une propriété à plusieurs types, ou sans aucun ({}), n'a pas de type : le modèle peut donner n'importe
quelle valeur JSON. Un tableau dont les éléments ne sont pas connus — pas d'items, des éléments sans type unique —
est montré avec items: {}, n'importe quelle valeur JSON : aucun tableau n'arrive à un fournisseur sans items,
que certains refusent. Un outil dont l'inputSchema s'étend à plus de 4096 schémas, ou copie plus de 1 Mio de
texte, coûterait la mémoire de l'hôte et le contexte du modèle : chaque usage d'un $ref est compté (une définition
utilisée plusieurs fois compte à chaque fois, puisque le modèle la voit à chaque fois), et l'outil est écarté avec
un avertissement écrit une fois par définition d'outil distincte, comme ci-dessous.
Aucun inputSchema ne fait échouer la connexion : une entrée de required ou la description d'une
propriété qui n'est pas une chaîne est ignorée, un nombre qu'aucun double ne contient (1e400) est retiré
d'un enum ou d'un default, et la liste est lue outil par outil : une entrée qui n'est pas un objet (null), un
outil sans nom, ou un outil dont le name, la description ou les annotations ont le mauvais type JSON (un
name qui est un nombre) est écarté à lui seul — les autres outils de son serveur sont enregistrés.
L'avertissement nomme l'outil et le serveur tel que MCP:Servers le nomme, et il est écrit une fois pour
cette entrée, pas à chaque lecture de la liste — pour un inputSchema illisible, une fois pour cette
définition : un serveur qui la change est signalé de nouveau. Quand tools/list_changed apporte une telle entrée pour un
outil qui était enregistré, l'outil quitte le registre. Un "tools": null ne liste aucun outil, pas plus
qu'un result absent ou null. Une liste d'outils de la mauvaise forme — un tools qui n'est ni null ni un
tableau, un result présent qui n'est pas un objet, un nextCursor qui n'est pas une chaîne — n'est pas une
liste vide : elle échoue, avec un message qui nomme le serveur et le membre ; la connexion est donc signalée
en échec, et un tools/list_changed qui apporte une telle réponse laisse en place les outils enregistrés. Un
nom qu'un serveur liste deux fois, sur une page ou sur deux, est enregistré une fois, la première, et signalé
une fois : ce n'est pas une collision, et l'état du serveur ne rejette rien ; les noms sont comparés comme le
registre les compare, sans leur casse. prompts/list et resources/list sont lus entrée par entrée eux
aussi : un prompt sans nom, une ressource sans uri, ou une entrée dont les membres ont le mauvais type JSON
est écartée à elle seule avec un avertissement écrit une fois, un null parmi les arguments d'un prompt est
retiré, et un prompts ou un resources à null ne liste rien. Un nom de prompt ou une uri de ressource
listé deux fois est gardé une fois, le premier, et signalé une fois (prompts/get et resources/read nomment
une entrée ; les noms sont comparés avec leur casse). Aucun registre ne suit ces deux listes : une liste de la
mauvaise forme donne ce qui a pu ĂŞtre lu, avec un avertissement.
Les avertissements du client portent un nom d'événement qu'un filtre de journal peut viser :
mcp.tool.unreadable (un outil écarté, son entrée ou son inputSchema), mcp.entry.unreadable (un prompt ou
une ressource écarté), mcp.entry.duplicate (un outil, un prompt ou une ressource listé deux fois),
mcp.listing.unreadable (un prompts/list ou un resources/list de la mauvaise forme) et mcp.tool.rejected
(un nom qu'un autre outil détient).
Serveur (McpServer) — bi-génération sur un même endpoint
- Implémente
server/discover(versions supportées, capacités, indices de fraîcheurttlMs/cacheScope, identité du serveur dans le_metadu résultat). - Une requête déclarant une version
_metanon supportée est rejetée en-32022avec le payload{ supported, requested }, quelle que soit la méthode. - Le
initializelegacy renvoie la révision demandée quand elle est supportée, sinon la révision legacy la plus récente.pingreste servi pour les sessions legacy seulement (retiré de la lignée moderne). tools/listest renvoyé en ordre déterministe (tri ordinal par nom — un SHOULD de 2026-07-28, pour des caches clients stables) avec les champs modernesresultType/ttlMs/cacheScope; les clients legacy ignorent ces membres additifs.- Une notification valide — un message sans
id— ne reçoit jamais de réponse, pas plus qu'une réponse (unresultou unerrorsansmethod, quel que soit le reste de son enveloppe : le serveur n'envoie aucune requête, il l'ignore). Une ligne qui est du JSON mais pas une requête valide reçoit-32600 Invalid Request, y compris une notification dont l'enveloppe est invalide (sa réponse porte unidnull) ;-32700est réservé au texte qui n'est pas du JSON. Sont refusés ainsi : une valeur qui n'est pas un objet (un scalaire,null, un tableau — le batching n'est pas parlé, un lot reçoit donc une seule réponse pour toute la ligne), unjsonrpcabsent ou différent de"2.0", unemethodabsente, vide ou qui n'est pas une chaîne, unidnullou qui n'est ni une chaîne ni un entier, unparamsqui n'est ni un objet ni un tableau (nullvaut absence), et unidà côté d'une méthodenotifications/*(MCP l'interdit : le message reçoit une réponse, il n'est pas exécuté). La réponse porte l'idquand il a pu être lu — une chaîne ou un entier —,nullsinon. Une ligne de JSON valide imbriquée au-delà de 64 niveaux est refusée de la même façon, avec unidnull:-32700reste réservé au texte qui n'est pas du JSON.ProcessRequestAsyncdonne à un hôte C# les mêmes réponses pour la requête qu'on lui remet, et seulement pour ce que cette requête contient encore : un hôte qui désérialise lui-même le message enJsonRpcRequestperd unidnull(le message est pris pour une notification) et unjsonrpcabsent (il vaut"2.0"par défaut, le message est donc exécuté), et une réponse qu'il lui remet reçoit-32600là où la boucle stdio l'ignore. - Un message ne porte jamais de membre
null: une réponse contientresultouerror, jamais les deux, et un membre optionnel sans valeur est absent — un client strict (les SDK MCP) refuse le message sinon. Le seulnullest l'idde la réponse à une ligne dont l'idn'a pas pu être lu. - Les
argumentsd'untools/call(hors outilrun_crew_*de--crew, voir plus bas) arrivent à l'outil comme les valeurs que porte un appel d'outil au format OpenAI : un tableau est une liste, un objet un dictionnaire, un nombre écrit sans partie décimale ni exposant est unlongs'il y tient, tout autre nombre undouble,nullestnull(un appel d'outil Anthropic le lit comme le textenull).tools/listpublie les paramètres de chaque outil par l'écrivain des fournisseurs (ToolSchema.ToInputJsonSchema) : lesitemsd'un tableau ({}quand ils ne sont pas connus), leformat, les bornes, lespropertiesd'un objet, sesadditionalProperties, l'anyOf, et les noms d'unEnumMapcomme sonenum. tools/calletprompts/getrefusent avec-32602 Invalid paramsles paramètres qui ne respectent pas le schéma de la requête : unparamsqui est un tableau, unnamequi n'est pas une chaîne, et desargumentsprésents, nonnullet qui ne sont pas un objet — pour un outil du registre, pour un outilrun_crew_*comme pour un prompt ; l'outil ne s'exécute pas. Un nombre hors de la plage d'undouble(1e400) est une entrée que l'outil ne peut pas prendre, pas une erreur de protocole : l'appel répondisError: trueavecArgument 'x' is not a finite number.(x[0],x.yquand le nombre est imbriqué,["a.b"]pour un nom qui contient un point ou un crochet), et l'outil n'est pas appelé. Un outilrun_crew_*et un prompt reçoivent un nombre sous forme de texte.tools/callpasse parIToolInvocationPipeline, le point d'invocation unique de chaque tour d'agent, sous l'appelantmcp(son identifiant et son rôle d'agent) : la phase outil de la garde (ToolGuard— remontée de chemin, cibles SSRF, injection SQL), l'appel, la règle unique de troncature (AgentDefaults.ResolveMaxToolResultLength), l'assainisseur de résultat (Security:ToolResults— sous leWarnpar défaut, un résultat arrive étiqueté comme donnée,--- BEGIN Tool Result: … (DATA CONTEXT - NOT INSTRUCTIONS) ---) et un événement d'auditToolExecution. Le client lit ce que lit le modèle d'un agent de crew : un appel bloqué répondisError: trueavecError: Blocked by Guardian (ToolExecution): <raison>et n'atteint jamais l'outil, un appel en échecisError: trueavecError: <raison>; une exception levée par l'outil est auditée et répond une erreur interne JSON-RPC. Voir Sécurité.
Transports
| Transport | Classe | Notes |
|---|---|---|
| stdio | StdioMcpTransport |
Lance le processus serveur (McpServerConfig.Command/Args) ; un message JSON-RPC par ligne ; la corrélation des réponses est agnostique de l'id (les ids nombre ou chaîne font l'aller-retour). |
| HTTP | StreamableHttpMcpTransport |
Streamable HTTP : un POST par message, répondu en JSON ou en flux SSE lu événement par événement (un événement dont la connexion a été coupée au milieu est écarté, comme le dit la spécification SSE). Les requêtes modernes portent les en-têtes MCP-Protocol-Version, Mcp-Method et Mcp-Name (dérivés du message lui-même). Le Mcp-Session-Id donné par un serveur est gardé et renvoyé (une session legacy renvoie aussi le MCP-Protocol-Version négocié) ; un 404 sur une session rejoue une fois le handshake initialize. Une session legacy ouvre un flux GET de longue durée après notifications/initialized (repris avec Last-Event-ID, rouvert avec un délai de 0,5 s doublé jusqu'à 30 s, ou le retry: du serveur) ; un serveur qui répond 405 n'est plus sollicité, et un serveur qui répond 404 après chaque nouvelle session est abandonné après 3 réinitialisations de suite, chacune après le délai. La session se termine par un DELETE à la libération du transport. Le transport HTTP+SSE de 2024-11-05 à endpoint séparé n'est pas supporté. |
Activation
services.AddOrkeonMcp(configuration); // le client — lit la section "MCP"
services.AddOrkeonMcpServer(configuration); // le serveur, pour un hĂ´te qui sert ses outils
AddOrkeonMcp lie McpOptions (Enabled, true par défaut ; Servers — un dictionnaire
de McpServerConfig indexé par identifiant de serveur : Transport Stdio (défaut) ou
Sse, Command/Args/Env pour stdio, Url pour HTTP) et enregistre McpToolProvider
en singleton. Il n'enregistre aucun serveur : c'est AddOrkeonMcpServer qui enregistre
McpServer (+ McpServerOptions depuis MCP:Server : Name, Orkeon par défaut, Version, vide
par défaut — la version de la release en cours d'exécution —, MaxConcurrency (4), ExposeOutput (faux), ResourcesPageSize (100) et
MaxResourceBytes (1 Mio)), lequel sert l'IToolRegistry du conteneur et appelle chaque
outil par son IToolInvocationPipeline — AddOrkeonInfrastructure() et
AddOrkeonApplication() enregistrent les deux. Enregistrer n'est pas servir : l'hĂ´te lance
RunStdioAsync — ce que fait orkeon mcp serve — ou ProcessRequestAsync lui-même.
Aucun réglage ne démarre le serveur : la section MCP ne porte aucune clé de ce genre, et
chaque runner bâti sur RunnerHost refuse une clé inconnue au démarrage, serveurs déclarés ou non. Le serveur expose des outils, et /output comme
ressources quand ExposeOutput est actif (ci-dessous) ; prompts/* répondent
Method not found sauf si l'hôte donne au serveur un IMcpServerExtension (orkeon mcp serve --crew le fait), et aucune option ne prétend le contraire. La surcharge
AddOrkeonInfrastructure(IConfiguration) appelle elle-mĂŞme AddOrkeonMcp, jamais
AddOrkeonMcpServer.
{
"MCP": {
"Enabled": true,
"Servers": {
"filesystem": {
"Transport": "Stdio",
"Command": "npx",
"Args": [ "-y", "@modelcontextprotocol/server-filesystem", "/srv/data" ],
"Env": { "NODE_ENV": "production" }
},
"search": {
"Transport": "Sse",
"Url": "https://mcp.example.com/mcp",
"Auth": { "Type": "Bearer", "TokenEnv": "SEARCH_MCP_TOKEN" },
"Headers": { "X-Tenant": "env:SEARCH_MCP_TENANT" },
"Tools": { "Allow": [ "search", "fetch" ], "Deny": [ "fetch" ] },
"CallTimeout": "00:00:30"
}
},
"Server": { "Name": "Orkeon" }
}
}
Le serveur et le client se présentent comme Orkeon, avec la version de la release qu'ils exécutent
(celle qu'affiche orkeon --version), dans le handshake legacy (serverInfo, clientInfo) et dans
le _meta des requêtes modernes et des réponses à server/discover et tools/list. MCP:Server:Version, quand il n'est pas blanc, remplace celle
du serveur ; rien ne remplace celle du client.
Authentification, filtre et délai par serveur. Chaque MCP:Servers:<id> accepte :
Auth:TypevautNone(défaut),Bearer(Authorization: Bearer, le jeton lu dans la variable que nommeTokenEnv) ouBasic(UserEnvetPasswordEnv). Les variables sont lues à chaque requête : un jeton renouvelé ne demande aucun redémarrage. Aucun identifiant n'est jamais écrit dans les réglages.Headers: en-têtes HTTP supplémentaires, chacun une valeur littérale ouenv:VAR. Un en-têteAuthorizationy est refusé : utilisezAuth. Les en-têtes que le transport pose lui-même le sont aussi (Mcp-Session-Id,MCP-Protocol-Version,Mcp-Method,Mcp-Name,Last-Event-ID) ; un en-tête statique ne remplace jamais celui qu'une requête porte déjà .Url: quandAuthest renseigné ou qu'un en-tête litenv:VAR, l'adresse doit êtrehttps, ouhttpen loopback, commeTokenUrl: un identifiant n'est jamais envoyé en clair à un autre hôte.Tools:Allow(vide, tous les outils sont gardés) puisDeny, appliqués avant que les outils n'atteignent le registre ; un nom présent dans les deux est refusé. Une entrée qui ne correspond à aucun outil listé par le serveur est signalée par un avertissement (et dansMcpServerStatus.UnmatchedToolFilters).CallTimeout: durée maximale d'un appel d'outil, 60 secondes par défaut. Un serveur muet termine l'appel en erreur d'outil (McpCallTimeoutException,error_typedans les métadonnées de la réponse) ; l'annulation par l'appelant n'est pas un délai dépassé. La même borne vaut pourprompts/list,prompts/get,resources/list,resources/readet unresources/subscribelegacy (uneTimeoutExceptionqui nomme la clé). Une durée non positive est refusée ; la borne ne peut pas être désactivée.ConnectTimeout: durée maximale de la poignée de main et de la liste des outils, 30 secondes par défaut, quel que soit l'appelant. Un serveur resté muet fait échouer la connexion avec une erreur qui nommeMCP:Servers:<id>:ConnectTimeout.
OAuth 2.0. Auth:Type accepte aussi oauth2-client-credentials et oauth2-device
(OAuth2ClientCredentials et OAuth2Device sont lus aussi). Les graphies acceptées de Auth:Type sont exactement None, none, Bearer, bearer, Basic, basic, OAuth2ClientCredentials, oauth2-client-credentials, OAuth2Device et oauth2-device ; toute autre, un nombre compris, est refusée avec cette liste, avec ces clés :
"Auth": {
"Type": "oauth2-client-credentials",
"TokenUrl": "https://idp.example.com/oauth/token",
"ClientId": "orkeon-agent",
"ClientSecretEnv": "TRACKER_OAUTH_CLIENT_KEY",
"Scopes": [ "tools.call" ],
"Audience": "https://mcp.example.com"
}
TokenUrl(etDeviceAuthorizationUrlpour le device flow) doit être une adressehttpsabsolue, ouhttpsur la boucle locale : un identifiant n'est jamais posté en clair vers un autre hôte.ClientIdest obligatoire ;ClientSecretEnvnomme la variable qui porte le secret du client (obligatoire pour les client credentials, facultative pour le device flow) et se vérifie au démarrage puis à chaque demande de jeton.ScopesetAudiencesont facultatifs.- Le jeton d'accès vit en mémoire seulement et n'est jamais écrit sur disque. Il est renouvelé 60 secondes
avant son expiration. Quand le serveur répond
401, la requête repart une fois avec un nouveau jeton ; un second401est la réponse (l'appel échoue, rien ne boucle). Les requêtes refusées ensemble partagent un seul renouvellement. Le fluxGET, quand le serveur en offre un, se rouvre aussitôt après un renouvellement, une fois de suite, puis temporise. oauth2-deviceaffiche une adresse de vérification et un code sur le terminal du run (stderr) et attend la personne ; les renouvellements suivants utilisent le jeton de rafraîchissement émis par le fournisseur, et ne redemandent un code que s'il est refusé. Disponible dansorkeon runet la REPL, qui enregistrent uneIOAuthLoginInteractionsur leur console.orkeon-hostn'en enregistre aucune : un serveur enoauth2-devicey est écarté au démarrage avec une erreur qui le nomme ; utilisezoauth2-client-credentials. La connexion se fait avant la poignée de main de la connexion et avant un appel qui trouve le jeton expiré, hors deConnectTimeoutetCallTimeout: l'attente de la personne est bornée par la durée de vie du code d'appareil, pas par ces délais. La fermeture d'une session (leDELETEdeMcp-Session-Id) ne lance jamais de connexion.- Le point de terminaison de jeton est joint par son propre
HttpClient, enregistré sous le nomorkeon-mcp-oauth(McpServiceExtensions.OAuthHttpClientName), proxy et délai par défaut, sans redirection, exclu du journal d'échanges LLM. Le secret du client et les jetons ne sont jamais écrits dans une erreur ni une ligne de log : ce que le fournisseur d'identité renvoie en écho est masqué. - Un serveur dont les réglages sont illisibles (un
Auth:Typemal écrit, une durée invalide) est écarté au démarrage avec une ligne qui le nomme et en donne la raison ; les graphies acceptées deAuth:Typey sont listées. - Non pris en charge : la découverte de ressource protégée (RFC 9728) et l'enregistrement dynamique de client (DCR) ; les points de terminaison sont des réglages.
Headers et Auth valent pour le transport HTTP (Sse) ; sur un serveur Stdio ils sont refusés, jamais
ignorés en silence. Un serveur dont la configuration est invalide (un en-tête Authorization littéral, un en-tête que pose le
transport, une Url en http simple vers un hĂ´te distant avec des identifiants, une
variable d'environnement absente, Auth:Type sans nom de variable, un délai non positif, Auth ou Headers
sur un serveur Stdio) est écarté au démarrage avec une erreur qui nomme la clé des réglages, jamais une valeur, et le run continue
sans ses outils. Tous les serveurs partagent un HttpClient enregistré sous le nom orkeon-mcp
(McpServiceExtensions.HttpClientName) ; il est exclu du journal d'échanges LLM, si bien que ni le trafic ni
les identifiants n'y sont écrits. Les identifiants sont appliqués par requête par un
IMcpRequestAuthenticator, et non portés par le client ; une variable vide au moment d'une requête fait
échouer cette requête avec la même erreur nommant la clé, au lieu de l'envoyer sans authentification. Le
client ne suit aucune redirection HTTP : une réponse 3xx est un échec, si bien que les en-têtes statiques
et les identifiants n'atteignent jamais un autre hôte que celui configuré.
Rien n'est développé dans la section. Command, Args et Env passent tels qu'ils sont écrits, et le
serveur hérite de l'environnement où tourne Orkeon : une référence ${NOM} ou %NOM% dans Command,
Args, Url ou une valeur d'Env refuse le démarrage, avant la connexion d'un serveur, avec sa correction
(une référence de variable n'est jamais développée).
L'hôte partagé des runners honore la section de lui-même. orkeon run
— et tout runner bâti sur RunnerHost — appelle AddOrkeonMcp dès que MCP:Servers
déclare au moins un serveur et que MCP:Enabled n'est pas false, puis connecte chaque
serveur dans un pas de démarrage explicite (McpStartup) avant le chargement de la crew
— et avant que --validate juge la crew et que --list-tools imprime le manifeste, pour
que les trois voient la même surface d'outils. Un serveur qui ne peut pas être connecté
(commande inexistante, point de terminaison muet, poignée de main toujours en attente
après 30 s) coûte une ligne d'erreur qui le nomme, dans le journal et sur stderr, et le run
continue. La sortie d'erreur d'un serveur stdio est lue au fil de l'eau — chaque ligne va au
journal en Debug (MCP server '<id>' stderr: …), si bien qu'un serveur qui y écrit beaucoup
ne s'y bloque jamais — et un serveur qui s'arrête avant de répondre dit pourquoi : son code de
sortie et la dernière ligne écrite sur sa sortie d'erreur rejoignent cette ligne d'erreur
(Transport disconnected: the MCP server exited with code 1; its last line on stderr: …).
Les outils sont enregistrés sous leur propre nom, sans préfixe de serveur, et un
nom déjà tenu par le registre — un outil intégré, un outil de script ou l'outil d'un
serveur connecté plus tôt — est refusé : l'outil MCP n'est pas enregistré, une ligne
d'erreur nomme le serveur et l'outil (The tool 'file_read' of MCP server 'x' collides with an already-registered tool and was not registered), dans le journal et sur stderr, et
l'outil qui tenait le nom le garde, y compris après la déconnexion de ce serveur. Les
autres outils du serveur sont enregistrés normalement (--list-tools montre la surface
fusionnée).
orkeon-host les connecte aussi : bâti sur RunnerHost, il lit la même
section et exécute le même pas, une fois, depuis son premier service hébergé, au démarrage
du démon — avant que le canal de chat puisse livrer un message qui charge une crew — et
dĂ©connecte les serveurs Ă l'arrĂŞt, après le drainage. Les mĂŞmes rĂ©glages donnent Ă
orkeon run et à orkeon-host les mêmes outils ; un serveur injoignable coûte la même
ligne d'erreur et le démon démarre sans lui. Dans tout autre hôte qui embarque, MCP reste une
surface bibliothèque — l'hôte appelle lui-même AddOrkeonMcp(configuration) (ou la
surcharge config) et connecte lui-mĂŞme les serveurs.
orkeon-repl, et les scripts. orkeon-repl enregistre la section de la même façon et connecte
les serveurs avant de charger ses commandes ; un serveur qui échoue coûte la même ligne, et le REPL
démarre. Les outils qu'apporte un serveur entrent dans le registre d'outils, et le catalogue des
scripts le lit à côté des outils du conteneur (ScriptToolCatalogue) : l'espace de noms tools
d'une commande, le .tools([...]) d'un agent dans une crew .ork.ts et ctx.llm.act atteignent les
outils d'un serveur MCP — dans le REPL, et sous orkeon run, où les serveurs d'un script procédural
sont connectés avant qu'il tourne. Whisper par MCP branche
ainsi un serveur de transcription.
La bibliothèque ne livre pas de hosted service pour cela : un hôte qui embarque résout
McpToolProvider et appelle explicitement ConnectServerAsync(serverId, config) pour
chaque serveur configuré — exactement ce que fait le pas de démarrage de l'hôte des runners,
et ce qu'appelle le service de connexion d'orkeon-host. Un hĂ´te qui sert ses outils appelle
AddOrkeonMcpServer(configuration), puis résout McpServer et lance RunStdioAsync(reader, writer) sur les flux qu'il possède — ce
que fait orkeon mcp serve. orkeon-host ne sert pas MCP.
Outils MCP et crews
Un outil MCP connecté est un outil comme les autres : un agent de crew le liste par son nom,
en YAML ou dans un script .ork.ts, et le reçoit.
agents:
analyst:
tools: [search_issues] # un outil exposé par un serveur MCP déclaré dans MCP:Servers
CrewFactory attache tout outil que le registre résout ; il n'y a pas d'interface plus
étroite qu'IBaseTool à implémenter. Les serveurs sont connectés avant le chargement de la
crew : sous StrictTools — le défaut des runners — une crew qui nomme l'outil d'un serveur
qui n'a pas pu être connecté échoue au chargement avec la ligne ordinaire unknown tool(s).
--list-tools et --validate voient les outils MCP, McpServer ré-expose ce que contient
le registre — tous les outils, ou ceux que nomme orkeon mcp serve --tools (AllowedTools) ; l'hôte
d'orkeon mcp serve n'enregistre pas human_input —, et du code C# peut en résoudre un par IToolRegistry.GetToolByNameAsync(name).
Le décorateur des runs observés de --events jsonl enveloppe les outils enregistrés dans la
DI ; les outils MCP arrivent dans le registre à l'exécution et ne sont pas enveloppés.
Servir les outils avec orkeon mcp serve
orkeon mcp serve [--settings <fichier>] [--tools a,b,…] [--max-concurrency <n>] [--expose-output] [--crew <a.yaml> [<b.yaml> …]] [--allow-external-mounts]
Le verbe sert les outils d'un hôte Orkeon à un client MCP sur stdio — le transport par lequel Claude Desktop, les éditeurs et les frameworks d'agents démarrent un serveur local : le client lance le processus, écrit un message JSON-RPC par ligne sur son stdin et lit les réponses sur son stdout, une par ligne ; fermer stdin arrête le serveur.
- L'hôte est celui que construit un run. Les réglages se résolvent comme ceux
d'
orkeon run, ancrés au répertoire courant :--settings, sinonappsettings.jsonà cet endroit, sinon unappsettings/appsettings.jsontrouvé en remontant, sinon le fichier par utilisateur d'orkeon init, sinon les seules variables d'environnementORKEON_*; le fichier retenu est nommé sur stderr. Les montages qu'il déclare (Orkeon:FileSystem:Mounts) sont ce qu'atteignent les outils de fichiers, et les serveurs MCP qu'il déclare sousMCP:Serverssont connectés d'abord, leurs outils servis aussi. Ce qui est servi est ce qu'imprimeorkeon run --list-toolspour les mêmes réglages,human_inputà part : cet outil répond pour l'opérateur d'un run, et le client d'un serveur MCP a son propre humain. Aucune crew n'est chargée, donc aucun outil que déclare une crew.ork.tsn'est servi : ceux-là sont enregistrés au chargement de leur crew. --crew <a.yaml> [<b.yaml> …]sert des crews comme outils. Plusieurs crews se suivent, séparées par des espaces, après un seul drapeau, qu'on ne peut pas répéter (comme--mount). Chaque crew est chargée une fois au démarrage par le point d'entrée avec lequelorkeon runetorkeon eval run --crewchargent une crew, dans un hôte à elle qui porte ce qu'orkeon rundonne à une crew : les réglages (--settings, sinon résolus depuis le dossier de la crew), le budget, le gardien et la barrière de permissions (Orkeon:Security:PermissionGate, unaskest refusé sans canal). Une crew qui ne se charge pas, un dossier hors du répertoire courant sans--allow-external-mounts, deux crews qui donnent un même nom, ou un nomrun_crew_*qu'un outil de l'hôte porte déjà refusent le démarrage, avec le nom. Seules les crews nommées sont servies : aucun outil ne prend de chemin.- L'outil est
run_crew_<nom>: lenamede la crew, en minuscules, chaque suite d'autres caractères devenant un tiret bas. SoninputSchemaest un objet à une propriété chaîne obligatoire par{placeholder}trouvé dans lesdescriptionetexpectedOutputdes tâches (comparés sans tenir compte de la casse, dans l'ordre de première apparition) et aucune autre propriété. Un nombre ou un booléen est lu comme son texte ; un objet, un tableau ounullest refusé, de même qu'un argument inconnu ou manquant (-32602, noms listés). Le résultat est la sortie finale de la crew ; une crew qui échoue est un résultatisError, pas une erreur JSON-RPC. - Progression : quand l'appel porte
_meta.progressToken, le serveur envoie unenotifications/progresspar tâche terminĂ©e (progressde 1 Ătotal, le nombre de tâches, avec unmessage) avant la rĂ©ponse ; sans jeton rien n'est envoyĂ©.notifications/cancelledannule le run. - Prompts : chaque tâche est le prompt
<nom>_task_<n>(à partir de 1), ses arguments les placeholders de cette tâche, le message sa description et sa sortie attendue interpolées. La capacitépromptsn'est annoncée qu'avec--crew. - Les appels d'une même crew s'exécutent un par un. L'hôte de la crew est partagé par ses appels, et avec lui ce
qu'il monte (
/output,AUTO_SUMMARY.md, les checkpoints) : un second appel attend le premier (les appels d'autres crews, et tous les autres outils, s'exécutent à côté). Chaque appel tourne tout de même dans un scope à lui, avec son propre état de tâches, et unnotifications/cancelleddu client annule la crew en cours : ses agents voient le jeton et l'appel n'est pas répondu. - Le run est enregistré comme tout run de l'hôte. Avec
Orkeon:RunHistory:Enabledactivé dans les réglages de la crew, chaque appel est un run de l'historique :run.started, les événements de tâche,run.finished, sous son propre identifiant de run (celui des checkpoints), lu avecorkeon runs. Historique éteint, rien n'est écrit.run.finishedportesuccess,exitCode,durationMs,cappedTasksetmissingDeliverables, et aucun champ de tokens (voir le bus d'événements de run). Les événements ne portent pas de compte de tokens : l'usage du modèle n'est pas attribué par appel. - Il n'y a pas de mode hors ligne. L'hôte du serveur lit les vrais réglages et une crew appelle les modèles qu'ils déclarent ; le fournisseur mock ne s'atteint qu'en pointant les profils vers lui.
- Le
totalde la progression est le nombre de tâches de la crew ; une relance ou un manager hiĂ©rarchique peut exĂ©cuter plus de tentatives que cela, et la progression s'arrĂŞte alors Ătotal.
- L'outil est
- La permission gate n'est pas consultée pour les appels du client (
GateExempt). Les appels du serveur passent par le point d'invocation gardé (Guardian, assainisseur de résultat, audit) sous l'appelantmcp, marquéGateExempt: le client IA qui a lancéorkeon mcp servesur stdio ne passe pas par l'IPermissionGate. La raison : le client est l'agent de l'opérateur, qui a déjà choisi ce qu'il peut atteindre (les réglages,--tools, les montages) ; stdout porte le protocole, unaskn'aurait aucun canal vers un humain et tout appel à approuver serait refusé. Une crew servie avec--crewest un autre cas : ses propres agents passent par la permission gate comme dansorkeon run. --tools a,b,…ne sert que les outils nommés (séparés par des virgules) ; un nom que l'hôte n'a pas refuse le démarrage en le nommant. Les autres outils ne sont ni listés ni appelables, même ceux qu'un serveur MCP amont enregistre plus tard (tools/list_changed) : la liste blanche est celle du serveur (MCP:Server:AllowedTools), pas un désenregistrement. Les outils de--crewn'y sont pas soumis.- Les requêtes s'exécutent en concurrence (
--max-concurrency <n>, au moins 1, 4 par dĂ©faut, ouMCP:Server:MaxConcurrency). Chaque requĂŞte est une tâche ;nau plus tournent Ă la fois et les autres attendent leur tour : un cinquième appel lent dĂ©marre quand l'un des quatre premiers se termine. Un appel de--crewne tient aucun emplacement : il attend sa crew (une exĂ©cution Ă la fois par crew), donctools/listetpingrestent servis. Les rĂ©ponses passent par un canal vers un seul Ă©crivain : deux rĂ©ponses ne s'entrelacent jamais sur stdout, et elles peuvent arriver dans un autre ordre que les requĂŞtes (le client les rapproche parid). Quand stdin se ferme, chaque requĂŞte dĂ©jĂ lue reçoit sa rĂ©ponse avant que le serveur ne s'arrĂŞte. notifications/cancelledannule la requĂŞte que nomme sonrequestId, qu'elle tourne ou qu'elle attende son tour : l'appel d'outil reçoit l'annulation, et une requĂŞte annulĂ©e n'est jamais rĂ©pondue, comme la spĂ©cification le demande. Un identifiant inconnu du serveur est ignorĂ©. Une seconde requĂŞte dont l'identifiant est dĂ©jĂ en vol est refusĂ©e (-32600).McpServerest un singleton sans dĂ©pendance scoped : une requĂŞte n'a pas de portĂ©e DI propre.--expose-output(ouMCP:Server:ExposeOutput) sert/outputcomme ressources en lecture seule, dĂ©sactivĂ© par dĂ©faut.resources/listpagine les fichiers sous/outputpar ordre de chemin (ResourcesPageSizepar page, unnextCursoropaque), chacun sous la formeorkeon:///output/<chemin>avec sonname, sonmimeTypeet sasize;resources/readrend un fichier entextquand c'est du texte UTF-8 et enblobbase64 sinon, jusqu'ĂMaxResourceBytes. Tout passe parIFileSystemService: le montage/outputdoit exister et accorder Read (un avertissement sur stderr le dit quand il n'est pas montĂ©), et l'URI est analysĂ©e strictement — aucun segment./../vide, ni requĂŞte ni fragment, ni%2f, tout autre queorkeon:///output/…est refusĂ©./workspaceet tout autre montage ne sont jamais exposĂ©s, aucune URI ni erreur ne porte de chemin physique, et il n'y a niresources/subscribeniresources/templates/list. Sans l'option,resources/*rĂ©pondentMethod not found.- Chaque appel est gardĂ© : le point d'invocation du serveur,
sous l'appelant
mcp— un appel bloqué n'atteint jamais l'outil, un résultat arrive tronqué et étiqueté comme donnée, et la piste d'audit enregistre chaque appel sous l'agentmcp; un appel bloqué ou en échec atteint aussi stderr, par le puits de journal de la piste (Agent=mcp). - Stdout ne porte que le protocole. Chaque ligne de journal, avertissement et diagnostic
va sur stderr — là où un client MCP enregistre la sortie d'un serveur —, de même que
--helpet les erreurs d'usage. - Codes de sortie :
0le client a fermé le flux (ou--help) ;1une erreur d'usage, un réglage refusé (une clé inconnue, un montage déclaré par les réglages qui ne peut pas être monté, tout autre réglage que refuse l'hôte des runners — une ligneERROR:le nomme), un nom de--toolsque l'hôte n'a pas, un--crewrefusé au démarrage (une crew qui ne se charge pas, un nom donné deux fois, un nomrun_crew_*déjà tenu par un outil), un serveur lancé par un autre (plus bas) ;2une erreur inattendue. Ctrl+C ou SIGTERM termine le serveur avec0, les crews et les serveurs amont étant libérés à la sortie.
Une configuration client — le claude_desktop_config.json de Claude Desktop :
{
"mcpServers": {
"orkeon": {
"command": "orkeon",
"args": ["mcp", "serve", "--settings", "/home/moi/orkeon/appsettings.json"]
}
}
}
Un client démarre ses serveurs dans un répertoire de travail de son choix : nommez le fichier
de réglages avec --settings, ou comptez sur le fichier par utilisateur d'orkeon init.
Un serveur ne démarre jamais sous un autre. Avant de connecter les serveurs MCP de ses
réglages, un serveur pose ORKEON_MCP_SERVE dans son propre environnement — chaque processus
qu'il lance en hérite, et la variable est retirée quand il s'arrête — et un serveur qui la
trouve posée refuse de démarrer : code 1, et une ligne sur stderr, que le serveur qui l'a
lancé joint à son erreur de connexion
(orkeon mcp serve: refused to start: another `orkeon mcp serve` started this one (ORKEON_MCP_SERVE is set), …).
Des réglages qui déclarent orkeon mcp serve lui-même sous MCP:Servers coûtent donc
cette seule ligne : retirez l'entrée, ou déclarez les deux
serveurs côté client. orkeon run et orkeon-host ne posent aucun marqueur, et peuvent
utiliser un orkeon mcp serve lancé sur d'autres réglages. Comme ORKEON_DEBUG, la variable
est aussi lue par la couche de configuration ORKEON_, comme une clé (MCP_SERVE) qui n'est
aucun réglage.
Notifications, pagination et prompts (le client)
- Pagination.
tools/list,resources/listetprompts/listsuiventnextCursorjusqu'à une page qui n'en nomme aucun (McpClient.ListToolsAsync,ListResourcesAsync,ListPromptsAsync). Un serveur dont le curseur ne finit jamais fait échouer la liste au bout de 100 pages, ou de 10 000 éléments, (InvalidOperationException) au lieu de la laisser grossir sans fin. - Notifications. Une trame sans
idest une notification :IMcpTransport.Notificationsest unChannelReader<JsonRpcNotification>(256 entrées,DropOldest, un avertissement par entrée perdue). Le transport stdio l'alimente depuis la sortie du serveur ; le transport HTTP, avec les notifications d'une réponse encadrée en SSE (à mesure qu'elles arrivent, pas après son message final), du fluxGETet desubscriptions/listen. Une requête que le serveur envoie au client (sampling/createMessage,roots/list,elicitation/create) reçoit-32601sur stdio et sur HTTP : le client n'en offre aucune ; unpingen HTTP reçoit le résultat vide que la spécification exige. - Abonnements. Sur un serveur moderne en HTTP,
McpToolProvidergarde ouverte une requêtesubscriptions/listen(McpClient.ListenAsync: changements de listes d'outils, de prompts et de ressources, plus les ressources abonnées) ; quand le serveur termine le flux, il est rouvert après le même délai croissant et la liste d'outils est marquée périmée, puisque ce que le serveur a dit entre-temps est perdu. Un serveur qui refuse la requête n'est plus sollicité. Le flux n'est pas borné parCallTimeout. Sur un serveur legacy,McpToolProvider.SubscribeResourceAsyncenvoieresources/subscribe(UnsubscribeResourceAsyncy met fin et abandonne la lecture en cache) (refusé quand le serveur n'annonce pasresources.subscribe) et les mises à jour arrivent sur le fluxGET. Unnotifications/resources/updatedn'invalide que la lecture en cache de cette ressource (McpToolProvider.ReadResourceAsyncmet en cache les lectures des ressources abonnées, et elles seules, et une lecture en vol quand la mise à jour arrive n'est pas gardée) ; les outils ne sont pas listés de nouveau. Quand le fluxGETest rouvert ou la session réinitialisée, le cache est abandonné et les abonnements sont renvoyés, puisque les notifications du trou sont perdues. notifications/tools/list_changed.McpToolProvidersurveille chaque serveur connecté. Après une attente de 500 ms (les notifications arrivées entre-temps sont absorbées) il liste de nouveau les outils, applique le filtreToolsdu serveur, désenregistre les outils que le serveur a retirés, remplace ceux dont la définition a changé par un nouvel adaptateur en une seule étape du registre (IToolRegistry.ReplaceToolAsync: le nom ne cesse jamais de se résoudre), et enregistre les nouveaux. Un nom qu'un autre outil détient (un intégré, un outil de script, l'outil d'un autre serveur) lui reste et est signalé par l'avertissementmcp.tool.rejected;McpServerStatus.RejectedToolNamesle nomme. Une tâche déjà en cours garde les instances d'outils qu'elle a reçues : seule la crew construite ensuite voit le nouvel ensemble. Les notifications sont lues dès leur arrivée : un flot d'autres trames ne peut pas chasser unlist_changeddu canal borné, et unlist_changedarrivé pendant une nouvelle liste en déclenche une autre. Une nouvelle liste qui échoue garde les outils enregistrés jusque-là et est journalisée.- Prompts.
McpClient.ListPromptsAsyncetGetPromptAsync(name, arguments)parlentprompts/*. L'outil intégrémcp_prompt_get(server,name,arguments) remet un prompt à un agent, ou liste les prompts du serveur quandnameest vide ;AddOrkeonMcpl'enregistre. Le texte d'un prompt est un contenu non fiable du serveur et un vecteur d'injection de prompt : il arrive au modèle comme résultat d'un appel d'outil, rien de plus, et un serveur peut y mettre des instructions. L'outil déclareToolAccess.Read: la permission gate laisse donc passer l'appel sans demander, dans tous les modes. Ne connectez que des serveurs de confiance, ou gardez l'outil hors destools:d'un agent qui ne doit pas lire leurs prompts.
Limites honnĂŞtes
Alignées sur Limitations connues :
- Abonnements —
subscriptions/listenne tourne qu'en HTTP (le client stdio entend chaque notification que le serveur envoie) ; la forme du filtre 2026-07-28 (notifications.toolsListChanged,promptsListChanged,resourcesListChanged,resourceSubscriptions) est celle que ce client envoie, vérifiée contre ses propres faux serveurs et le serveur de référence, pas encore contre le schéma publié. - Ni sampling, ni roots, ni elicitation — une requête du serveur pour l'un d'eux reçoit
-32601: le sampling ferait appeler un LLM par Orkeon pour le serveur hors du budget, du gardien et du coût d'un run ; les roots exposeraient des chemins physiques (règle VFS) ; l'elicitation attend le human-in-the-loop durable. - Pas de requêtes multi-aller-retour (MRTR) — un résultat intermédiaire moderne
input_requiredremonte comme une erreur d'outil explicite, jamais comme des données partielles. - OAuth se limite aux client credentials et au device flow — pas de flux authorization-code, pas de découverte de ressource protégée (RFC 9728), pas d'enregistrement dynamique de client (DCR) ; le device flow demande un hôte avec terminal (pas
orkeon-host) ; les jetons ne sont jamais persistés, une connexion device est redemandée au run suivant. - HTTP+SSE 2024-11-05 non supporté — le transport à endpoint de messages séparé est refusé ; Streamable HTTP est le transport HTTP. L'interop contre le serveur de référence tourne chaque nuit (
McpReferenceServerInteropTests, Interop MCP). 2025-03-26exclue (batching JSON-RPC obligatoire).- Le serveur ne parle que stdio (
orkeon mcp serve, ouRunStdioAsync/ProcessRequestAsyncdans un hĂ´te C#) : pas de transport HTTP, des prompts et des crews comme outils seulement pour les crews que nomme--crew(un client ne donne jamais de chemin), et les ressources se limitent Ă/output(lecture seule, pas deresources/subscribe).
Statut expérimental
Chaque type MCP porte [Experimental("ORKEXP004")] : y faire référence depuis votre code
est une erreur de compilation tant que le diagnostic n'est pas supprimé — cette
suppression vaut opt-in et reconnaissance que la surface (notamment les types wire) peut
encore bouger. Voir APIs expérimentales.
Voir aussi : Sous-systèmes opt-in · APIs expérimentales · Limitations connues · Retour à l'index