Repository navigation
v0.25.0
Docs: an "In-process client" section with copy-pasteable recipes for driving coding agents and
CLIs yourself. Driving a vendor CLI or ACP agent is not something toolnexus maintains as library
surface; agents change their flags too often. Instead the new section shows how to do it on the
public API that already exists: createInProcessClient (generate, or GenerateStream in Go)
plus toolkit.serve with the MCP profile. Four pages: an overview, a complete ACP agent recipe
(spawn, initialize, session/new with your toolkit as an MCP server, session/prompt, streamed
agent_message_chunks), a one-shot CLI recipe (claude -p, codex exec: render the request, run
the process, parse text or tool calls), and "Extend it" (your own agent, isolation, model selection
over configOptions, permission policies). Recipes are JavaScript, Python and Go, each run against
a fake agent/CLI and live against Claude Code; per-agent isolation and model notes are labelled
with the version and date they were verified on. The section is also published as plain markdown
for agents at /_llms-txt/in-process-client.txt (listed in llms.txt). The research behind the
notes is in docs/references/acp-agent-isolation-2026-11-05.md. Not done: recipes for the
Java, C#, Elixir, Clojure and Rust ports; two Python serve gaps found while verifying are
documented, not fixed (mcp={} exposes no tools; GET /mcp gets no response, which hangs the
Claude ACP adapter).
MCP 2026-07-28 client: hosted servers, OAuth login, remote skills and tool search (all eight ports)
toolnexus now speaks MCP 2026-07-28 to every server first, and can log in to OAuth-protected ones.
Until now each port drove its MCP SDK (or, in Elixir and Clojure, our own client) on the 2025 protocol,
and an OAuth-protected server meant pasting a bearer token into headers. Hosted servers such as
GitHub's already speak 2026-07-28, and most of them ask for OAuth.
- Discover first, nothing to configure. Each server is asked
server/discoverbefore anything else.
A 2026 server is used through toolnexus's own client (no SDK) over stdio or Streamable HTTP. An older
server answers that with an error, an HTTP 400/404/405/5xx or silence on stdio (5 s), and gets
exactly the client you had before, frozen.mcp.jsonfiles keep working unchanged, and tool names,
result mapping, filters, timeouts and status are the same on both paths. - Questions a tool asks mid-call (2026
input_required) arrive through yourwaitForas §10 requests:
form →input, URL →authorization. With nowaitForthe call returns{status:"pending"}and resumes
at the round it paused on. Atools/callis never re-sent after a timeout, 5xx or dropped connection,
because the server may already have run it. - OAuth login (new optional
authper server): protected-resource and authorization-server
discovery, PKCE S256 withresource,state/isschecks, refresh (one request shared by concurrent
callers) and step-up oninsufficient_scope. The client identity is a pre-registeredclientIdor a
Client ID Metadata Document. Dynamic Client Registration is deliberately not supported; without an
identity you get an error naming the issuer andauth.clientId. Two modes:autoopens the browser
and takes the callback on127.0.0.1;pausehands your host a §10authorizationrequest and you
answer it withdata.callbackUrl. New load/toolkit optionstokenStore(default in-memory) and
openUrl. Tokens, codes and secrets never reach logs or error text. - Skills over MCP (SEP-2640): a server that offers skills adds them to the same
skilltool as your
local ones, with digest and path-containment checks. - Lazy tool search (
"toolSearch": true, optional"description"): the toolkit exposes
<server>_search_toolsand<server>_call_toolinstead of every tool, for servers with hundreds of
tools. Yourtoolsfilter anddisableToolsapply first.
Contract: SPEC §2 (2.2a fallback rule and resolved questions), §2A.1/§2A.1a, fixtures examples/mcp-2026/;
change openspec/changes/upgrade-mcp-2026-07-28.
Not done yet (tracked in that change and #134):
- The server side.
serve /mcpstill speaks the pre-2026 profile; the 2026 server, itsauth
(PRM, 401/403, JWT via JWKS, principal) and the in-process dev authorization server come in a follow-up
on top of the MCP handler from PR #140. When that lands it is BREAKING: old-era clients will no
longer be able to callserve /mcp. The MCP SDK dependencies stay for now because they power the frozen
fallback; golang keepsmark3labs/mcp-go. - OAuth on the frozen fallback: JS, Python, Java and C# attach the bearer per request and re-run the
flow on a 401. Rust (rmcp), Elixir and Clojure send the token as a fixed header at connect, so a token
that expires mid-session is not refreshed on an old server. resourceTools()(list_mcp_resources/read_mcp_resource) sees fallback servers only.- No progress notifications or
nextCursorpagination on the 2026 path; roots, sampling, logging and the
Tasks extension are out of scope. - Elixir and Clojure re-encode a search hit's
inputSchema(keys sorted) instead of passing the server's
bytes through. Clojure resumes only one input request per MRTR round without awaitFor, and its
autocallback page needs a browser (koine gives a server no query string). - Not yet verified: the 8×8 client×server interop matrix on the shipped code, and live Keycloak/GitHub
logins (the Go spike passed both).
MCP 2026-07-28 on the server side: MCPHandler speaks the new wire when you opt in, with OAuth metadata and skills over MCP, in all eight ports. The 2026-07-28 client (change upgrade-mcp-2026-07-28) could talk to GitHub's hosted server but not to a toolnexus server: MCPHandler refused 2026-07-28, so a toolnexus client always fell back to the old wire. Now add "2026-07-28" to ProtocolVersions and the same handler, with the same hooks, serves it:
- The stateless wire.
server/discover, header validation (-32020header mismatch,-32022unsupported version, checked before auth),resultTypeand_metaserverInfo on every result,tools/listsorted by name withttlMs/cacheScope. Noinitialize, no session id, no GET stream. List both"2026-07-28"and a 2025 version to serve old and new clients on one mount; without the opt-in nothing changes (an old-only handler answers a 2026server/discoverwith HTTP 400, which the 2026 client takes as its cue to fall back). - Confirm and suspensions without elicitation streams. A
BeforeCallconfirm becomes aninput_requiredround the client answers through itswaitFor; a tool that returns a §10Pendingrequest gets the answer back asToolContext.Answeron the retry.BeforeCallstill runs on every round, so a forgedrequestStatecannot get past a deny. - Skills over MCP (SEP-2640).
ListSkills(ctx)publishes skills (skills/list,skills/get,resources/readofskill://URIs with sha256 digests and traversal-safe URIs);LoadMCPSkills(dir)reads a skills folder. A toolnexus client loads them into itsskilltool byte-identical to the local copy. - OAuth for the server.
MCPServerAuth{Issuer, Scopes, Verify?}gives you anAuthenticatehook (bearer token, RS256 JWT checked against the issuer's JWKS — signature,iss,aud,exp— or your ownVerify; per-tool scopes; exact 401 / 403insufficient_scopechallenges) and the RFC 9728 metadata handler to mount at/.well-known/oauth-protected-resource. The verifiedPrincipalis whatIdentityFrom(ctx)returns. AnyAuthenticatehook can now return anMCPAuthErrorto pick 401 or 403 and the challenge. - Bring your own authorization server. The auto-approving dev authorization server the suites and the interop run use (pre-registered and Client ID Metadata Document clients, PKCE, refresh, no dynamic client registration) is test tooling in every port's test tree, not library API: nothing named
StartMCPDevAuthServer/McpDevAuthServer/start_mcp_dev_auth_serverships, so a server that approves everyone cannot end up in production by import. - Proven end to end by
interop/mcp2026/run.sh: the Go 2026 client against the Go server — discover, MRTR input, confirm, skills, tool search, OAuth with a pre-registered client id, with a CIMD URL and with a scope step-up, and the fallback against a handler without the opt-in. Shared wire cases:conformance/mcp_handler/cases.json(mcp2026_*).
Not done: Serve(addr, {mcp}) still serves the pre-2026 profile (switching it is the BREAKING step change upgrade-mcp-2026-07-28 describes, left for a decision); per-tool scopes are enforced only on the 2026 wire (older wires check "*" only); a multi-round tool sees only the latest round's answer; the cross-port interop matrix (every port's client × every port's server) and the Keycloak live run against the server are not run here; the site API pages for the new symbols are not written. Tracked in openspec/changes/add-mcp-2026-server-handler.
MCP serve you can mount yourself, with auth, per-request tools and a confirm gate, in all eight ports. Serve(addr, {mcp}) owns its port and shows everyone the same tools, so a host that wanted
an MCP endpoint behind its own login had to write its own MCP server (#139). Now
tk.MCPHandler(cfg) returns an http.Handler to mount on your own mux, behind your own TLS, CORS
and OAuth, with plain hooks:
Authenticate(r)runs on every request; an error is HTTP 401 with yourWWW-Authenticateheader.
What it returns reaches every hook and tool viaIdentityFrom(ctx).ListTools(ctx)decides the tools per request (they can be built at runtime). Atools/callfor
a name not in that list is "tool not found" and never runs.NotifyToolsChanged()tells connected
clients to re-list.BeforeCall(ctx, tool, args)returns allow, deny or confirm. Confirm asks the user through MCP
elicitation when the client supports it; otherwise the caller gets your own result (for example
"re-call with this nonce") or a plain "confirmation required" error.Tool.Annotations(title,readOnlyHint,destructiveHint,idempotentHint,openWorldHint)
go out unchanged;OnCallreports identity, duration, error and result size for metering;
ServerInfo(ctx)brandsinitialize(now withtitle); resources and prompts hooks; your own
SessionIDs, orStateless(optionally with a fixedStatelessSessionIDfor clients that expect one).- Structured results. A tool can return
ToolResult.Structuredand declareTool.OutputSchema;
MCP serve sends them asstructuredContentandoutputSchema, with a JSON text block when the
tool sets no text.ToolResult.Metagoes out as the result's_meta, and a request's
params._metais readable in hooks and tools viaMCPRequestMetaFrom(ctx). All optional:
tools that do not set them produce exactly the same output as before, onServetoo. - Protocol versions you can trust.
ProtocolVersionsper handler; the default is 2025-06-18 only.
2025-11-25 can be turned on (the handler implements its one server-side rule change: bad tool
arguments come back as an error result, not a protocol error). 2025-03-26 is not accepted (it allows
batches, which the handler rejects) and 2026-07-28 waits for #134 — listing them does nothing.
Every port ships it in its own native handler shape: Go http.Handler, JS Node request listener
(toolkit.mcpHandler), Python ASGI app (toolkit.mcp_handler), Java JDK HttpHandler
(toolkit.mcpHandler; give the HttpServer a multi-threaded executor), C# McpHttpHandler over
HttpListenerContext or a host-supplied McpHttpExchange (toolkit.McpHandler), Elixir Plug
(Toolnexus.mcp_handler/2), Clojure Ring handler (toolnexus.mcp-handler/mcp-handler; SSE bodies are
lazy seqs, so the Ring adapter must stream seq bodies), Rust hyper Service (toolkit.mcp_handler,
serve feature). A shared fixture, conformance/mcp_handler/cases.json, pins the wire and every
port's suite replays it.
Port notes: outside Go, beforeCall receives the parsed arguments object rather than raw JSON bytes.
The Java, Elixir and Clojure GET streams send a : keepalive comment every 15 s (Java and Elixir) or
end on session DELETE (Clojure), because those servers cannot see a client disconnect. In Elixir a
confirm timeout reads "confirmation failed: timeout"; the other ports use Go's "context deadline
exceeded". The official MCP Java SDK 2.0.0 client sends MCP-Protocol-Version: 2025-11-25 on later
requests even after it negotiated 2025-06-18, so it needs supportedProtocolVersions(List.of("2025-06-18"))
against a default handler.
Rust: a source change if you build Tool with a struct literal. Tool has two new public fields,
output_schema and annotations. A literal that names every field no longer compiles until you add
output_schema: None, annotations: None (or end it with ..Default::default()). The builders
(with_output_schema, with_annotations) are unaffected.
toolnexus has no tenant, role or storage concepts here: those stay in your hooks (ADR 0039).
Serve(addr, {mcp}) is unchanged apart from the optional structured fields. Not done: when you
run several replicas, elicitation answers need sticky routing. The docs-page examples are run in CI
for Go, Python and Java only; the JS, C#, Elixir, Clojure and Rust pages are not run yet.
Let any coding agent call your toolkit, through three vendor-neutral pieces (all eight ports).
toolnexus does not ship a client per coding agent: which binary, flags, login and quirks an agent
needs changes on the vendor's schedule, so those live as recipes in the docs, written on top of
what the library now provides (ADR 0041, SPEC §8C):
- Your in-process model can stream. Give
createInProcessClienta streaming generate —
generateStream(req, emit)(GoGenerateStream, pythongenerate_stream, elixir
:generate_stream, clojure:generate-stream, …) — andstreamyields each text youemitas it
happens. Before, only Go had this and every other port refusedstreamon an in-process client.
A newthoughtstream event carries model reasoning;tool_call/tool_resultevents with
via: "acp"report tools an agent ran itself — passed to you, never executed by your loop. A plain
generatestill refuses to stream, because one chunk pretending to be a stream is the bug this
prevents. Clojure has no stream API; there the events go torun's:on-eventas emitted. - The ACP client passes your configuration through untouched.
loadACPnow sends the
mcpServersyou give it verbatim (it always sent[]before),sessionMetaassession/new
_meta,clientCapsMetaasinitializeclientCapabilities._meta, and passesmodelthrough
(session/set_config_option, thensession/set_model). It streams everyagent_message_chunkthe
moment it arrives in every port (was Go only), fails a request as soon as the agent exits instead of
waiting out the timeout, answers agent requests it does not implement with-32601so the agent
never hangs, declaresterminal:false, and tears down the agent's whole process group onclose. toolkit.asMcpServer()→{url, token, close}serves your toolkit (MCP servers, skills,
your own tools) on a loopback port behind a fresh bearer token, so an agent you launch can call it
and other local processes cannot. You puturland the token into the agent'smcpServersentry.
Pinned without any vendor binary in conformance/acp-client/cases.json (streaming that is really
incremental, verbatim passthrough, agent exit, unknown requests, the server's 401/404/405 rules).
Not in the library, by decision: per-vendor styles or enums, a one-shot CLI transport for agents
without ACP (write a generate that runs your CLI — that is what the seam is for), vendor
permission allow-lists or prompt hints, a stdio-to-HTTP MCP bridge, model lists. The default
permission policy is unchanged (first allow option); a docs recipe shows how to allow only your
toolkit's tools.
Fixed (python only): toolkit.serve(mcp={}) now exposes the toolkit's tools, and GET /mcp answers
405 instead of hanging. An empty MCP serve profile was treated as absent, so /mcp was mounted
but advertised no tools; it now means "present with defaults" (name: "toolnexus", every tool), as
in every other port and SPEC.md §7C. GET /mcp used to hold the connection open forever, which
hung clients that probe it for a server stream (e.g. the Claude ACP adapter, whose session/new
waited on it); the stateless profile offers no stream, so it now returns 405 (Allow: POST),
matching Java, Elixir, C# and Rust. Other ports were not affected by either bug.