mcp

Documentation

Overview

Package mcp serves aprot handlers as MCP (Model Context Protocol) tools over the Streamable HTTP transport, so an AI assistant calls the same handlers a browser does — through the same aprot.Server pipeline, the same middleware, and the same auth (issue #316).

Only methods opted in via aprot.Registry.EnableMCP are exposed. Dispatch goes through aprot.Server.Invoke, so refresh triggers fired by a tool call refresh subscribed WebSocket/SSE clients like any other mutation.

registry.Register(&TodoHandlers{})
registry.EnableMCP(&TodoHandlers{}, aprot.MCPOptions{Tools: map[string]aprot.MCPTool{
    "ListTodos":  {ReadOnly: true, Idempotent: true},
    "CreateTodo": {Description: "Add a todo item to the list."},
}})
server := aprot.NewServer(registry)
http.Handle("/mcp", mcp.NewAdapter(server, mcp.Options{ServerName: "todos"}))

Tool calls carry no connection: aprot.Connection returns nil in middleware and handlers, exactly as on REST. Connection presence means "there is a socket", never "the caller authenticated" — gate protected tools on your own auth (e.g. a wrapping http.Handler that validates the Authorization header and attaches the resolved identity with aprot.WithPrincipal, read back via aprot.PrincipalFrom in middleware and handlers). A wrapper may also install a connection via aprot.WithConnection (see aprot.Server.NewDetachedConn) for middleware that reads per-connection state; a aprot.PrincipalProvider registered on that connection is resolved for the tool call, so one auth setup can serve sockets and MCP alike. An explicit aprot.WithPrincipal wins over the provider — the wrapper that authenticated the request is the authority on that execution — and a provider error rejects the tool call instead of running it anonymously.

The adapter is stateless: it implements the JSON-RPC subset MCP requires for tool serving (initialize, ping, tools/list, tools/call) over HTTP POST, without sessions or server-initiated streams.

Experimental

This package is experimental: its API may change without notice, and without a breaking-change entry, until the first real consumer arrives. There are none yet, and the MCP specification itself churns — the adapter pins revision 2025-06-18 and accepts older revisions during negotiation. The handlers it serves are not experimental; only this adapter's own surface is.

It is kept, rather than deleted for lack of users, because it is the second consumer of aprot's request-scoped dispatch seam: with REST alone that seam drifted REST-shaped for several releases (#316, #330). The keep-condition is that CI keeps exercising it — the invariant matrix (#339) runs every cross-path invariant against this adapter. If that coverage ever lapses, deleting the package is the right call (#340).

Index

• type Adapter
  • func NewAdapter(server *aprot.Server, opts Options) *Adapter
  • func (a *Adapter) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Options

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter serves MCP over HTTP. It implements http.Handler and can be mounted on any stdlib-compatible router.

func NewAdapter

func NewAdapter(server *aprot.Server, opts Options) *Adapter

NewAdapter builds an MCP adapter over the server's registry. Tools are resolved once, at construction — register handlers and call EnableMCP before creating the adapter.

A RegisterMCP group with no tools enabled via EnableMCP panics here: MCP is that group's only surface, so a tool-less group is reachable nowhere and the registration is a mistake.

func (*Adapter) ServeHTTP

func (a *Adapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the MCP Streamable HTTP transport for a stateless tool server: JSON-RPC messages arrive as HTTP POST bodies and are answered with application/json. GET (server-initiated streams) is not supported.

type Options

type Options struct {
	ServerName    string // serverInfo.name; default "aprot"
	ServerTitle   string // serverInfo.title (display name), optional
	ServerVersion string // serverInfo.version; default "0.0.0"
	Instructions  string // optional hints for the model, sent on initialize
}

Options configures the MCP adapter's server identity.