MCP
Error handling
How the Matter MCP server turns RFC 7807 problems into actionable next-step guidance.
Last updated
For the underlying REST API error model and the canonical RFC 7807 envelope, see API errors. This page covers MCP-specific tool-error shape.
When the Matter API returns an RFC 7807 problem, the MCP server rewrites it into a tool error with a targeted next-step suggestion. Agents get a concrete path forward instead of a bare error code.
Shape of an MCP tool error
{
"isError": true,
"code": "invalid_state_transition",
"httpStatus": 409,
"message": "Entity `ent_Nq3KcAbc` is in state `dissolved`; this operation requires `active`. Call `matter_retrieve_entity` to inspect the current state, then invoke the appropriate transition tool (`matter_reinstate_entity`, `matter_execute_intent`, etc.).",
"problem": { /* the raw RFC 7807 response */ }
}The raw problem is preserved so agents that want to introspect it — or forward it to a
logging pipeline — can.
Example mappings
| Code | Suggested next step |
|---|---|
invalid_state_transition | Inspect state, call the right transition tool. |
tier_insufficient | Create an Authorization for human sign-off, or request higher-tier token. |
human_signature_required | Poll or subscribe to authorization.approved, then retry with same Idempotency-Key. |
compliance_deadline_past | Consider late-filing penalties; call the filing endpoint with acknowledge_late: true. |
valuation_expired | Call matter_create_valuation first, then retry ISO grant. |
insufficient_authorized_shares | File amendment to increase authorized, or reduce issuance quantity. |
filing_rejected_by_state | Retrieve filing detail; common fixes via matter_change_registered_agent or matter_update_entity. |
idempotency_key_reused_with_different_body | Generate a fresh UUID key, or restore original payload. |
rate_limited | Wait retry_after seconds. |
Full mapping table: apps/mcp/src/error-map.ts. A CI test asserts 1:1 coverage between every code in errors and a mapping.
Request IDs
Every tool response includes the request_id from the underlying API call (surfaced in
the problem.request_id field for errors, and in _request_id in the tool's structured
content for success). Agents should log this alongside any error — support can triage
via GET /v1/requests/{id} with a 7-day retention window.
Follow-up hints on async mutations
On 202 Accepted, the MCP tool adds a _follow_up field to structured content:
{
"_follow_up": "The operation is in progress. Subscribe to updates with `matter_subscribe_to_events` or poll the resource."
}Well-trained agents pick up the hint and open a stream rather than hammering the poll endpoint.
Retries
The MCP server does not auto-retry on transient errors. That's the agent's
responsibility — every tool is idempotent when a client-supplied idempotency_key is
passed, so retry is safe. The Matter-recommended retry policy is exponential backoff
starting at 1s, capped at 5 attempts per logical request.