Transport-agnostic MCP server.

Receives decoded JSON-RPC messages, dispatches to the Registry for tool/resource operations, and returns response maps. Transports (stdio, SSE) call handle_message/2 and write the response back over their I/O channel.

Supported Methods

• initialize -- MCP handshake, returns server capabilities and serverInfo (name "raxol"; version the :server_version option, default this package's version)
• notifications/initialized -- client acknowledgement (no reply)
• ping -- health check
• tools/list -- list the registered tools this caller may call
• tools/call -- invoke a tool
• resources/list -- list registered resources
• resources/read -- read a resource
• prompts/list -- list registered prompts
• prompts/get -- render a prompt with arguments
• logging/setLevel -- set server log level
• completion/complete -- auto-complete tool arguments

Notifications

The server can push notifications to connected transports. Transports subscribe via subscribe/2 and receive {:mcp_notification, map()} messages.

Elicitation

When Raxol.MCP.Authorizer returns {:ask, prompt}, what happens depends on whether the client can be asked. A client that advertised the elicitation capability at initialize (and has a subscribed transport) is sent a real elicitation/create request; anything else gets the machine-readable authorization_required deny.

A parked call never holds up its caller. A handle_message/3 caller blocks until it gets a reply, so tools/call returns nil immediately and the call's eventual response is pushed on the subscriber channel:

client                     server                    transport
tools/call  ------------->  ASK -> park, return nil ->  (unblocked)
           <-------------  elicitation/create (push)
response   ------------->  resume, return nil
           <-------------  tools/call response (push)

Returning nil is what keeps such a transport (Transport.SSE) from deadlocking: it stays free to READ the client's answer. A request/3 caller (Transport.Stdio) never blocks, so its call simply stays outstanding: the prompt is still pushed, but the call's response, or deny, is the REPLY to that request. Until then cancel/2 with the call's request_ref reaches it, whether it is still waiting for the answer or, once approved, running.

A parked call is always closed, exactly once, by one of five paths: an approval (runs the tool), a decline/cancel/unapproved accept, an error response, a timeout (:elicitation_timeout_ms, default 60s), or, on a full server, making room for another connection's call (see below). Every path but approval resolves to the same deny -- silence is not consent. Dropping it is the exception: cancel/2, its request/3 caller exiting, or its connection going away ends it with no answer, and kills the tool if an approval already started it.

Parked calls are capped twice. A connection may have at most :max_parked_elicitations (default 32) calls parked at once, and the server at most :max_parked_elicitations_total (default 256) across every connection. A parked call holds no callback worker, so without the first a client could park calls as fast as it sent them; without the second, every connection that can be asked (up to :max_client_capabilities) could park its full share. The total defaults to eight connections' full share: each parked call is a timer and a small entry in the server's state, so 256 bounds that state while eight clients can each use their whole share at once. The per-connection cap may not exceed the total; the server refuses to start if it does.

Past the per-connection cap an ASK gets the authorization_required deny with the detail too many elicitations pending. The total is shared by every client, so it is not first come, first served: when the server is full, an ASK from a connection holding fewer parked calls than the connection holding the most closes that connection's oldest parked call (with the deny and the detail too many elicitations pending on this server) and parks in its place. Any other ASK on a full server gets that deny itself. So a client that spreads its calls over several connections (a network transport mints one per stream) cannot hold every other client's approvals; it only crowds out its own. What remains: a client with more elicitation-capable connections than the total, each holding one call, can still keep a newcomer's call from lasting. Bounding that needs a per-peer identity no transport gives the server (Transport.SSE trusts the client's session id, and a remote address is shared behind a proxy).

Sensitive tools

A tool annotated destructiveHint: true or sensitive: true (see Raxol.MCP.ToolDef.sensitive?/1) must not be served without an authorizer. The server REFUSES TO BOOT when a static one is already registered, and denies at tools/call for one registered afterwards -- the boot check alone would be bypassable by registering late. Derived widget tools (the tool defs Raxol.MCP.TreeWalker derives, which Raxol.MCP.ToolSynchronizer registers with derived: true; see Raxol.MCP.Registry.register_tools/3 and Raxol.MCP.Registry.static_tools/1) are left out of the boot check: they come and go with a session's view, so a restart of this server with live sessions would otherwise refuse to boot. A static tool with a dotted name (agent.reset), or one whose tool map carries a :derived key, is still checked. The tools/call refusal covers both.

Unknown tools

A tools/call naming no registered tool answers JSON-RPC -32601, unless the :unknown_tool_reply option says otherwise. It is a 1-arity function given the tool name (a binary); a binary it returns is sent back as an isError tool result with that text, and nil keeps the -32601. An app whose tools come and go uses it to tell a client that cached a name what happened to it: Raxol.Application passes Raxol.Headless.McpTools.unknown_tool_reply/1, which names a stopped session. The server itself reads nothing into a tool name.

Client capabilities

What each connection advertised at initialize is kept until that connection's subscriber exits. A connection that never subscribes has no exit to wait for, so the map is also capped by :max_client_capabilities (default 1024). Past the cap the oldest entry without a live subscriber is evicted first, and a live one only when every entry has a subscriber. Each eviction emits [:raxol, :mcp, :server, :client_capabilities_evicted]. An evicted connection keeps working; it just cannot be asked, so an ASK becomes the deny, until it sends initialize again.

Callback isolation

Tool, resource, prompt, completion, and authorization callbacks run in linked, monitored workers rather than in the shared server process. The server remains responsive to other clients, notifications, subscriber exits, and elicitation timers while callback work is pending.

:max_in_flight bounds concurrent callback workers across every connection (default 32); it does not count parked calls, which hold no worker. One connection may hold at most :max_in_flight_per_connection of them (default half of :max_in_flight, at least 1), so one client running many slow calls at once (a stdio peer included) leaves the rest to other connections. It is a share per connection id, not per peer: handle_message/2 callers use the stdio transport's :default id and so share its slots, and connections together can still fill :max_in_flight (two at the default share do). The share may not exceed :max_in_flight; the server refuses to start if it does. Both counts are kept in this process and checked when a worker starts, so concurrent requests cannot both pass a check meant for one. :callback_timeout_ms bounds each worker's lifetime (default 300,000 ms). Work above either concurrency bound receives a structured busy error. A finite timeout passed to handle_message/4 also cancels that call's worker if the caller stops waiting. request/3 callers cancel explicitly with cancel/2, and are monitored: when one exits, its outstanding requests are cancelled.

params must be an object. "params": null is treated as absent; any other non-object params is answered -32602 before the method is looked at. method must be a string: a request naming anything else is answered -32600, and such a notification is dropped. logging/setLevel answers an unknown level with -32602, and is otherwise gated by :read_authorizer like the other read surfaces.