Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

MCP Integration (Model Context Protocol)

Status: Experimental ([Experimental("ORKEXP004")] on every MCP type β€” see Experimental APIs). Dual-era: client and server speak both protocol lineages. Code: src/core/Orkeon.Infrastructure/MCP/.

The MCP integration works in both directions:

  • Client β€” McpClient speaks JSON-RPC to an external MCP server; McpToolProvider connects to any number of servers, lists their tools and registers each one in the Orkeon IToolRegistry as an McpToolAdapter (IBaseTool). The adapter's ToolAccess comes from the tool's MCP annotations only for a server the operator trusts (MCP:Servers:<name>:TrustAnnotations = true): Read for readOnlyHint: true, Execute for annotations without it. A server is untrusted by default: any server can label a destructive tool read-only, which plan mode would then let run, so its tools stay Unspecified (the permission gate's fail-closed classification) whatever their hints say β€” as do the tools of a server that sends no annotations. DisconnectServerAsync unregisters them. A crew agent lists such a tool by name, like any other β€” see MCP tools and crews.
  • Server β€” McpServer exposes the tools of the Orkeon IToolRegistry to external MCP clients (tools/list / tools/call, with ToolSchema β†’ JSON Schema conversion), over stdio (RunStdioAsync) or by processing individual requests (ProcessRequestAsync). Every tools/call crosses the invocation point a crew agent's calls cross β€” guardian, truncation, result sanitizer, audit. Only the tools capability is advertised, plus read-only resources when /output is exposed (opt-in), plus prompts and crew tools when --crew names crews. The stdio loop runs requests concurrently and honours notifications/cancelled. orkeon mcp serve serves it over stdio β€” see Serving the tools with orkeon mcp serve.

Version negotiation: two protocol lineages

McpProtocol declares what both sides speak:

  • Modern, stateless lineage β€” ModernVersion = "2026-07-28". No handshake: every request carries _meta (io.modelcontextprotocol/protocolVersion, clientInfo, clientCapabilities); capability discovery is the server/discover method.
  • Legacy initialize lineage β€” SupportedLegacyVersions = ["2025-11-25", "2025-06-18", "2024-11-05"]: classic initialize handshake followed by the mandatory notifications/initialized. 2025-03-26 is deliberately excluded: it is the only revision that mandates JSON-RPC batching, which this implementation does not speak.

Client (McpClient.ConnectAsync)

  1. Probe with server/discover (declaring 2026-07-28 in _meta).
  2. Success with supportedVersions β†’ modern server; adopt the newest mutually supported revision. A success without supportedVersions is a legacy server answering an unknown method leniently β†’ fall back to initialize.
  3. Error -32022 UnsupportedProtocolVersionError β†’ still a modern server; read its supported list from the error data, renegotiate, retry server/discover.
  4. Any other error β†’ legacy server; run the initialize handshake, which really negotiates (the server's chosen revision is accepted if the client supports it) and ends with notifications/initialized.

On an established modern connection, every request carries per-request _meta; a mid-flight -32022 triggers one renegotiation + retry with a mutually supported revision (McpClient.SendAsync).

What the client keeps of a remote tool's schema

McpToolAdapter reads the inputSchema of a remote tool into the schema an agent's model is shown, whole and at any depth. Of each property it keeps the type, the description, the default as the JSON value it is (null is no default), the enum (every scalar value as it is: a string, a number, a boolean) or a const (an enum of one value), the format, the bounds (minimum, maximum, exclusiveMinimum, exclusiveMaximum - the boolean form of draft 04 too -, minLength, maxLength, pattern, minItems, maxItems), the items of an array - an array of arrays included -, the properties and required of an object, its additionalProperties (the schema of a dictionary's values, or false) and the alternatives of anyOf and oneOf (shown as anyOf). The root is read like any other schema: a $ref, an allOf or a nullable anyOf / oneOf that stands for one object gives that object's properties; of its additionalProperties, the root keeps only false. A local $ref (#/$defs/X, #/definitions/X, any JSON pointer into the document, # the root) is the schema it names, with the description, default and format written beside it over those of the definition, and the enum and the bounds written beside it where the definition has none. A type written as an array is read as its one member that is not "null" (["string", "null"], a nullable parameter, is a string); an anyOf / oneOf whose only alternative but the null schema is X - Pydantic's Optional[X] - is X, and so is an allOf of one schema X; the null schema is written {"type": "null"}, {"type": ["null"]}, {"const": null} or {"enum": [null]}. An allOf whose members are all objects (their $ref followed), beside a schema that is an object or names no type, is one object: the union of their properties (the first that names one wins), the union of their required, and additionalProperties: false when any of them says so. A property with properties and no type is an object. A tuple (items as an array, or prefixItems with the items that follow it) is read as the alternatives of its positions, and items: false as maxItems. Still lost, among others: the position of a tuple's items, an allOf with a member that is no object, an anchor (#name) or a reference to another document and a reference cut at a cycle (a tree whose node holds nodes), which accept any JSON value, not, if / then / else, patternProperties, uniqueItems, multipleOf, dependentRequired, additionalItems, title, minProperties / maxProperties, propertyNames, contains, an enum member that is null or no scalar, and what lies more than 32 levels deep (any JSON value). A property with several types, or with none ({}), has no type: the model may give any JSON value. An array whose items are not known - no items, items with no single type - is shown with items: {}, any JSON value: no array reaches a provider without items, which some refuse. A tool whose inputSchema expands to more than 4096 schemas, or copies more than 1 MiB of text, would cost the host's memory and the model's context: each use of a $ref is counted (a definition used many times counts each time, as the model is shown it each time), and the tool is set aside with a warning written once per distinct tool definition, as below.

No inputSchema makes the connection fail: a required entry or a description of a property that is no string is skipped, a number no double holds (1e400) is dropped from an enum or a default, and the listing is read tool by tool: an entry that is no object (null), a tool with no name, or one whose own name, description or annotations have the wrong JSON type (a name that is a number) is set aside on its own - the other tools of its server are registered. The warning names the tool and the server as MCP:Servers names it, and is written once for that entry, not at every listing - for an inputSchema that cannot be read, once for that definition: a server that changes it is warned about again. When tools/list_changed brings such an entry for a tool that was registered, the tool leaves the registry. A "tools": null lists no tool, and so does a result that is absent or null. A tool listing of the wrong shape - a tools that is neither null nor an array, a result that is present and no object, a nextCursor that is no string - is no empty listing: it fails, with a message that names the server and the member, so the connection is reported as failed and a tools/list_changed that brings such an answer leaves the registered tools in place. A name one server lists twice, on one page or two, is registered once, the first time, and warned about once: it is no collision, and the server's status rejects nothing; names are compared as the registry compares them, without their case. prompts/list and resources/list are read entry by entry too: a prompt with no name, a resource with no uri, or one whose members have the wrong JSON type is set aside alone with a warning written once, a null among a prompt's arguments is dropped, and a prompts or resources that is null lists nothing. A prompt name or a resource uri listed twice is kept once, the first, and warned about once (prompts/get and resources/read name one entry; the names are compared with their case). No registry follows these two listings, so one of the wrong shape lists what could be read, with a warning.

The client's warnings carry an event name a log filter can match: mcp.tool.unreadable (a tool set aside, its entry or its inputSchema), mcp.entry.unreadable (a prompt or a resource set aside), mcp.entry.duplicate (a tool, a prompt or a resource listed twice), mcp.listing.unreadable (a prompts/list or resources/list of the wrong shape) and mcp.tool.rejected (a name another tool holds).

Server (McpServer) β€” dual-era on one endpoint

  • Implements server/discover (supported versions, capabilities, ttlMs/cacheScope freshness hints, server identity in result _meta).
  • A request that declares an unsupported _meta version is rejected with -32022 and the { supported, requested } payload, whatever the method.
  • Legacy initialize echoes the requested revision when supported, otherwise answers with the newest legacy revision. ping stays served for legacy sessions only (removed from the modern lineage).
  • tools/list is returned in deterministic order (ordinal sort by name β€” a 2026-07-28 SHOULD, for stable client caches) with the modern resultType/ttlMs/cacheScope fields; legacy clients ignore these additive members.
  • A valid notification - a message with no id - is never answered, and neither is a response (a result or an error with no method, whatever the rest of its envelope: the server sends no request, so it drops one). A line that is JSON but no valid request is answered -32600 Invalid Request, a notification whose envelope is invalid included (its answer carries a null id); -32700 is kept for text that is not JSON. Refused that way: a value that is no object (a scalar, null, an array - batching is not spoken, so a batch gets one answer for the whole line), a jsonrpc that is absent or not "2.0", a method that is absent, empty or no string, an id that is null or neither a string nor an integer, a params that is neither an object nor an array (null counts as none), and an id beside a notifications/* method (MCP forbids it, so the message is answered, not obeyed). The answer carries the id when it could be read - a string or an integer -, null otherwise. A line of valid JSON nested deeper than 64 levels is refused the same way, with a null id: -32700 is kept for text that is not JSON. ProcessRequestAsync gives a C# host the same answers for the request it is handed, and only for what that request still holds: a host that deserializes the message itself into a JsonRpcRequest loses a null id (the message is taken for a notification) and an absent jsonrpc (it defaults to "2.0", so the message is obeyed), and a response it hands over is answered -32600 where the stdio loop drops it.
  • A message never carries a null member: a response holds result or error, never both, and an optional member with no value is absent - a strict client (the MCP SDKs) refuses the message otherwise. The one null is the id of the answer to a line whose id could not be read.
  • The arguments of a tools/call (a run_crew_* tool of --crew aside: see below) reach the tool as the values a tool call in the OpenAI format carries: an array is a list, an object a dictionary, a number written without a fraction or an exponent is a long when it fits one, any other number a double, null is null (an Anthropic tool call reads it as the text null). tools/list publishes each tool's parameters through the providers' writer (ToolSchema.ToInputJsonSchema): the items of an array ({} when they are not known), the format, the bounds, the properties of an object, its additionalProperties, the anyOf, and the names of an EnumMap as its enum.
  • tools/call and prompts/get refuse parameters that fail the request's schema with -32602 Invalid params: a params that is an array, a name that is no string, and arguments that are present, not null and not an object - for a registry tool, for a run_crew_* tool and for a prompt alike; the tool does not run. A number beyond the range of a double (1e400) is an input the tool cannot take, not a protocol error: the call answers isError: true with Argument 'x' is not a finite number. (x[0], x.y when the number is nested, ["a.b"] for a name that holds a dot or a bracket), and the tool is not called. A run_crew_* tool and a prompt take a number as its text.
  • tools/call goes through IToolInvocationPipeline, the single invocation point of every agent turn, under the caller mcp (its agent id and role): the guardian's tool phase (ToolGuard β€” path traversal, SSRF targets, SQL injection), the call, the one truncation rule (AgentDefaults.ResolveMaxToolResultLength), the result sanitizer (Security:ToolResults β€” under the default Warn a result arrives tagged as data, --- BEGIN Tool Result: … (DATA CONTEXT - NOT INSTRUCTIONS) ---), and a ToolExecution audit event. The client reads what a crew agent's model reads: a blocked call answers isError: true with Error: Blocked by Guardian (ToolExecution): <reason> and never reaches the tool, a failed call isError: true with Error: <reason>; an exception the tool throws is audited and answers a JSON-RPC internal error. See Security.

Transports

Transport Class Notes
stdio StdioMcpTransport Launches the server process (McpServerConfig.Command/Args); one JSON-RPC message per line; response correlation is id-agnostic (number or string ids round-trip).
HTTP StreamableHttpMcpTransport Streamable HTTP: one POST per message, answered as JSON or as an SSE stream read event by event (an event the connection was cut in the middle of is discarded, as the SSE specification says). Modern requests carry the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers (derived from the message itself). The Mcp-Session-Id a server hands out is kept and sent back (a legacy session also sends the negotiated MCP-Protocol-Version); a 404 on a session replays the initialize handshake once. A legacy session opens a long-lived GET stream after notifications/initialized (resumed with Last-Event-ID, re-opened with a backoff of 0.5 s doubling up to 30 s, or the server's retry:); a server that answers it 405 is not asked again, and one that answers it 404 after each new session is given up after 3 re-initialisations in a row, each after the backoff. The session ends with a DELETE when the transport is disposed. The 2024-11-05 HTTP+SSE transport with a separate endpoint is not supported.

Activation

services.AddOrkeonMcp(configuration);         // the client β€” reads the "MCP" section
services.AddOrkeonMcpServer(configuration);   // the server, for a host that serves its tools

AddOrkeonMcp binds McpOptions (Enabled, default true; Servers β€” a dictionary of McpServerConfig keyed by server id: Transport Stdio (default) or Sse, Command/Args/Env for stdio, Url for HTTP) and registers McpToolProvider as a singleton. It registers no server: AddOrkeonMcpServer registers McpServer (+ McpServerOptions from MCP:Server: Name, default Orkeon, Version, empty by default β€” the version of the running release β€”, MaxConcurrency (4), ExposeOutput (false), ResourcesPageSize (100) and MaxResourceBytes (1 MiB)), which serves the container's IToolRegistry and calls every tool through its IToolInvocationPipeline β€” AddOrkeonInfrastructure() and AddOrkeonApplication() register both. Registering is not serving: the host runs RunStdioAsync β€” what orkeon mcp serve does β€” or ProcessRequestAsync itself. No setting starts the server: the MCP section carries no such key, and every runner built on RunnerHost refuses an unknown key at startup, servers declared or not. The server exposes tools, and /output as resources when ExposeOutput is on (below); prompts/* answer Method not found unless the host hands the server an IMcpServerExtension (orkeon mcp serve --crew does), and no option claims otherwise. The AddOrkeonInfrastructure(IConfiguration) overload calls AddOrkeonMcp itself, never 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" }
  }
}

The server and the client introduce themselves as Orkeon, with the version of the release they run (the one orkeon --version prints), in the legacy handshake (serverInfo, clientInfo) and in the _meta of the modern requests and of the server/discover and tools/list answers. MCP:Server:Version, when it is not blank, replaces the server's; nothing replaces the client's.

Per-server authentication, filter and timeout. Each MCP:Servers:<id> accepts:

  • Auth: Type is None (default), Bearer (Authorization: Bearer, the token read from the variable TokenEnv names) or Basic (UserEnv and PasswordEnv). The variables are read on every request, so a rotated token needs no restart. No credential is ever written in the settings.
  • Headers: extra HTTP headers, each a literal value or env:VAR. An Authorization header is refused here: use Auth. So are the headers the transport sets itself (Mcp-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Last-Event-ID); a static header never replaces one a request already carries.
  • Url: when Auth is set or a header reads env:VAR, the address must be https, or http on loopback, like TokenUrl: a credential is never sent in clear to another host.
  • Tools: Allow (empty keeps every tool) then Deny, applied before the tools reach the registry; a name in both is denied. An entry that matches no tool the server lists is reported as a warning (and in McpServerStatus.UnmatchedToolFilters).
  • CallTimeout: how long one tool call may take, 60 seconds by default. A silent server ends the call as a tool error (McpCallTimeoutException, error_type in the response metadata); a caller's own cancellation is not a timeout. The same bound holds for prompts/list, prompts/get, resources/list, resources/read and a legacy resources/subscribe (a TimeoutException naming the key). A duration that is not positive is refused; there is no way to switch the bound off.
  • ConnectTimeout: how long the handshake and the tool listing may take, 30 seconds by default, whoever connects the server. A server that stays silent fails the connection with an error naming MCP:Servers:<id>:ConnectTimeout.

OAuth 2.0. Auth:Type also takes oauth2-client-credentials and oauth2-device (OAuth2ClientCredentials and OAuth2Device are read too). The accepted spellings of Auth:Type are exactly None, none, Bearer, bearer, Basic, basic, OAuth2ClientCredentials, oauth2-client-credentials, OAuth2Device and oauth2-device; any other, a number included, is refused with that list, with these keys:

"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 (and DeviceAuthorizationUrl for the device flow) must be an absolute https address, or http on loopback: a credential is never posted in clear to another host. ClientId is required; ClientSecretEnv names the variable holding the client secret (required for client credentials, optional for the device flow) and is checked at startup and again on every token request. Scopes and Audience are optional.
  • The access token lives in memory only and is never written to disk. It is renewed 60 seconds before it expires. When the server answers 401, the request is sent again once with a new token; a second 401 is the answer (the call fails, nothing loops). Requests refused together share one renewal. The GET stream, when the server offers one, is opened again at once after a renewal, once in a row, then backs off.
  • oauth2-device shows a verification address and a code on the run's terminal (stderr) and waits for the person; the following renewals use the refresh token the provider issued, and ask for a new code only when it is refused. It is available in orkeon run and the REPL, which register an IOAuthLoginInteraction on their console. orkeon-host registers none, so a server in oauth2-device is set aside at startup with an error naming it; use oauth2-client-credentials there. The sign-in is done before the connection's handshake and before a call that finds the token expired, outside ConnectTimeout and CallTimeout: the wait for the person is bounded by the lifetime of the device code, not by those timeouts. Closing a session (the DELETE of Mcp-Session-Id) never starts a sign-in.
  • The token endpoint is reached through its own HttpClient, registered as orkeon-mcp-oauth (McpServiceExtensions.OAuthHttpClientName), with the default proxy and timeout and no redirect, and excluded from the LLM exchange log. The client secret and the tokens are never written in an error or a log line: what the identity provider echoes back is scrubbed.
  • A server whose settings cannot be read (a misspelt Auth:Type, a bad duration) is set aside at startup with one line naming it and the reason; the accepted Auth:Type spellings are listed in it.
  • Not supported: protected-resource discovery (RFC 9728) and dynamic client registration (DCR); the endpoints are settings.

Headers and Auth apply to the HTTP (Sse) transport; on a Stdio server they are refused, never silently dropped. A server whose configuration is invalid (a literal Authorization header, a header the transport sets, a plain http Url to a remote host with credentials, an absent environment variable, Auth:Type without its variable name, a non-positive timeout, Auth or Headers on a Stdio server) is set aside at startup with an error that names the settings key, never a value, and the run goes on without its tools. All servers share one HttpClient registered as orkeon-mcp (McpServiceExtensions.HttpClientName); it is excluded from the LLM exchange log, so neither the traffic nor the credentials are written there. The credentials are applied per request by an IMcpRequestAuthenticator, not carried by the client; a variable that is empty when a request is made fails that request with the same key-naming error instead of sending it unauthenticated. The client follows no HTTP redirect: a 3xx answer is a failure, so the static headers and credentials never reach a host other than the configured one.

Nothing is expanded in the section. Command, Args and Env pass as written, and the server inherits the environment Orkeon runs in: a ${NAME} or %NAME% reference in Command, Args, Url or an Env value refuses the start, before any server connects, with its correction (a variable reference is never expanded).

The shared runner host honours the section on its own. orkeon run β€” and every runner built on RunnerHost β€” calls AddOrkeonMcp when MCP:Servers declares at least one server and MCP:Enabled is not false, then connects every server in an explicit startup step (McpStartup) before the crew loads β€” and before --validate judges the crew and --list-tools prints the manifest, so the three see the same tool surface. A server that cannot be connected (a command that does not exist, an endpoint that does not answer, a handshake still pending after 30 s) costs one error line naming it, on the log and on stderr, and the run goes on. A stdio server's own stderr is read as it writes it β€” each line to the log at Debug (MCP server '<id>' stderr: …), so a server that writes a lot there never blocks on it β€” and a server that stops before answering says why: its exit code and the last line it wrote on stderr join that error line (Transport disconnected: the MCP server exited with code 1; its last line on stderr: …). The tools are registered under their own names, without a server prefix, and a name the registry already holds β€” a built-in tool, a script tool, or a tool of a server connected earlier β€” is refused: the MCP tool is not registered, one error line names the server and the tool (The tool 'file_read' of MCP server 'x' collides with an already-registered tool and was not registered), on the log and on stderr, and the tool that held the name keeps it, including after that server disconnects. The server's other tools are registered normally (--list-tools shows the merged surface). orkeon-host connects them too: built on RunnerHost, it reads the same section and runs the same step once, from its first hosted service, when the daemon starts β€” before the chat channel can deliver a message that loads a crew β€” and disconnects the servers when it stops, after the drain. The same settings give orkeon run and orkeon-host the same tools; an unreachable server costs the same error line and the daemon starts without it. In any other embedding host, MCP stays a library surface β€” the host calls AddOrkeonMcp(configuration) (or the config overload) and connects the servers itself.

orkeon-repl, and the scripts. orkeon-repl registers the section the same way and connects the servers before it loads its commands; a server that fails costs the same one line, and the REPL starts. The tools a server brings enter the tool registry, and the scripts' catalogue reads it beside the container's tools (ScriptToolCatalogue): a command's tools namespace, an agent's .tools([...]) in a .ork.ts crew and ctx.llm.act reach an MCP server's tools β€” in the REPL, and under orkeon run, where a procedural script's servers are connected before it runs. Whisper through MCP wires a speech-to-text server this way.

The library ships no hosted service for this: an embedding host resolves McpToolProvider and calls ConnectServerAsync(serverId, config) for each configured server, explicitly β€” which is exactly what the runner host's startup step does, and what orkeon-host's connection service calls. A host that serves its tools calls AddOrkeonMcpServer(configuration), then resolves McpServer and runs RunStdioAsync(reader, writer) over the streams it owns β€” what orkeon mcp serve does. orkeon-host serves no MCP.

MCP tools and crews

A connected MCP tool is a tool like any other: a crew agent lists it by name, in YAML or in a .ork.ts script, and receives it.

agents:
  analyst:
    tools: [search_issues]   # a tool exposed by an MCP server declared in MCP:Servers

CrewFactory attaches every tool the registry resolves; there is no narrower interface than IBaseTool to implement. The servers are connected before the crew loads, so under StrictTools β€” the runners' default β€” a crew that names a tool of a server that could not be connected fails at load with the ordinary unknown tool(s) line. --list-tools and --validate see the MCP tools, McpServer re-exposes what the registry holds - every tool, or those orkeon mcp serve --tools names (AllowedTools); the host of orkeon mcp serve registers no human_input -, and C# code can resolve one with IToolRegistry.GetToolByNameAsync(name). The observed-run decorator of --events jsonl wraps the tools registered in DI; MCP tools reach the registry at run time and are not wrapped.

Serving the tools with orkeon mcp serve

orkeon mcp serve [--settings <file>] [--tools a,b,…] [--max-concurrency <n>] [--expose-output] [--crew <a.yaml> [<b.yaml> …]] [--allow-external-mounts]

The verb serves an Orkeon host's tools to an MCP client over stdio β€” the transport by which Claude Desktop, editors and agent frameworks start a local server: the client launches the process, writes one JSON-RPC message per line on its stdin and reads the answers on its stdout, one per line; closing stdin ends the server.

  • The host is the one a run builds. The settings resolve like orkeon run's, anchored at the current directory: --settings, else appsettings.json there, else an appsettings/appsettings.json found walking up, else the per-user file of orkeon init, else the ORKEON_* environment variables alone; the file used is named on stderr. The mounts it declares (Orkeon:FileSystem:Mounts) are what the file tools reach, and the MCP servers it declares under MCP:Servers are connected first, their tools served too. What is served is what orkeon run --list-tools prints for the same settings, human_input aside: that tool answers for the operator of a run, and the client of an MCP server has a human of its own. No crew is loaded, so no tool a .ork.ts crew declares is served: those are registered when their crew loads.
  • --crew <a.yaml> [<b.yaml> …] serves crews as tools. Several crews go space-separated after one flag, which cannot be repeated (like --mount). Each crew is loaded once at the start through the entry point orkeon run and orkeon eval run --crew load crews with, in a host of its own that carries what orkeon run gives a crew: the settings (--settings, else resolved from the crew's folder), the budget, the guardian, and the permission gate (Orkeon:Security:PermissionGate, ask refused without a channel). A crew that does not load, a folder outside the working directory without --allow-external-mounts, or two crews that give one name refuse the start, named; so does a run_crew_* name a tool of the host already holds. Only the crews named are served: no tool takes a path.
    • The tool is run_crew_<name>: the crew's name, lower case, every run of other characters one underscore. Its inputSchema is an object with one required string property per {placeholder} found in the tasks' description and expectedOutput (matched without regard to case, in order of first use) and no other property. A number or a boolean is read as its text; an object, an array or null is refused, so is an unknown or a missing argument (-32602, the names listed). The result is the crew's final output; a crew that fails is a result with isError, not a JSON-RPC error.
    • Progress: when the call carries _meta.progressToken, the server sends one notifications/progress per finished task (progress 1 to total, the number of tasks, with a message) before the answer; without a token nothing is sent. notifications/cancelled cancels the run.
    • Prompts: every task is the prompt <name>_task_<n> (1-based), its arguments the placeholders of that task, the message its description and expected output interpolated. The prompts capability is advertised only with --crew.
    • Calls of one crew run one at a time. The crew's host is shared by its calls, and so is what the host mounts (/output, AUTO_SUMMARY.md, the checkpoints), so a second call of a crew waits for the first (calls of other crews, and every other tool, run alongside). Each call still runs in a scope of its own, with its own task state, and a client's notifications/cancelled cancels the running crew: its agents see the token and the call is not answered.
    • The run is recorded like any run of the host. With Orkeon:RunHistory:Enabled on in the crew's settings, each call is a run of the history: run.started, the task events, run.finished, under its own run id (the one the checkpoints use), read with orkeon runs. With the history off nothing is written. run.finished carries success, exitCode, durationMs, cappedTasks and missingDeliverables, and no token fields (see the run event bus). The events carry no token count: the model's usage is not attributed per call.
    • There is no offline mode. The serve host reads the real settings and a crew calls the models they declare; the mock provider is reached only by pointing the profiles at it.
    • The progress total is the number of tasks of the crew; a retry or a hierarchical manager can run more task attempts than that, and the progress then stops at total.
  • The permission gate is not consulted for the client's calls (GateExempt). The server's calls run through the guarded invocation point (Guardian, result sanitizer, audit) as the caller mcp, marked GateExempt: the AI client that launched orkeon mcp serve over stdio is not passed through the IPermissionGate. The reason: the client is the operator's own agent, and the operator already chose what it may reach (the settings, --tools, the mounts); stdout carries the protocol, so an ask would have no channel to a human and every call needing approval would be refused. A crew served with --crew is another matter: its own agents are gated as in orkeon run.
  • --tools a,b,… serves the named tools only (comma-separated); a name the host does not have refuses the start, naming it. The other tools are neither listed nor callable, even those an upstream MCP server registers later (tools/list_changed): the allow-list is the server's own (MCP:Server:AllowedTools), not an unregistration. The tools of --crew are not subject to it.
  • Requests run concurrently (--max-concurrency <n>, at least 1, default 4, or MCP:Server:MaxConcurrency). Each request is one task; at most n run at once and the others wait their turn, so a fifth slow call starts when one of the first four ends. A --crew call holds no slot: it waits for its crew (one run per crew at a time), so tools/list and ping stay answered meanwhile. The answers go through one channel to one writer: two answers never interleave on stdout, and they may arrive in a different order than the requests (the client matches them by id). When stdin closes, every request already read is answered before the server ends.
  • notifications/cancelled cancels the request its requestId names, whether it runs or still waits for its turn: the tool call receives the cancellation, and a cancelled request is never answered, as the specification asks. An id the server does not know is ignored. A second request with an id already in flight is refused (-32600). McpServer is a singleton with no scoped dependency, so a request has no DI scope of its own.
  • --expose-output (or MCP:Server:ExposeOutput) serves /output as read-only resources, off by default. resources/list pages the files under /output in path order (ResourcesPageSize per page, an opaque nextCursor), each as orkeon:///output/<path> with its name, mimeType and size; resources/read returns a file as text when it is UTF-8 text and as a base64 blob otherwise, up to MaxResourceBytes. Everything goes through IFileSystemService: the /output mount must exist and grant Read (a warning on stderr says when it is not mounted), and the URI is parsed strictly β€” no ./../empty segment, no query or fragment, no %2f, anything but orkeon:///output/… refused. /workspace and every other mount are never exposed, no URI or error carries a physical path, and there is no resources/subscribe and no resources/templates/list. Without the flag resources/* answer Method not found.
  • Every call is guarded: the invocation point of the server, under the caller mcp β€” a blocked call never reaches the tool, a result arrives truncated and tagged as data, and the audit trail records each call under the agent mcp; a blocked or failed one also reaches stderr, through the trail's log sink (Agent=mcp).
  • Stdout carries the protocol and nothing else. Every log line, warning and diagnostic goes to stderr β€” where an MCP client records a server's output β€”, and so do --help and the usage errors.
  • Exit codes: 0 the client closed the stream (or --help); 1 a usage error, a refused setting (an unknown key, a mount the settings declare that cannot be mounted, any other setting the runner host refuses β€” one ERROR: line names it), a --tools name the host does not have, a --crew refused at start (a crew that does not load, a name given twice, a run_crew_* name a tool already holds), a serve started by another serve (below); 2 an unexpected error. Ctrl+C or SIGTERM ends the serve with 0, the crews and the upstream servers disposed on the way out.

A client configuration β€” Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "orkeon": {
      "command": "orkeon",
      "args": ["mcp", "serve", "--settings", "/home/me/orkeon/appsettings.json"]
    }
  }
}

A client starts its servers in a working directory of its own choosing: name the settings file with --settings, or rely on the per-user file of orkeon init.

A serve never starts under another one. Before it connects the MCP servers of its settings, a serve sets ORKEON_MCP_SERVE in its own environment β€” every process it starts inherits it, and it is cleared when the serve ends β€” and a serve that finds it set refuses to start: exit 1, and one line on stderr, which the serve that started it joins to its connection error (orkeon mcp serve: refused to start: another `orkeon mcp serve` started this one (ORKEON_MCP_SERVE is set), …). Settings that declare orkeon mcp serve itself under MCP:Servers therefore cost that one line: remove the entry, or declare both servers in the client. orkeon run and orkeon-host set no marker, and can use an orkeon mcp serve started on other settings. Like ORKEON_DEBUG, the variable is also read by the ORKEON_ configuration layer, as a key (MCP_SERVE) no setting is.

Notifications, pagination and prompts (the client)

  • Pagination. tools/list, resources/list and prompts/list follow nextCursor until a page names none (McpClient.ListToolsAsync, ListResourcesAsync, ListPromptsAsync). A server whose cursor never ends fails the listing after 100 pages, or after 10 000 items, (InvalidOperationException) instead of growing it without end.
  • Notifications. A frame without an id is a notification: IMcpTransport.Notifications is a ChannelReader<JsonRpcNotification> (256 entries, DropOldest, one warning per dropped entry). The stdio transport feeds it from the server's stdout; the HTTP transport feeds it with the notifications of an SSE-framed answer (as they arrive, not after its final message), of the GET stream and of subscriptions/listen. A request the server sends to the client (sampling/createMessage, roots/list, elicitation/create) is answered -32601 on stdio and on HTTP: the client offers none of them; a ping on HTTP gets the empty result the specification requires.
  • Subscriptions. On a modern server over HTTP, McpToolProvider keeps a subscriptions/listen request open (McpClient.ListenAsync: tools, prompts and resources list changes, plus the subscribed resources); when the server ends the stream it is opened again after the same backoff and the tool list is marked stale, since what the server said meanwhile is lost. A server that refuses the request is not asked again. The stream is not bounded by CallTimeout. On a legacy server, McpToolProvider.SubscribeResourceAsync sends resources/subscribe (UnsubscribeResourceAsync ends it and drops the cached read) (refused when the server does not announce resources.subscribe) and the updates arrive on the GET stream. A notifications/resources/updated invalidates only the cached read of that resource (McpToolProvider.ReadResourceAsync caches the reads of subscribed resources and nothing else, and a read that was in flight when the update arrived is not kept); the tools are not listed again. When the GET stream is opened again or the session initialised again, the cache is dropped and the subscriptions are sent again, since the notifications of the gap are lost.
  • notifications/tools/list_changed. McpToolProvider watches each connected server. After a 500 ms wait (the notifications that arrive meanwhile are absorbed) it lists the tools again, applies the server's Tools filter, unregisters the tools the server dropped, swaps the ones whose definition changed for a new adapter in one registry step (IToolRegistry.ReplaceToolAsync: the name never stops resolving), and registers the new ones. A name another tool holds (a built-in, a script tool, another server's) is left to it and warned about as mcp.tool.rejected; McpServerStatus.RejectedToolNames names it. A task already running keeps the tool instances it was given: only the crew built afterwards sees the new set. The notifications are read as they arrive, so a flood of other frames cannot push a list_changed out of the bounded channel; one that arrives during a re-listing triggers another. A failed re-listing keeps the tools registered so far and is logged.
  • Prompts. McpClient.ListPromptsAsync and GetPromptAsync(name, arguments) speak prompts/*. The built-in tool mcp_prompt_get (server, name, arguments) hands a prompt to an agent, or lists the server's prompts when name is empty; it is registered by AddOrkeonMcp. The prompt text is untrusted content of the server and a prompt-injection vector: it reaches the model as the result of a tool call, nothing more, and a server can put instructions in it. The tool declares ToolAccess.Read, so the permission gate lets the call through without asking, in every mode: connect only servers you trust, or keep the tool out of the tools: of an agent that must not read their prompts.

Honest limitations

Aligned with Known limitations:

  • Subscriptions β€” subscriptions/listen runs on HTTP only (the stdio client hears every notification the server sends); the 2026-07-28 filter shape (notifications.toolsListChanged, promptsListChanged, resourcesListChanged, resourceSubscriptions) is the one this client sends, checked against its own fake servers and the reference server, not yet against the published schema.
  • No sampling, roots or elicitation β€” a server request for them is answered -32601: sampling would make Orkeon call an LLM for the server outside the budget, guard and cost of a run; roots would expose physical paths (VFS rule); elicitation waits for durable human-in-the-loop.
  • No multi-round-trip requests (MRTR) β€” a modern input_required interim result is surfaced as an explicit tool error, never as partial data.
  • OAuth is client credentials and device flow only β€” no authorization-code flow, no protected-resource discovery (RFC 9728), no dynamic client registration (DCR); the device flow needs a host with a terminal (not orkeon-host); tokens are never persisted, so a device sign-in is asked again at the next run.
  • HTTP+SSE 2024-11-05 not supported β€” the transport with a separate message endpoint is refused; Streamable HTTP is the HTTP transport. Interop against the reference server runs nightly (McpReferenceServerInteropTests, MCP interop).
  • 2025-03-26 excluded (mandatory JSON-RPC batching).
  • The server speaks stdio only (orkeon mcp serve, or RunStdioAsync / ProcessRequestAsync in a C# host): no HTTP transport, prompts and crews as tools only for the crews --crew names (a client never gives a path), and resources are /output only (read-only, no resources/subscribe).

Experimental status

Every MCP type carries [Experimental("ORKEXP004")]: referencing them from your code is a compiler error until you suppress the diagnostic β€” that suppression is your opt-in acknowledgement that the surface (notably the wire types) may still move. See Experimental APIs.


See also: Opt-in subsystems Β· Experimental APIs Β· Known limitations Β· Back to index