FastMCP review: Validation, timeouts and tool scopes

Testing FastMCP 4.1.6 over real stdio and HTTP: input coercion, output contracts, error masking, timeout side effects and JWT tool permissions.

AgentIndex · Published 2026-11-07 · Updated 2026-11-07

FastMCP turns Python functions into MCP capabilities. We tested what happens at that boundary: whether invalid arguments reach application code, who checks returned data, how timeouts affect work already underway and whether selected tool scopes work over authenticated HTTP.

The framework generated useful schemas, rejected the tested invalid inputs and carried structured results, resources and prompts through real connections. Three distinctions mattered: default coercion differed from strict validation; an output schema did not make the raw server response conform to it; and a timeout error did not undo a synchronous worker's journal write.

A pinned implementation and an independent client

On November 7, 2026, we installed fastmcp==4.1.6. The outer package pins fastmcp-slim at the same version, where the implementation lives. We verified both PyPI wheels and compared eight selected implementation files with release commit 1302563111a0e72176174cdb5ac19838cb0687c3. The slim wheel's SHA-256 was d25691ae70a7f2b9d8197d6261bdd0f4b9ff33064087cd35c20539b0b48bb1ca. Fixed release

Execution used macOS 26.6.2 on Apple M1 Pro, x86_64 Python 3.13.1, Pydantic 2.14.3 and MCP Python SDK 2.3.0. A binary-only install and pip check succeeded; the reproduction directory fixes 62 packages.

We wrote an artificial application with quote, error and timeout tools, plus resources and a prompt backed by six frozen public AgentIndex records. The business calculations and journal were our specimen; FastMCP supplied registration, schema generation, validation and transport. The reference SDK drove two stdio servers and one loopback HTTP server through four client sessions, issuing 42 tool requests, including deliberate failures. Five additional HTTP authentication probes were rejected.

The source fingerprints, fixture and raw results preserve those operations. No mocked MCP responses, model calls, production services or external identity provider were involved. Python connection auditing recorded only loopback destinations across four processes; update checks and telemetry were disabled.

CheckObserved result
Generated argument schemaRequired fields and quantity bounds appeared; injected Context was absent
Missing, empty or out-of-range inputRejected before the quote function entered
Numeric string for an integerConverted by the default profile; rejected by strict input validation
Deliberately invalid return objectRaw server result had isError=false; SDK output validation rejected it
Error maskingHid the internal marker; preserved the explicitly raised ToolError message
Async versus worker-thread timeoutAsync task cancelled; synchronous completion marker still appeared
Resources and promptFrozen records and Chinese text survived the tested requests
HTTP JWT and per-tool scopeInvalid credentials rejected; reader could not execute the writer tool

Input validation protected the function body

Our quote function declared a nonempty item name and integer quantity from 1 to 50. The generated schema reflected those constraints and omitted the injected Context argument, which the caller should not supply.

We sent quantities zero and 51, a missing quantity and an empty item name through raw protocol calls. Each returned a tool error. A separate application journal confirmed that none entered the quote body. The valid request returned the expected structured object with Chinese text. This verifies the framework's tested argument-to-function boundary; the quoted price itself was our application logic.

The string "3" showed why configuration matters. With the default profile, it reached the body as integer 3; with strict_input_validation=True, it was rejected without another body entry. Both profiles advertised an integer in JSON Schema. Readers needing JSON-type enforcement should explicitly choose and test the strict setting rather than infer it from the schema alone. Input execution path

Output validation happened on the client in our negative case

We deliberately annotated one function as returning a Pydantic Receipt, then returned an ordinary dictionary with a string where an integer was required and a negative total. That is a broken application contract, intentionally included to test its enforcement.

We first inspected the wire result with the reference session's lower-level send_request, which does not perform its call_tool output check. The server returned the invalid structured object with isError=false in both profiles. We independently checked it against the advertised schema and confirmed the mismatch.

Calling the same tool through SDK ClientSession.call_tool then raised RuntimeError for invalid structured content. The strict-input setting had not made output validation a server guarantee. Keep the client's validation, and construct validated return models in application code when that is the intended contract. Our valid quote tool returned a constructed Receipt; the negative tool did not. Result conversion

This finding covers the tested annotated-dictionary path. It does not establish that every output type or integration skips server-side checks.

Masking and timeouts change different parts of the contract

With default error-detail handling, an internal ValueError exposed our artificial marker in the response. Setting mask_error_details=True removed it. An explicitly raised ToolError remained visible in both profiles, allowing the application to provide an intentional caller-facing error. We tested those response paths, not a general redaction guarantee. Settings

Both timeout tools had a 0.15-second execution deadline. The async tool awaited one second, recorded cancellation and never recorded completion. The synchronous tool used the default worker-thread path, slept 0.4 seconds and wrote a completion marker. After receiving its timeout error, the client still found that marker in the journal.

A timeout therefore was not evidence that the application had done nothing. This controlled case supports checking business state and designing retries around idempotency when tools write data. It is not a benchmark of timeout precision, database transactions or all cancellation paths.

Resources, prompts and HTTP permissions also ran

In both stdio profiles, static and templated resources returned the expected frozen public records. The prompt endpoint returned the selected record's Chinese description inside our template. No model generated a response from that prompt. We tested these protocol surfaces as data delivery, not retrieval quality or model reasoning.

For HTTP, we generated a temporary RSA key pair and configured the published JWTVerifier with a static public key, issuer, audience and required catalog:read scope. Missing credentials, a wrong signature, an expired token, a wrong audience and a token lacking that global scope each returned HTTP 401.

A valid reader token could call the ordinary tools, but its tool list omitted the action protected by require_scopes('ledger:write'). Naming that action directly returned an error without a write marker. A token containing both scopes listed and executed it, producing exactly one protected marker. Tool-level scope checks were available in this open-source package and worked in this selected path. JWT verifier, scope checks

This was local signed-token validation, not an OAuth login, SSO integration, key-rotation exercise or production security audit.

Adoption decision

FastMCP is worth evaluating when you want to expose Python functions, resources and prompts while keeping responsibility for application contracts. The tested release declares Python 3.10 or newer. Pin the package and its implementation, choose coercion and masking deliberately, and retain independent client checks.

We did not evaluate FastMCP’s own client API, Apps, task extensions, remote identity providers, other operating systems, migrations, sustained concurrency, speed advantages or model autonomy. For another MCP result-contract example, see our Headroom compression and retrieval review. For state and failure recovery in a browser tool, see the Playwright MCP workflow tests.

For document-ingestion tools, our Xberg PDF and OCR review shows a different acceptance boundary: successful extraction can still contain wrong numbers, and partial batch errors need explicit handling.