Module mcp_handler 

MCP — INBOUND, embeddable: a plain streamable-HTTP MCP server with generic per-request hooks (SPEC §7C.1, ADR 0039). Port of golang/mcphandler.go. Behind the serve feature.

Toolkit::serve owns a listener and exposes one static tool list. Toolkit::mcp_handler returns an McpHandler a host mounts on its own router (hyper directly — it implements hyper::service::Service — or any framework through McpHandler::handle), behind its own TLS, CORS and OAuth. Every policy is a hook; toolnexus has no notion of tenant, user, role or storage.

The transport is JSON-RPC over HTTP written by hand (no rmcp server types in the public API): tools resolve per request, and a confirm elicitation rides the SAME POST’s SSE response (protocol 2025-06-18).

MCP 2026-07-28 (SPEC §7C.2, ADR 0040) is opt-in: list "2026-07-28" in McpHandlerConfig::protocol_versions. That stateless wire (server/discover, header validation, MRTR, the skills extension) lives in v2026; bearer-token protection in McpServerAuth. Bring your own authorization server; the auto-approving dev authorization server the suite uses is test tooling (tests/common_dev_auth), not part of the library.

Structs

McpAuthError

An authenticate failure with an explicit HTTP status and challenge (McpServerAuth returns it). status 0 ⇒ 401. A non-empty www_authenticate hook result wins over challenge. reason never reaches the wire.

McpAuthMetadata

The RFC 9728 metadata handler returned by McpServerAuth::metadata. Mount it with hyper (hyper::service::Service) or call McpAuthMetadata::handle.

McpCallEvent

Surfaced once per inbound tools/call.

McpDecision

What before_call returns. The default allows.

McpHandler

The embeddable MCP server returned by Toolkit::mcp_handler. Cheap to clone. Mount it with hyper (hyper::service::Service) or call McpHandler::handle from any framework.

McpHandlerConfig

Configures Toolkit::mcp_handler. Every field is optional.

McpPrincipal

The verified caller. McpServerAuth::authenticate makes it the identity: rc.identity_as::<McpPrincipal>().

McpPrompt

One prompts/list entry.

McpPromptArgument

One prompt argument.

McpPromptMessage

One text message of a prompts/get result. role: user | assistant.

McpPromptResult

The prompts/get result.

McpRequestContext

The request being served: HTTP parts, the authenticated identity, the session id and the JSON-RPC params._meta. Every hook receives it; a tool reads it with mcp_request_context.

McpResource

One resources/list entry.

McpResourceContent

One resources/read entry: set text, or blob (base64).

McpServerAuth

Protects an McpHandler with bearer tokens.

McpServerInfo

Advertised at initialize. Empty title / instructions are omitted.

McpSkill

One skill published through the skills extension (SEP-2640). files are paths relative to the skill directory (/-separated) and MUST include SKILL.md. frontmatter None ⇒ {name}. load_mcp_skills builds these.

McpSkillFile

One text file of a skill.

Enums

McpDecisionKind

The outcome of a before_call gate.

Constants

MCP_HANDLER_IMPLEMENTED_VERSIONS

The MCP protocol versions whose wire McpHandler implements (ADR 0039). Configured versions outside this list are dropped. 2026-07-28 is opt-in only (never a default) and is served by the stateless wire of SPEC §7C.2; initialize never negotiates it.

MCP_PROTOCOL_2026

The MCP 2026-07-28 protocol version (SPEC §2.1).

MCP_SKILLS_EXTENSION

The SEP-2640 skills extension id advertised by server/discover.

Traits

McpSessionIds

Issues and checks Mcp-Session-Id values. The default is an in-memory set; a host plugs its own (signed ids, a DB) so any replica validates any session.

Functions

load_mcp_skills

Read every skill under dir (any depth, **/SKILL.md, symlinks not followed) for McpHandlerConfig::list_skills. The frontmatter is {name, description} parsed as in §3; a skill without a name is skipped. Files are every regular UTF-8 file under the skill directory (binary files are skipped — the wire carries text), paths /-separated, sorted by code point; skills sorted by name.

mcp_request_context

The McpRequestContext of the served call a tool is running in.

Type Aliases

AuthenticateFn

authenticate: an error ⇒ HTTP 401 (see McpAuthFailure).

BeforeCallFn

before_call(ctx, tool, args); an error is a deny carrying its message.

BoxFuture

A boxed, sendable future returned by the async hooks.

GetPromptFn

ListPromptsFn

ListResourcesFn

ListSkillsFn

list_skills: the skills published through the SEP-2640 skills extension.

ListToolsFn

McpAuthFailure

An authenticate failure. Any error ⇒ a plain HTTP 401; an McpAuthError (downcast) ⇒ its status, its challenge as WWW-Authenticate and the body {"error":"unauthorized"} (both wires). "msg".into() builds a plain one.

McpBody

The response body type.

McpIdentity

What authenticate produces; reachable everywhere via McpRequestContext::identity.

OnMcpCallFn

ReadResourceFn

ServerInfoFn

VerifyTokenFn

verify(ctx, token, audience): replaces the default RS256/JWKS verifier (opaque tokens, introspection). Any error ⇒ 401 invalid_token.

WwwAuthenticateFn

www_authenticate(ctx, err): the WWW-Authenticate value (“” ⇒ omitted).