fastmcp.exceptions
Custom exceptions for FastMCP.
Functions
to_mcp_error
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
FastMCPDeprecationWarning
Deprecation warning for FastMCP APIs.
Subclass of DeprecationWarning so that standard warning filters
still apply, but FastMCP can selectively enable its own warnings
without affecting other libraries in the process.
FastMCPError
Base error for FastMCP.
ValidationError
Error in validating parameters or return values.
ResourceError
Error in resource operations.
ToolError
Error in tool operations.
PromptError
Error in prompt operations.
InvalidSignature
Invalid signature for use with FastMCP.
ClientError
Error in client operations.
NotFoundError
Object not found.
DisabledError
Object is disabled.
ResourceSecurityError
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
Error when authorization check fails.
InsufficientScopeError
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.