[antoinetoussaint-byte]

Closes #46.

A solution exposes its experience to an agent client — Claude Code, Claude Desktop, any MCP client — the way it exposes it to a browser: as the signed-in person, through the host's gateway, with the same authority. The solution owns its tool surface; this runtime owns serving it, exactly as it owns serving HTTP. Nothing MCP-specific goes in the gateway.

The three lines a solution writes

solution.New(solution.Manifest{ID: "wiki", Title: "Wiki"}).
    ServeMCP("wiki", "v1.0.0", func(srv *mcp.Server) {
        mcp.AddTool(srv, &mcp.Tool{Name: "ask_wiki", Description: "ask the wiki a question"}, askWiki)
    }).
    Serve()

A tool handler gets the viewer from its own context:

gw, err := solution.ViewerFromContext(ctx)   // the same caller-bound Gateway a Handler is given
robin, err := gw.ForModule(ctx, "robin", solution.Scope{ResourceKind: "conversations", Actions: []string{"create"}})

register receives the official SDK's own *mcp.Server (github.com/modelcontextprotocol/go-sdk v1.8.0, the latest stable 1.x), so tools are declared exactly as that SDK documents them and this runtime adds nothing to them.

What is served

• /mcp — stateless Streamable HTTP (mcp.NewStreamableHTTPHandler with Stateless: true). /solutions/<id>/mcp through the gateway, a route it already fronts. Stateless because the gateway is a reverse proxy with no sticky routing: a session held in one replica's memory is unreachable from the next request, so an MCP session would break under any rollout. POST only; GET/DELETE are 405 and no Mcp-Session-Id is ever issued.
• /.well-known/oauth-protected-resource — the RFC 9728 document, served unauthenticated with Access-Control-Allow-Origin: * (discovery is public, §3.1), built from the SDK's own oauthex.ProtectedResourceMetadata so the field spellings are not typed here.
• No CORS on /mcp. The runtime's policy for a solution's own API admits any origin with an authorization header; that is the right answer there and the wrong one for the single route that acts with the viewer's full authority. The SDK's DNS-rebinding protection is left on for the same reason.

Authentication: the gateway's, enforced here

No token verification, no JWKS, no audience logic. The gateway runs ext_authz and stamps the identity, so a check here would be a second, divergent copy of the host's admission rules with its own bugs. What is enforced is that the gateway did it:

The request	Answer
no authorization	401 + WWW-Authenticate: Bearer resource_metadata="…"
bearer, but none of x-user-id/x-org-id/x-session-id stamped	401 + the same challenge: nothing but the gateway may reach this endpoint
x-session-id stamped empty	403 naming the x-credential-kind the gateway stamped: a credential that authenticates without a session cannot mint a Work Context, which accounts roots in one

Which caller sees those 401s — corrected since the first version of this PR, and the main thing a reader should take from it. Not an MCP client coming through the gateway: the gateway strips identity headers and runs ext_authz before proxying, so an unauthenticated request is denied there with its own 401 authentication required and never reaches the solution. The runtime's 401 is what a caller reaching the solution directly sees (a local run, a port-forward) and the shape the gateway's own challenge has to match; emitting it there is the host's half, codefly-dev/module-saas-starter#1003. The metadata document is served here either way, because it is what that challenge has to name.

The no-session refusal is at the boundary rather than once per tool call, where it would read as a broken tool. Each tool call runs as the viewer through a receiving middleware that binds the stamped identity to the request's context — never from the tool's arguments, which a model writes — and logs the tool name, which the accounts mint audit does not carry; no arguments and no credentials.

Classification

Every change is a fix at the place that owns the behaviour. Serving a solution's surfaces, and reading the identity the gateway stamps, is what this repository owns; there is no stopgap in this PR and nothing works around a defect elsewhere.

One thing the runtime genuinely cannot resolve, handled explicitly rather than guessed: the resource identifier a client binds its token to must be the public MCP URL, whose origin is the host's and whose path is the host's route layout — which this runtime deliberately does not encode (the same reason manifestUrl is root-relative). So MCP_PUBLIC_URL is it when set, paired with the metadata document's URL by the same suffix swap the registration token URLs use and refused at boot when unpairable. In a deployed runtime context both it and HOST_ISSUER_URL are required: unset, the identifier is missing the prefix the gateway strips and the issuer is the in-cluster address this composition dials the host at, and both used to be served with a 200 from a solution that looked healthy. That is the same silent damage deployedRuntimeContext already refuses for a loopback SELF_UPSTREAM or PUBLIC_URL, so it is refused the same way, naming the variable that fixes each. A local run resolves a host it can actually reach and is untouched; there the identifier is still reconstructed from x-forwarded-proto/-host/-prefix, with a boot log line saying so.

The fix that would retire MCP_PUBLIC_URL is the gateway telling a solution its public route — in the registration response it already answers — which belongs to the gateway, not here. No issue filed for it: that needs the owner's go-ahead.

authorization_servers is the host issuer, never request-derived, so a crafted Host header cannot point a client at another authorization server. A forwarded proto is accepted only as http or https, and a forwarded host or prefix that is not one is dropped rather than sanitized.

Configuration

Resolved in loadConfig and checked in validate() — the one place each, as AGENTS.md requires; validateMCP is called from validate() and runs only when ServeMCP was declared. environment_boundary_test.go still passes with no new exception.

Tests

mcp_test.go, hermetic like the rest of the suite: an in-process gateway double (stampedTransport) stamps the identity headers as the gateway does, and the existing workContextGateway double answers the accounts mint and the module read.

• a real mcp.NewClient over Streamable HTTP does initialize → tools/list → tools/call, and the tool's ForModule read succeeds only because the viewer's Work Context was minted and presented — the mint's org, session and bearer are asserted to be the viewer's
• the 401 shape and its exact challenge, for no bearer and for a bearer with nothing stamped; the 403 for a credential with no session, asserted to name the kind the gateway stamped (and, for another kind, asserted not to name api_key) and to carry no challenge
• the metadata document: resource from the forwarded headers, the resolved issuer, bearer_methods_supported, CORS; the issuer unchanged under a crafted Host; the configured public URL winning over any header; an unusable forwarded prefix, host or scheme dropped rather than sanitized
• stateless: no Mcp-Session-Id issued, GET is 405; no CORS on /mcp; a tool call logged by name with neither its arguments nor the viewer's credential
• the boot refusals: a mis-declared surface, a redeclared ServeMCP, a handler registered on a path ServeMCP serves, an unresolved issuer only when MCP is served, an unpairable MCP_PUBLIC_URL, and the deployed-context refusal of an unset MCP_PUBLIC_URL or HOST_ISSUER_URL — that last one confirmed load-bearing by mutation (delete the refusal, the test fails)

Server.MCPHandler(MCPEnvironment{...}) is the test seam, mirroring PassthroughHandler: the surface exactly as Serve serves it, against an environment the caller supplies, nothing registered anywhere. The wiki (obin-ai/core-solutions#343) tests its tools through it.

What the independent review established by execution

An executed review of d68bc8b confirmed, beyond the findings below: go-sdk v1.8.0 with Stateless: true behaves as claimed (no Mcp-Session-Id issued, a forged one ignored, GET/DELETE 405); 40 concurrent tool calls from two viewers produced 40 mints with no cross-viewer mixing; and the SDK's localhost DNS-rebinding protection 403s any local hostname other than localhost:<port>.

What it found, and what was done

	Finding	Done
F1	the runtime's 401 challenge is unreachable through the gateway, and the README presented it as the client-facing handshake	fixed in the README refusal table, the discovery paragraph, the code comments that asserted it, and above
F2	a deployed solution served a wrong resource identifier and an in-cluster issuer on a 200, with a boot log line as the only signal	boot refused by name for both, pinned by a test and confirmed by mutation
F3	x-forwarded-proto used unvalidated (javascript://host/mcp)	http/https only, else the request's own scheme
F4	the no-session 403 asserted api_key whatever was stamped	names the stamped kind; the api_key detail only when that is the kind
F6	no per-tool-call record	one log line per tool call: solution id and tool name, nothing else
F7	Handle("/mcp") + ServeMCP panicked inside ServeMux; a second ServeMCP silently replaced the first	both refused at boot by name, before the listener opens

Docs in this PR

• README.md — new ### Exposing an MCP server: the three lines, how a tool gets the viewer, the table of what is served, every refusal with its reason and which caller sees it, the resource identifier and the issuer (including the deployed-context requirement), connecting from Claude Code today, and MCPHandler. Two new rows in the env-override table (HOST_ISSUER_URL, MCP_PUBLIC_URL), and MCP added to what the runtime owns.
• AGENTS.md — the trust boundary an agent would otherwise undo by being helpful (verify no token; refuse at the boundary; no identity from tool arguments), MCP in the ownership paragraph, and mcp.go in "where the depth is".
• the package doc comment, which also now states what this package actually depends on.

What I did not verify

• No real gateway, no real accounts, no composed stack. Every counterpart is an httptest double on 127.0.0.1. A green run proves the wire shapes and refusals this package produces — not that the gateway stamps x-user-id/x-credential-kind as ServeMCP: a solution exposes an MCP server as the signed-in person — Streamable HTTP, RFC 9728 metadata, tools that run under the viewer's Work Context #46 describes (if it does not, every MCP request is refused loudly, by a message naming the headers), not that accounts mints a Work Context for a tool call, and not that a real MCP client's OAuth flow completes.
• Discovery through the gateway is the host's half and untested here: the gateway emitting the 401 challenge, admitting an unauthenticated GET on /solutions/<id>/.well-known/oauth-protected-resource, and whether a client that only guesses RFC 9728's path-derived location (/.well-known/oauth-protected-resource/solutions/<id>/mcp, at the host's root) can discover this resource. All three are in the README and tracked by module-saas-starter#1003.
• Refs in tool results are the solution's to return — the runtime encodes whatever the tool's output struct carries.
• No tag, no release: the consumer pins a default-branch commit after this merges.

Gates run locally on the head of this branch: go build ./..., go vet ./..., go test -race ./... -count=1 -timeout=5m, go mod tidy -diff, gofmt -l . — all clean, plus CI.

Dependency note: adds github.com/modelcontextprotocol/go-sdk v1.8.0 as a direct require (with github.com/google/jsonschema-go and segmentio/encoding indirect, its own dependencies). It is a public API dependency — a solution imports .../go-sdk/mcp to declare tools — so a consumer pinning this runtime gets that version through MVS.

🤖 Generated with Claude Code