Skip to content

The MCP surface ​

A vertical whose routes come from mountOperations serves an MCP endpoint at /api/mcp, and writes nothing to get it — one tool per operation, derived from the same declarations the route table is.

That is the whole prerequisite, and it is worth stating plainly: this rides on the derived route table. A vertical that still hand-writes its routes has no operations catalog to render, so it has no tool list either — it gets the endpoint by adopting mountOperations, not by configuring anything here.

http
POST https://your-vertical.example/api/mcp
Authorization: Bearer <token from your issuer>

The point is not that MCP is fashionable. It is that a vertical already declares everything a tool needs, so the surface is a derivation rather than a thing you maintain. There is no tool registry to keep in step with your routes, and no second file that can disagree with your model.

http is the declaration ​

An operation that declares http becomes a tool. One that does not, does not.

ts
'ticket0/configure-desk': {
  summary: 'Change the desk’s settings',        // → the tool description
  permission: 'desk:configure',                  // → the check that still runs
  input: z.object({ greeting: z.string().optional() }),  // → the tool's inputSchema
  http: { method: 'PATCH', path: '/desk' },      // → this is what makes it a tool
}

That is the same boundary the route table already draws. A composed engine's in-scope functions carry no http — the engine is entity-agnostic and does not own a URL shape — so they are not routes and they are not tools either.

There is deliberately no mcp: true. A flag saying "also expose this" would restate a fact http already carries, and the two would part company the first time somebody renamed a route.

Exposure is not authorization ​

This is the property that lets the surface default to on.

Every tool maps to a route that already exists, behind the same bearer verification and the same assertAllowed(await ctx.check(…)) inside the operation. Anything an agent can do through MCP it could already do with curl and the same token. The endpoint is a new rendering, not a new door.

Two consequences worth knowing, because they are what a hand-rolled MCP server usually gets wrong:

  • Authentication is transport-level. Every call to the endpoint needs a principal — the handshake included — so an anonymous client's first message gets an HTTP 401 carrying the challenge, which is what makes it start its authorization flow. Never reported as a tool failure, and never deferred to the second request.
  • Authorization is in-band. A refused permission comes back as a normal tool result with isError: true, so the agent reads "you may not do that" and picks something else. Returning a transport error there would make one refusal look like a broken session.

Finding where to authenticate ​

A 401 that only says "no" is a dead end: the client has no way to learn which issuer to talk to, and somebody has to paste a token in by hand. So the endpoint can publish RFC 9728 protected-resource metadata and point its challenge at it.

http
401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://desk.example/.well-known/oauth-protected-resource/api/mcp"
json
{
  "resource": "https://desk.example/api/mcp",
  "authorization_servers": ["https://issuer.example"],
  "bearer_methods_supported": ["header"]
}

The default mount discovers the issuer through the vertical's ordinary /api/auth/* route. vertical-auth answers the read-only /api/auth/mcp-authorization-servers request from the same configuration as normal sign-in. The lookup stays inside the app and resolves per request, so one serving script can answer for many scopes and issuers. No per-vertical MCP wiring or manual client ID is needed with the team Auth Server, which supports anonymous dynamic client registration.

Custom auth implementations can explicitly supply mcp.protectedResource.authorizationServers. An auth implementation without the standard discovery route publishes no issuer until that override is configured. Existing deployments need updated vertical-host and vertical-auth packages and a redeploy. Both root and path-inserted protected-resource metadata URLs must reach the worker rather than an asset fallback.

An instance nobody has configured a login for publishes a document with noauthorization_servers rather than an empty list: "this resource has no issuer" and "nobody has set this up yet" are different claims, and a client acts differently on them.

The issuer mints for it ​

Next, a client asks that issuer for a token for this endpoint. It passes the document's resource as an RFC 8707 resource indicator. An authorization server that enforces resource indicators mints only for resources it knows about. It turns anything else away with invalid_target, before any login page renders.

If the vertical signs in with one of the team's own Auth Server apps, the platform registers the endpoint there, so there is nothing to configure. When the dashboard binds an app to a team Auth Server (at install, or when you change its Identity), it registers one resource per hostname the app answers on: https://<hostname>/api/mcp. Deleting the app, or moving it to another issuer, un-registers them, and from the next request on the old issuer refuses to mint for them. Apps installed before this existed are registered the next time anyone on the team opens the dashboard. A per-PR preview of such an app has its own endpoint, https://<app>--<tag>.<base>/api/mcp, registered at the same Auth Server on every push and un-registered when the preview is deleted or expires.

Two cases fall outside this:

  • A vertical that moves its endpoint or pins its identifier. The platform registers only the convention, /api/mcp, the default mountOperations uses. A vertical that mounts the endpoint elsewhere (mcp: { path }) or pins resource advertises a string nothing registers, and its clients still get invalid_target.
  • An external issuer (Auth0, Keycloak, Supabase, …). Its resource registry is yours to configure. Register the resource your document publishes.

The Auth Server says so in its metadata (resource_parameter_supported: true), and any client it knows may request a token for any resource registered there. It does not restrict which client may target which resource: every MCP client registers itself, so there is no fixed list of clients to restrict to. What protects the endpoint is the user's own sign-in and consent, the audience check below, and the permissions every operation checks.

A token has to be for this endpoint ​

The endpoint accepts a bearer token only if its aud names this endpoint's resource, the same string its document publishes. Anything else gets a 401 with error="invalid_token" and the challenge that names the document. That covers a token another vertical's endpoint asked for from the same issuer, and an id_token presented as a bearer, whose audience is the client it was minted for.

It matters because every vertical on one team Auth Server trusts the same issuer, so the signature and the issuer alone cannot tell vertical A's token from vertical B's. The check only ever refuses. The vertical's own resolver still verifies the signature, the issuer and the expiry, and a token has to pass both.

The rest of the API does not apply this check by default. Setting OIDC_AUDIENCE (or audience on a delivered substrat:auth) holds every bearer route to that audience. If you also serve MCP, set it to the endpoint's resource, because a token then has to name that string for both checks.

A call made for a user by another app ​

Another app of the same team can call this endpoint for one of your users: a help desk's assistant looking up that user's orders, say. It does not hold the user's token. The team auth server mints it one by RFC 8693 token exchange, and only when the platform has recorded that your app delegates to it, for a named set of your permission keys. The token's sub is the user, act names the acting app, aud is this endpoint, and scope is the keys it may act with. The auth server mints it for five minutes, with no refresh, and the vertical refuses a delegated token whose lifetime (exp − iat) is longer than that, or whose iat is more than 30 seconds ahead of its clock. maxLifetimeSeconds beside actors can lower the bound, never raise it.

The record of who your app delegates to comes from your app's manifest. Declare each acting app with the keys it may use and the mcp channel:

ts
delegations: [{ actor: 'helpdesk', permissions: ['orders:read'], channels: ['mcp'] }],

The dashboard delivers the declared set to the team auth server as substrat:delegations:<host>, and from this release it manages that entry: a grant delivered any other way is replaced on its next pass. If you delivered one by hand, move it into the host's manifest before you deploy, or the acting app loses it.

Nothing accepts such a token until the vertical opts in, in two places:

ts
const instance = await instanceAuthFor({ directory, scopeId, envSpec, env, delegation: { actors: [actorClientId] } });

async function stub(c: Context) {
  // mcpChannelOf and mcpScopeOptions are from @substrat-run/vertical-host
  const subject = await instance.provider().resolve(c.req.raw.headers, c.req.url, { delegated: mcpChannelOf(c) });
  if (!subject) throw new HTTPException(401, { message: 'unauthorized' });
  // … map subject.sub to a principal, as before
  return host.getScope(principal, tenantId, scopeId, { ...mcpScopeOptions(c, subject) });
}

mcpScopeOptions(c, subject) hands the delegation to both places that hold a call to it: the endpoint's check of each tool, and the kernel, through the getScope options it returns. For a user acting directly it returns {} and sets nothing.

mcpChannelOf(c) is the MCP endpoint serving the request: the resource it answers as, set by the endpoint around its own resolveStub call and null everywhere else — on every REST route, in any other handler, and in a middleware reading after next(). Nothing a request sends can set it. The same stub therefore serves both doors: on a REST route it passes null, and no delegated token is admitted there.

An actor's client id differs from one team auth server to the next, so actors may also be a function of the install's delivered wiring, (wiring) => readonly string[]. One that throws, or returns nothing usable, admits no delegated token.

A delivered audience (on substrat:auth) applies to a delegated token too, and that token's one aud is the endpoint's resource. So unless the audience is exactly that resource, no delegated token is admitted: the opt-in is off, and it fails closed. The verifier logs a warning when the endpoint's channel names a resource other than the delivered audience, once per isolate for each issuer and audience. It names the field, not its value.

What each half does:

  • It is admitted only through the endpoint's channel. The verifier refuses a token carrying act unless actors names the acting app, the caller passed the channel, the token's aud is exactly the channel's resource, and that resource is on the request's own origin. A call without the channel — resolve(headers), a REST route, a stray handler — refuses it. Because the resource is the channel's, an endpoint moved by mountOperations' own basePath or mcp.path option is judged by its own. A prefix Hono adds (app.basePath(), app.route()) does not move the resource: it still names the unprefixed path, as the endpoint's metadata does. Every route mountOperations mounts also refuses a bearer carrying act, with a 401, before resolving anyone.

  • The endpoint is the only route at its path. A route registered before it that Hono's TrieRouter would dispatch a request for that path to, by any method but OPTIONS (/mcp, /:slug, /:slug?, a regex parameter), stops the vertical from mounting; so does a second mountOperations on the same base path. The path judged is the one the endpoint really answers at, an app.basePath() prefix included. A * is judged as TrieRouter reads it, so /api/*, /api/mcp/*, /*/mcp, a GET * fallback, /api/mc* and /ap* all stop it too; register such a route after the mount, or make it middleware that answers only once await next() has found nothing. A route registered after the endpoint never runs there, since the endpoint answers every method but OPTIONS itself, with a 405 and Allow: POST for all but POST. Not judged:

    • app.use, app.all and app.mount, which Hono records alike as middleware, and OPTIONS routes;
    • the routes of an app this one is mounted into later with app.route();
    • the * forms that the default router dispatches there and TrieRouter does not match: a * inside a segment, such as /api/*cp, and a pattern ending in two or more * segments that reaches the path only if its last * matches nothing, such as /api/*/* or /*/*/*. These are not refused.

    None of these routes is handed the channel, so none admits a delegated token.

  • A hand-written MCP surface owns its ceiling. A vertical that serves its own MCP endpoint and passes delegated to the verifier itself takes on what the derived endpoint does: holding every call to subject.delegation.scope. Nothing checks that it does.

  • The endpoint holds every call to the scope. A tool runs only when its leading permission key is in scope. A tool whose operation declares no single leading key (narrows) is outside every scope. A refusal is an in-band tool error, the same as a denied permission.

  • The kernel holds every check behind it. The stub getScope mints with the delegation refuses a key outside scope at every decision the operation makes: a second ctx.check, an entity check, the grant-scoped read behind a filtered list. It refuses it exactly as it refuses a key the user lacks. So a delegated call does at most what the user may and what was delegated.

If the endpoint is handed nothing (mcpScopeOptions was not called), every tool call made with a bearer carrying act is refused. That covers a vertical that opted in to the verifier and forgot the second line. The endpoint cannot see whether the stub carries the delegation, so a stub that hands it over with setMcpDelegation alone gets the tool check and nothing behind it.

What is deliberately not here ​

Client registration. How a client obtains a client_id — dynamic registration (RFC 7591), or a client-ID metadata document — is a question for the authorization server. A resource server validates an access token and has no opinion about who minted the client, so that work belongs at the issuer, not here. (The platform's stock issuer supports both — see the auth server.)

Paged reads ​

A paged read's tool schema names limit, cursor, order and sort explicitly, and states the declared order as its default — the direction a call that names none is served.

Over HTTP those ride in the query string and the host supplies them. An MCP call has no query string, so a paged tool that did not name them would look to an agent like a list that returns everything — it would pull one page and report it as the whole table. That is a wrong answer with no error anywhere, which is the failure this platform works hardest to refuse.

The ceiling behaves as it does on the wire: a limit above LIST_PAGE_MAX is refused, not silently capped, because a capped page is indistinguishable from the end of a walk.

What a tool call cannot do yet ​

Two HTTP affordances have no MCP equivalent, and a tool call behaves exactly like a wire call that omitted them — which is a legitimate call, not a skipped check:

  • Optimistic concurrency. A tool result carries no ETag, so an agent has nothing to echo back and a guarded operation runs with no precondition. Read-modify-write over MCP is therefore last-writer-wins.
  • Idempotent retries. There is no Idempotency-Key, and inventing one per call would defeat the point — a retry would mint a new key and write twice anyway. An agent that retries a failed write may write twice.

Neither can be fixed by forwarding the POST's own headers: a batch carries several calls and one header cannot speak for all of them. Both want a tool-level convention — an ifMatch argument and a returned version — which is a design question, not an omission.

The one knob, and it is optional ​

ts
'ticket0/record-answer': {
  summary: 'Record an assistant answer and its token usage',
  mcp: false,        // never a tool, for anyone
  http: { method: 'POST', path: '/turns' },
}

mcp: false is for operations that face the network because a machine posts to them — a connector's return path, a relay's ingest, a widget service's surface, a schedule's entry point. They are reachable over HTTP for good reason and are pure noise in an agent's tool list.

The other half of the knob is a description:

ts
mcp: { description: 'Search the knowledge base. Use before answering any question.' }

summary is written for an API document — it answers what is this, where tool selection needs when would I reach for this. Say more only where the difference bites. A new vertical writes neither of these.

What this does not solve ​

Tool count. ticket0 routes 59 operations; marking its machine-facing ones leaves 46 tools, which is still a lot to put in front of a model. Two things will help, and it is worth being clear that neither is here yet:

  • A permission filter on tools/list, so a caller is not offered what they cannot call. This is a least-privilege floor rather than a curation mechanism — dramatic for a narrow principal, marginal for an admin. ticket0's desk-admin holds 16 of its 19 permission keys, so filtering would barely shorten its list.
  • Per-consumer app scoping, which is where a coherent toolset actually belongs. A triage agent and a reporting agent want different subsets of the same vertical while holding the same principal — and that is a fact about the consumer, which neither the model file nor the permission spine can express.

Filtering tools/list is invisible to the protocol, so both drop in later without breaking a client.

Turning it off ​

ts
mountOperations(app, myOperations, resolveStub, { mcp: false });

Or configure it:

ts
mountOperations(app, myOperations, resolveStub, {
  mcp: { path: '/mcp', serverInfo: { name: 'ticket0', version: '1.4.0' } },
});

The server name defaults to the module prefix your operations share (ticket0/get-desk, ticket0/list-agents ⇒ ticket0), so it cannot drift from what the tools are called.

What the endpoint speaks ​

Stateless Streamable HTTP: one POST per JSON-RPC message, answered as application/json. GET returns 405 — this server opens no server-to-client stream, because every tool is a request/response call into a scope and there is nothing to push.

Protocol revisions are negotiated, newest first: 2025-06-18, 2025-03-26, 2024-11-05. A client asking for one we do not implement is answered with ours rather than an echo of theirs, and decides for itself whether to continue.

Keeping answers small ​

A tool result is tokens the model pays for, so it is sent once, as compact JSON in the text block. There is no structuredContent copy and no indentation.

A read (GET) whose output names its columns also takes an optional fields argument, a list of column names to keep:

json
{ "name": "ticket0_list-tickets", "arguments": { "limit": 50, "fields": ["id", "subject", "status"] } }

It applies to each entry of a page (the cursor and paging fields are always returned) or to a single entry. The names are an enum in the tool's schema, so the model picks from real columns. An unknown name is refused in-band, before the operation runs, and lists the valid ones. It only removes what the operation would have returned anyway, so it changes no permission. REST and OpenAPI are unchanged. An operation that declares its own fields input keeps it, and gets no projection.

Implemented: initialize, ping, tools/list, tools/call. Resources and prompts are not — tools is the whole capability today.