Error model

How the Seal MCP server reports tool-call failures back to the AI client.

Tool calls return one of two shapes:

• Success. The tool's structured result, per the tool's schema.

• Failure. An MCP ToolError with a human-readable message and, where applicable, a machine-readable status code.

Failure categories

• Authorization. The calling user lacks the permission the tool requires. The error names the missing permission.

• Validation. The arguments do not match the tool's schema. The error names the offending field.

• Not found. The referenced resource does not exist in this tenant. The error names it.

• Conflict. A mutation would violate an invariant (creating a Sealing Rule that already exists, deleting one already deleted). The error names the conflict.

• Upstream. A downstream service (GitHub, the artifact server, or another Seal service) returned an unrecoverable error. The error names the upstream.

Timeouts

Each tool call has a server-side timeout appropriate to its underlying operation. Long-running operations (Generate fix, large repository scans) are asynchronous: the tool returns quickly with a handle you poll later.

Retries

Read-only tools (list_*, get_*) are safe to retry on transient failures. Most mutating tools are idempotent on identical input; per-tool descriptions document the exceptions.

Related

• Tool catalog

• Authentication