Skip to content

Error Codes mcp

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/mcp

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

Clone this wiki locally