fastmcp.exceptions

Custom exceptions for FastMCP.

Functions

to_mcp_error ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

to_mcp_error(exc: Exception) -> MCPError

Translate a FastMCP exception into a wire-format MCPError.

Central mapping from FastMCP's public exception types to the JSON-RPC error codes defined by the MCP spec (imported from mcp_types). Request-handler adapters call this instead of hand-rolling MCPError(code=..., ...) per call site, so the wire codes stay spec-correct and consistent across resources, prompts, and tools.

NotFoundError and DisabledError map to INVALID_PARAMS (-32602): per SEP-2164 a request naming a component that does not exist (or is disabled) is an invalid-params error, which matches the SDK's own ResourceNotFoundError -> INVALID_PARAMS mapping in mcp.server.mcpserver. ValidationError is also an invalid-params error. Everything else falls back to default_code (INTERNAL_ERROR by default).

If exc is already an MCPError, it is returned unchanged so an explicit code chosen upstream survives translation.

Classes

FastMCPError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L38" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Base error for FastMCP.

ValidationError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L46" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in validating parameters or return values.

ResourceError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L50" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in resource operations.

ToolError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in tool operations.

PromptError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L58" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in prompt operations.

InvalidSignature ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Invalid signature for use with FastMCP.

ClientError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in client operations.

NotFoundError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Object not found.

DisabledError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Object is disabled.

ResourceSecurityError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A templated resource parameter failed path-security screening.

Subclasses NotFoundError so the read handler surfaces a non-leaky INVALID_PARAMS (-32602) "resource not found" error to the client — a traversal attempt is indistinguishable from a request for a resource that does not exist, and never reveals which parameter or policy tripped.

AuthorizationError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error when authorization check fails.

InsufficientScopeError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Authorization failed because the token is missing required OAuth scopes.

Unlike a bare AuthorizationError, this carries the specific scopes the caller must obtain. A component-level scope shortfall can then be signalled as a spec-correct insufficient_scope step-up (SEP-2350 / RFC 6750 §3), naming exactly what to re-authorize for instead of an opaque denial. The named scopes are only the unmet ones, so an existing grant is accumulated rather than replaced when the caller re-authorizes.