documentation /concept

MCP Server

Concept

A group of tools a Model Context Protocol server offers. External MCP clients (Claude, Cursor, …) authenticate with an access token from the app’s identity provider and call the configured tools directly. Not a page: it renders nothing and is not referenced from any tab.

Placement

Headless placement: a module with this concept renders nothing, so it is declared under items: and served by a handler that names it with module: rather than being placed in a tab segment or a handler’s chat: slot. That handler’s authentication: decides whose access tokens the endpoint honors and, through its rule, which of those callers it admits: roles: for the holders of any of the roles the authenticator declares, from its users-table columns, its membership table or its directory, or of the predefined role loggedin, which every signed-in user holds and no authenticator may declare; no key admits anyone who signs in, the same as roles: [loggedin]. An app may declare at most one such handler.

Outline Display: Expose {{tools}} to external MCP clients

Details

A module with this concept is declared under items: and served by a handler of type: mcp, which names it with module:. Referencing it from a tab segment or a chat: slot is a type error, and so is a page handler naming it.

Tool names are what a client calls, and they have to stay distinct within the module: a name contributed twice – easy to do when ingredientRef: splices shared tool lists into tools: – would appear twice in tools/list while every call to it reached whichever comes first, so the spec checker rejects it. Each tool’s name is its required toolName setting (1-64 characters of letters, digits, underscore, or hyphen), so two lookups on the same table need names of their own. Beside the name, tools/list carries each tool’s title, the human-readable name a client shows: the tool’s toolTitle setting, or derived from the wire name when unset (search_open_orders is “Search Open Orders”). Titles must be distinct within the module too, derived ones included, since a person tells tools apart by them. The name the endpoint reports to clients is the handler’s title:, not a module setting.

That handler’s authentication: decides whose access tokens the endpoint honors, exactly as it decides who may load a page, and its optional query: decides which of those callers are admitted at all, with the same [Username] semantics a page query has. It must name an OIDC-backed authenticator whose API is configured with issuer, introspection_url, and audience; password, SecretCode, and Dummy authenticators have no external issuer and are rejected.

Set audience to this app’s own MCP endpoint URL – https://<the app's host and path>/mcp. The endpoint derives the absolute URLs in its discovery documents from that setting, so an opaque identifier there compiles but leaves the endpoint advertising a metadata URL that resolves nowhere.

The handler serves two HTTP endpoints: /mcp, which speaks JSON-RPC over POST, and /.well-known/oauth-protected-resource, which tells callers which identity provider issues tokens for this app. A 401 from /mcp carries the absolute URL of the second in its WWW-Authenticate challenge, which is how MCP requires clients to discover it. A 401 means the identity provider judged the token and refused it, or the handler’s query: did not admit the resolved caller; where the provider could not be reached at all, the endpoint answers 503 with a Retry-After instead, so a client keeps a token that was never in question. The app is an OAuth resource server only: it issues no tokens and runs no consent screen. Every request must carry Authorization: Bearer <token>, and a token minted for a different audience is rejected.

An app may declare several mcp handlers, each serving its own module and so listing and calling only that module’s tools. One handler alone is served at /mcp as above, whatever its name. With several, each is served at /mcp/<handler name> and its metadata document at /.well-known/oauth-protected-resource/mcp/<handler name>; nothing is served at /mcp itself, because a page URL may not be a prefix of another, so adding a second handler moves the first. Their names must then differ and hold only letters, digits and underscores, and in any app with an mcp handler no other handler may be named mcp. Each endpoint advertises its own authenticator’s audience: handlers sharing one authenticator share it too, which clients accept since https://<host and path>/mcp is a path prefix of every endpoint URL, and handlers that must refuse each other’s tokens name authenticators whose APIs set distinct audiences (.../mcp/<handler name>).

The tools: list draws on the same ingredient family Chat uses: table lookups, inserts, updates and deletes, and Tool pipelines built from row-action steps. A tool that must do several things – look something up and then act on it, call an API and record the result, check a rule before writing – is one Tool: its parameters declare what the caller supplies, its rowAction wires the steps, and its outputMapping picks what returns to the model. That ingredient’s steps decide its approval gate where the spec leaves requiresApproval unset, but an MCP surface applies no such gate, so put the policy in the pipeline instead: a Require placed before the step it protects refuses the call with its message, and If condition branches when both outcomes are normal.

Tools run unattended – there is no user in the loop to approve a call – so requiresApproval gates nothing here; it warns rather than failing, so one tool list can be shared with a Chat concept, which does gate it. The handler’s roles: decides who may call at all; scope what an admitted caller can reach with rowFilters (which see the token’s subject as currentUser) and with column selection, exactly as you would for Chat. A caller resolves to the same app user their browser session would, so per-user row filters and audit attribution behave identically on both paths.

Between the handler’s admission and those row filters sits an entry’s roles:, beside its settings, naming roles the handler’s authenticator declares: a caller must hold any one of them to see and call that tool. A caller holding none finds the tool absent from tools/list, and calling it anyway answers exactly as for a name that never existed. Absent means every admitted caller; [] means nobody.

An app’s tools change more often than its clients fetch tools/list, so a call to a name the caller cannot reach is expected rather than exceptional, and is answered as a tool result with isError: true, not as a protocol error: the text is a JSON document saying the client’s tool list is out of date and the server is working, with the names the caller can call now under availableTools. Its kind is unknown_tool for a name that was renamed, removed, or hidden by roles:, which are never told apart. An entry switched off with disabled: true answers disabled_tool instead, saying so, but only to a caller its roles: would have let call it; anyone else gets the unknown_tool answer.

A tool that is still served may have changed what it takes since the client listed it. When a call’s arguments do not fit the tool’s schema, the tool’s refusal (kind of bad_arguments) carries its current schema under inputSchema, so the model can correct the call without a fresh tools/list. The endpoint itself refuses an argument the schema does not declare the same way, before the tool runs, rather than let the tool ignore it: a filter the tool has since renamed would otherwise answer as if no filter were asked. Only this endpoint holds a call to the schema that way, since only its clients can hold a stale copy: a chat sends the model the current schema with every turn. A refusal of what an argument holds, such as a SQL statement that does not parse, carries no schema.

Settings

Optional