0021 - Our own Tool trait; the MCP SDK is an adapter behind a feature
Status: accepted
Context
The MCP server offers read-only tools over the storage traits. Rust has an
official SDK for it, rmcp, which defines tools with macros on a handler
(#[tool_router], typed parameters) and brings tokio.
Three facts weigh against building the server on those macros:
- The SDK moves.
rmcpwent through three major versions in five months (1.0 in March 2026, 2.0 in June, 3.0 in July) and keeps tightening behaviour between minors. The MCP specification itself changed shape (a session with aninitializehandshake, then a stateless revision), and clients still speak both. - The tool list will grow, and not only by us (ADR-0006). An application
embedding the library adds the tools that drive its own views; a server adds the
tools its users’ rights allow; a later version adds writing, validation,
export. A set of tools fixed at compile time by macros on one
implcannot be extended by a caller, and cannot put the caller’s tool before a builtin one. - tokio must not reach the libraries. Neither workspace has tokio today, the
ETP client is blocking, and
energyml-coreis wasm-clean (ADR-0007). A crate that only wants the registry (a desktop application, a test, a different transport) must not pay for an async runtime.
Decision
ToolandRegistryare ours, and SDK-independent. A tool is a value with a name, a title, a description, a JSON Schema for its arguments, hints, and anasync call(&ToolContext, args)that answers aToolOutputor aRefusal. The registry lists tools in registration order and tries what the caller registered first (Registry::with_tool). What a tool needs beyond the store travels inToolContext::extensions.StoreProvideris the one point where the store of a request comes from (a fixed store for stdio, a per-request store behind HTTP).rmcpis an adapter inenergyml-mcp’sservermodule, behind a Cargo featureserverthat is off by default. It implementsServerHandlerby hand (list_toolswalks the registry,call_toolcalls it) and nothing else. Normcptype appears in a public signature ofenergyml-mcp; errors carry the SDK’s messages as text.- tokio is confined to the feature.
serve_stdiobuilds its own single-threaded runtime and blocks the calling thread, so callers see a plain function. Each tool call runs on a blocking thread aroundfutures_executor::block_on, because the ETP store blocks inside itsasyncmethods, and is raced againstLimits::call_timeout; a timeout answers the refusaltimeout. - Two kinds of failure, as the specification has them. An unknown tool is a
JSON-RPC protocol error. Everything else a tool declines is a tool result with
isError: true, carrying{"refusal": ...}(ADR-0005): the model can read it and correct itself. Never an empty list. - The tool schemas are written by hand as
json!values, not derived from Rust types, so that a snapshot test oftools/listguards the contract clients see and a refactor cannot move it silently.
Consequences
- Replacing the SDK, or writing the JSON-RPC loop by hand for stdio, rewrites one
file and touches no tool and no test of a tool. The adapter is a few hundred
lines; a new
rmcpmajor costs an afternoon in that file. - The adapter is tested with the SDK’s own client over an in-memory duplex stream, so the server and the client are not both written by us.
- The server can be handed a registry with the caller’s tools first, at no cost to
the builtin ones; a hosted server (
retp mcp, a future HTTP server) shares the same tools by providing a differentStoreProviderand transport. - We write the tool schemas ourselves; a schema derivation crate is not a dependency.
- A call that times out is abandoned, not stopped: a blocking thread cannot be cancelled. It ends on its own and its answer is dropped. At exit the process gives a stuck call a short grace period and leaves anyway.
- Features of the SDK we do not use (resources, prompts, subscriptions, tasks) are
not offered; the server advertises the
toolscapability only. Offering one later is an addition to the adapter and, if it needs a trait, to this crate. - The contract with clients is the tool names and their arguments, not the Rust API: a tool name never disappears, an argument added later is optional, an incompatible change is a new tool name.