Repository navigation
Error Codes mcp
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
Part of Error codes: every code @ultimat3/mcp registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix |
|---|---|---|---|
X_MCP_APP_UNMOUNTED |
the app's MCP endpoint is exposed in config and nothing can be mounted |
ai.mcp.expose is true — the default — and either no apps/<app>/mcp.ts exports mcp, or the one that does was built without resolveToken, so defineAppMcp built no route. Logged once per boot by the web role (x dev and runRole alike), never thrown: an app with no agent surface yet is a working app |
export const mcp = defineAppMcp({ include: 'exposed', resolveToken }) in apps/web/mcp.ts, resolveToken added to the one that exists, or ai: { mcp: { expose: false } }
|
X_MCP_ARGS_INVALID |
tool arguments failed the input schema | not raised on the wire since 22.10: invalid tool arguments answer an isError result carrying X_INPUT_INVALID; McpArgsInvalidError stays exported |
{ jsonrpc: '2.0', id, method: 'tools/list' } — re-read the tool's inputSchema, then resend |
X_MCP_BODY_TOO_LARGE |
one MCP message is larger than the transport holds | a POST /mcp body over bodyLimitBytes (default 1 MiB), answered 413 on a JSON-RPC -32600 with id: null and data: { code, cause, fix, limit } — or one stdio line over lineLimitBytes, answered the same way on that wire. Its own code rather than X_BODY_INVALID because the knob differs: this route never passes through the HTTP pipeline's bodyLimitBytes. It was a bare -32600 reading request body is at least N bytes, limit is M until 2026-09-07 — two numbers and no next step, while the 401, 403 and 429 beside it all carried { code, cause, fix }
|
defineAppMcp({ bodyLimitBytes }) / mcpHttpRoute({ bodyLimitBytes }) where the route is built, serveStdio({ lineLimitBytes }) over stdio — the fix: line doubles the cap — or send less in one message: page a large read, split a long prompt across calls |
X_MCP_CATALOG_TOOL_DUPLICATE |
a per-caller MCP catalog names one tool twice | defineAppMcp({ catalog }) resolved a tool whose name a static tool, a meta tool, list_tenants or another runtime tool already answers to | defineAppMcp({ catalog: (caller) => ({ tools: [runtimeTool({ name: '<unique-name>', … })] }) }) — rename the runtime tool; x mcp tools --json lists the static names |
X_MCP_CATALOG_UNRESOLVED |
a per-caller MCP catalog could not be resolved | defineAppMcp({ catalog }) threw, or answered something other than { tools: runtimeTool()[] } this server can serve |
defineAppMcp({ catalog: (caller) => ({ tools: [runtimeTool({ name, description, inputSchema, permission, run })] }) }) — fix what the cause names in the catalog function: its throw, an entry not built by runtimeTool(), or a scope the boot scopes: map does not declare |
X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH |
an MCP confirmation approval did not carry the arguments the agent sent | approve was sent without arguments, with different arguments than view returned, or on a row keyed before a signing-secret rotation |
confirmations({ id, decision: 'view' }) — then approve with exactly the arguments it returns |
X_MCP_CONFIRMATION_CONTESTED |
identical concurrent MCP calls kept racing one confirmation | one agent sent the same call concurrently and the open row kept being consumed |
tools/call — retry once, after the concurrent identical calls finish: send one at a time |
X_MCP_CONFIRMATION_DECIDED |
an MCP confirmation was already decided | approve or reject was sent for a row already approved or rejected |
tools/call — the agent repeats the call, which opens a new confirmation to decide |
X_MCP_CONFIRMATION_EVIDENCE_INVALID |
an MCP confirmation approval carries no valid signed evidence | mcpConfirmations({ evidence }) is declared and an approval's signature is missing, does not verify against the approver's registered keys, signs another confirmation's payload, or the stored approvals no longer meet the quorum | confirmations({ id, decision: 'view' }) — sign the signingPayload it returns with a key registered to you, then approve with that signature and exactly the arguments it returns |
X_MCP_CONFIRMATION_EXPIRED |
an MCP confirmation expired before it was used or decided | the confirmation's ttlMs elapsed |
mcpConfirmations({ tools, ttlMs }) — raise ttlMs, or call the tool again with the same arguments to open a new confirmation |
X_MCP_CONFIRMATION_PENDING |
a gated MCP tool call waits for a person to approve it | the tool is in mcpConfirmations({ tools }) and no approved, unexpired confirmation covers this actor, tool and input |
confirmations({ id, decision: 'view' }) — as a person, with the id this answer carries; then confirmations({ id, decision: 'approve', arguments }) with exactly the arguments view returned, and the agent repeats the same tools/call before it expires |
X_MCP_CONFIRMATION_QUORUM_INVALID |
mcpConfirmations approvers resolved a quorum no approver set can meet | approvers({ args }) answered a quorum that is not a whole number of at least 1, an empty or malformed from list, or more named approvers than exist once the asking actor is excluded | mcpConfirmations({ approvers: ({ args }) => ({ quorum: 1, from: ['role:<name>'] }) }) — a whole quorum of at least 1, over selectors 'role:<name>' or 'actor:<id>' that can reach it without the asking actor |
X_MCP_CONFIRMATION_QUORUM_PENDING |
an MCP confirmation needs more approvers before the call runs | mcpConfirmations({ approvers }) resolved a quorum above one for this call and fewer distinct approvers have approved; the asking actor never counts, and one approver counts once | confirmations({ id, decision: 'view' }) — as another approver the quorum names, then approve with exactly the arguments it returns |
X_MCP_CONFIRMATION_REJECTED |
a person rejected this MCP tool call | the confirmation was decided 'reject' |
{ method: 'tools/call', params: { name, arguments } } — with arguments changed after asking the person who rejected it; the same arguments are rejected again |
X_MCP_CONFIRMATION_TOOL_UNKNOWN |
mcpConfirmations gates a tool this server does not project | a name in tools: matches no projected tool, or tools is empty |
mcpConfirmations({ tools: ['<a projected tool name>'] }) — x mcp tools --json lists them |
X_MCP_CONFIRMATION_UNKNOWN |
no MCP confirmation has that id | the id is mistyped, from another deployment, or purged after expiry |
confirmations({ id, decision }) — with the id from the X_MCP_CONFIRMATION_PENDING answer |
X_MCP_EFFECT_CONFLICT |
a read-only MCP tool declares an effect | a query (or a tool declared destructive: false) carries mcp.effect, and on a meta-split surface a read is always read_resource's | drop effect from the query's mcp block, or make it an action if it writes |
X_MCP_EFFECT_UNDECLARED |
an MCP tool on a meta-split surface declares no effect | defineAppMcp({ surface: 'meta-split' }) groups an action whose mcp block names no effect, so no dispatcher can be picked for it | add mcp: { expose: true, effect: 'write' } (or 'delete' for an archive, a send or a spend) to the action, or tools: { name: { effect } } for a hand-written tool |
X_MCP_GROUP_CONFLICT |
two resource groups claim one MCP tool | the same tool name listed under two groups |
groups: { <group>: { description, tools: ['<tool>'] } } — the tool in exactly one entry of groups (defineAppMcp) |
X_MCP_GROUP_UNKNOWN |
defineAppMcp groups a tool this server does not project | a typo, a renamed primitive, or a tool never listed |
groups: { <group>: { description, tools: ['<a projected name>'] } } — the tool name corrected (defineAppMcp) to one tools/list shows, or the entry removed |
X_MCP_HEADER_MISMATCH |
an MCP request header is absent or disagrees with the body | a modern POST /mcp without MCP-Protocol-Version and Mcp-Method (and Mcp-Name for tools/call, resources/read, prompts/get), or one whose value differs from the body after decoding a =?base64?…?= sentinel. Answered JSON-RPC -32020 (HeaderMismatch), HTTP 400: a load balancer may route on a header while the server runs the body | send MCP-Protocol-Version equal to params._meta["io.modelcontextprotocol/protocolVersion"], Mcp-Method equal to method and Mcp-Name equal to params.name or params.uri (base64 sentinel for a non-ASCII value), then resend the request |
X_MCP_HOST_REFUSED |
an MCP request named a Host that is not this machine | x mcp serve answered a request whose Host is not localhost, a *.localhost name or a loopback address — the shape of a DNS-rebinding page, whose Host and Origin agree. Answered 421 before the bearer token is read | curl -X POST http://localhost:9229/mcp -H 'authorization: Bearer <token>' |
X_MCP_IDEMPOTENCY_KEY_SHADOWED |
an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key | the tool argument would be both the action's input and the retry key |
x actions show <action> --json — rename the action's idempotencyKey input field; MCP clients pass the Idempotency-Key as the reserved idempotencyKey argument |
X_MCP_INCLUDE_EARLY |
include: 'exposed' projected before the scan registered every exposed primitive | an mcp endpoint built with include: 'exposed' at the top level of a module the boot scan evaluates before the app's actions and queries — an apps//{app,site,api,shared}/ file — so its catalog froze without them | move the defineAppMcp / adminMcp call into apps/<app>/mcp.ts at module scope — the boot scan evaluates that file after every apps/*/{site,app,api,shared} module |
X_MCP_JOB_TOOL_INVALID |
jobTool() was declared with something it cannot run | the job is not job()'s handle, the jobs driver has no introspect, or inlineMs is outside 0..25000 | jobTool({ job: myJob, policy, result, inlineMs: 5_000 }) — on the postgres or memory jobs driver |
X_MCP_LIST_PARAMS_INVALID |
a tool's listParams names a key its own input does not accept | listParams whitelists a filter, sort, fields, cursor or limit key the query would never read | add the key to the query's input schema, or drop it from mcp.listParams |
X_MCP_NOT_BRANCH_DB |
db.migrate was aimed at a database that is not a branch |
a production-tagged target, or any shared/long-lived database |
x db branch create <name> # then retry db.migrate — the guidance rides behind # so the whole line pastes into a shell. A production target gets the other half of the refusal instead: ROLE=migrate bun apps/web/server.ts # in your deploy hook
|
X_MCP_OAUTH_INVALID |
the MCP oauth block cannot be published as protected-resource metadata | no authorizationServers, an issuer that is not an absolute https URL (http only for localhost), or a resource / resourceDocumentation that is relative or carries a fragment. Refused at boot, before a client reads the metadata |
defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL, and resource, when set, an absolute URL with no fragment |
X_MCP_ORIGIN_REFUSED |
an MCP request came from a browser page on another origin | a POST /mcp whose Origin header is present and that core's proveSameOrigin cannot show is this app: not the route's public origin and not listed in http.cors.origins — refused 403 before the bearer token is read. It does not catch a DNS-rebound name, whose Host and Origin agree: x mcp serve refuses that Host first (X_MCP_HOST_REFUSED) |
curl -X POST http://localhost:3000/mcp -H 'authorization: Bearer <token>' — no Origin header; a page on a sibling origin is listed in http.cors.origins |
X_MCP_PATH_DUPLICATE |
two MCP endpoints claim one path |
apps/<app>/mcp.ts exports mcp as an array and two endpoints resolve to one POST path — a second defineAppMcp with no path defaults to /mcp — or to one RFC 9728 metadata path. Thrown at boot by the web role (x dev and runRole alike): one URL cannot answer two populations with two catalogs |
defineAppMcp({ path: '/mcp/admin', ... }) — each one after the first at its own path; every endpoint mounts at its own defineAppMcp path (default /mcp) |
X_MCP_PROTOCOL |
the MCP handshake or auth is wrong | missing bearer token, or a user-shaped actor |
authorization: 'Bearer <token>' on the request; resolve MCP callers as agents: { actor: agentActor({ id }), scopes } from resolveToken. A batch or a bad envelope: { jsonrpc: '2.0', id, method, params }, one request per message |
X_MCP_PROTOCOL_UNSUPPORTED |
the request names an MCP protocol version this server does not serve | a request whose params._meta["io.modelcontextprotocol/protocolVersion"] (or MCP-Protocol-Version header) names a revision outside MCP_MODERN_VERSIONS and MCP_LEGACY_VERSIONS. Answered JSON-RPC -32022 (UnsupportedProtocolVersionError) with data: { supported, requested }, HTTP 400 | resend the request with params._meta["io.modelcontextprotocol/protocolVersion"] set to a version from error.data.supported — MCP_MODERN_VERSIONS from @ultimat3/mcp lists the modern ones |
X_MCP_QUERY_REJECTED |
db.query was not given one read-only statement |
empty input, a batch, a non-read leading keyword, a mutating keyword anywhere at statement level (including a data-modifying CTE), a locking clause (FOR UPDATE/FOR SHARE), EXPLAIN ANALYZE, or a call from a banned function family matched by prefix (pg_read_*, pg_ls_*, lo_*, dblink, pg_advisory_*, pg_sleep*, set_config, …) |
SELECT * FROM <table> LIMIT 10 — exactly one read-only SELECT/WITH/EXPLAIN/SHOW/TABLE/VALUES statement. db.query has no write path at all: change data by calling an action exposed with mcp: { expose: true }, and change schema with db.migrate after x db branch create <name>
|
X_MCP_RATE_LIMITED |
the caller has spent its allowance for this request's class | more than rateLimits.read or rateLimits.write requests in one minute from one actor, metered by mcpHttpRoute after the body is parsed (the class comes out of the body) and before the tool runs. 429 with Retry-After; the bucket key names the actor and never reaches the caller. It has its own code rather than reusing X_RATE_LIMITED because the KNOB differs — the HTTP pipeline's buckets do not govern this route, so raising them would run and change nothing |
defineAppMcp({ rateLimits: { ...MCP_RATE_LIMITS, read: <n> } }) (or mcpHttpRoute({ rateLimits })) where the route is built — the fix: line doubles the class that refused — or wait out the Retry-After. Behind N replicas pass rateLimitStore: postgresRateLimitStore({ executor }) too, or each enforces the full allowance on its own |
X_MCP_RECIPE_EXAMPLE_INVALID |
an MCP recipe step's example fails its tool's input | the tool's input schema changed and the recipe's example did not | example: { … } — correct step.example in the recipe the cause names; the issues name the field |
X_MCP_RECIPE_LINK_DANGLING |
a recipe links to a docs://recipes/ URI no recipe serves | a recipe's markdown names docs://recipes/, and recipes: on that server holds no recipe by that name | recipes: [...(await markdownRecipes({ dir })), <the missing recipe>] — or correct the link in the file the cause names |
X_MCP_RECIPE_TOOL_UNKNOWN |
an MCP recipe step names a tool this server does not project | a tool was renamed or removed and a recipe still names it | steps: [{ tool: <a name the cause lists>, why }] — rename step.tool in the recipe the cause names, or expose the tool |
X_MCP_RECIPE_UNKNOWN |
an error links to a docs://recipes/ URI no recipe serves | defineError({ docs }) or an UltimateError names a recipe that recipes: does not declare | recipes: [{ name: '<name>', title, description, steps }] — add it to defineAppMcp, or drop docs: from the error |
X_MCP_RECIPE_URI_RESERVED |
docs://recipes/ is owned by recipes: | resources: holds a docs://recipes/ URI beside recipes:, or two recipes share a name | recipes: [{ name, title, description, steps }] — move the resource into defineAppMcp's recipes:, one name each |
X_MCP_REMOTE_AUTH_REQUIRED |
a remote MCP server needs authorization this app does not hold | the upstream answered 401: no token was sent, or the one sent expired or was revoked; meta.resourceMetadata names where its authorization server is described | mcpOAuthClient({ clientId, redirectUri }).begin(await client.discover(url)) — send the person to authorizeUrl, then return the token from mcpTools({ auth }) |
X_MCP_REMOTE_REFUSED |
a remote MCP server failed or refused the call | the url is wrong, the server answered a non-2xx other than 401 (a 401 is X_MCP_REMOTE_AUTH_REQUIRED) or a JSON-RPC error, or it spoke no protocol era this client knows |
curl -sS -X POST <url> -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' — then correct mcpTools({ url, auth }) |
X_MCP_REMOTE_TOOL_CHANGED |
a remote MCP server's tool no longer matches tools.lock.json | the remote server renamed, removed or re-shaped a tool that mcpTools({ allow }) names, or the lock was never written | x mcp lock <name> — after reviewing the remote diff the cause prints |
X_MCP_RESOURCE_DUPLICATE |
two resources claim one MCP resource URI | an app resource registered at a ultimate:// URI the framework already publishes, or one registerAll batch listing a URI twice. Resources used to Map.set-overwrite while tools threw, so resources/read answered from whichever provider was wired last |
register({ uri: 'ultimate://manifest-<what-it-is>', … }) — one of the two at its own URI — or drop the duplicate registration |
X_MCP_SCOPE_CONFLICT |
two scopes claim one MCP tool | one tool name listed under two different scopes entries, or under one entry while the tool already carries a different scope of its own |
scopes: { '<scope>': ['<tool>'] } — the tool under the single scope a token must hold for it, the other entry removed |
X_MCP_SCOPE_DENIED |
the connection's token does not carry the tool's scope | a read token calling a write tool. A token's scopes are never widened, so there is no grant verb: x token create --scopes … --json issues a token with the wider set, then x token revoke <old-id>
|
{ actor, scopes: new Set(['<scope>']) } from the app's resolveToken(token), then reconnect — or drop that scope from defineAppMcp({ scopes }). Scopes belong to the token and are fixed for the life of a connection, so a grant takes effect on the next one |
X_MCP_SCOPE_UNCOVERED |
an MCP tool is covered by no scope in the scopes map | defineAppMcp was given a scopes map, and a projected tool is named under none of its scopes, so no token scope could ever gate it. | List the tool under a scope in the scopes map passed to defineAppMcp, or remove it from the projection. |
X_MCP_SCOPE_UNKNOWN |
defineAppMcp scopes a tool this server does not project | a scopes entry in defineAppMcp names a tool by a name absent from the projected catalog — a typo, or the primitive was renamed, or dropped from actions:/queries:/tools:
|
scopes: { '<scope>': ['<a projected name>'] } — one of the projected tool names cause lists — or drop it from that entry |
X_MCP_SURFACE_INVALID |
the MCP meta surface is declared inconsistently | surface: 'meta' with no groups, or groups with a flat-only surface |
surface: 'meta', groups: { … } together in defineAppMcp (or a surface function), or drop both |
X_MCP_SURFACE_OVER_BUDGET |
an MCP surface an agent reads is larger than the app's budget for it | assertMcpSurfaceBudget measured tools/list, list_resources or instructions over the declared character budget |
surface: 'meta' in defineAppMcp groups tools behind it — or shorten the tool descriptions or instructions it names, or raise the budget with the measured size and the reason in the same diff |
X_MCP_TENANT_INVALID |
defineAppMcp declares its tenant argument inconsistently | tenant.arg is not a plain argument name, or a tool of this server already declares an input property of that name | defineAppMcp({ tenant: { arg: 'tenant', resolve, list } }) — pick an argument name no tool's input declares |
X_MCP_TENANT_REQUIRED |
an MCP call names no tenant | defineAppMcp({ tenant }) acts every call in the tenant the call names, and this call carries no tenant argument | list_tenants({}) — then send one of its values as the tenant argument of every tools/call |
X_MCP_TENANT_UNRESOLVED |
the tenant of an MCP call could not be resolved | defineAppMcp({ tenant: { resolve } }) threw, or answered an actor that is not an agent — a failed lookup is never read as "not a member" |
defineAppMcp({ tenant: { arg, resolve: ({ person, value }) => (member ? agentActor({ id: person.id, orgId: value }) : null), list } }) — the cause names what refused; resolve answers a kind: 'agent' actor, or null for a non-member, and never throws |
X_MCP_TOOL_DUPLICATE |
two primitives project to one MCP tool name | a tools: record key colliding with an exposed action, or an action and a query sharing a name |
rename one — the tool name is the primitive's export name, or the tools record key |
X_MCP_TOOL_UNDECLARED |
defineAppMcp lists a primitive that declares no MCP exposure |
an action or query named in actions:/queries: with no mcp block, or mcp: { expose: false }
|
mcp: { expose: true, description } beside the primitive's policy — or drop it from the list and let include: 'exposed' project what opted in |
X_MCP_TOOL_UNKNOWN |
no such tool for this caller | a stale tool name, or one this caller may not see | call tools/list to read the catalog |
X_MCP_TOOL_UNSAFE |
an MCP tool declares no policy | a hand-written tools: entry written without policy
|
policy: '<resource>:<verb>' on the tool, reusing the permission its action uses |
X_MCP_USER_CONFIRMATION_REQUIRED |
a delete_resource commit did not carry confirmed_by_user: true | delete_resource ran with live: true and without confirmed_by_user: true, so nothing ran | delete_resource({ resource, action, params, live: true, confirmed_by_user: true }) once the user has approved the change; live: false previews it without running |
X_MCP_WRONG_TOOL |
a meta-split action was called through the wrong dispatcher | read_resource, write_resource and delete_resource each run only the actions of their own effect, and this action belongs to another | repeat the call on the dispatcher the cause names, with the same resource, action and params |
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference