NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #408 most downloaded on PyPI
The fast, Pythonic way to build MCP servers and clients.
Latest stable
4.2.2
Last release today
18 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
2 years old
149 releases · first in 2024
Drag across the ruler to compare, or tap a release to open it.
Breaking changes. Server-initiated sampling and roots are removed from the server API: both pushed a request down a live connection, which the session…
FastMCP 4 makes stateful MCP applications work on the sessionless 2026-07-28 protocol while one deployment continues serving handshake-era clients. Tools can ask follow-up questions across requests, preserve authenticated user state, and move long-running work into background tasks without sticky sessions or a continuously connected client.
The engine underneath changed completely. MCP Python SDK v2 rewrote the protocol layer end to end — protocol types moved into a standalone mcp_types package (still importable as mcp.types), model fields use snake_case in Python, and the server request-handling model was replaced. FastMCP absorbs nearly all of it, so most FastMCP 3 servers upgrade untouched.
🌐 Every protocol era — modern and handshake-era clients are served simultaneously, negotiated per connection. Modern requests can be handled by any replica behind an ordinary load balancer.
💬 Interactive tools — tools ask follow-up questions across complete request-response rounds. Shared request-state keys let any replica resume the next round after load balancing or a worker restart.
💾 State without a session — UserSession and SessionId give tools explicit per-user state on a protocol that deliberately has none (SEP-2567), stored server-side and keyed to the authenticated user.
⏳ Background tasks — the io.modelcontextprotocol/tasks extension (SEP-2663), shipped in the new fastmcp-tasks package on the same Docket engine FastMCP 3 used. @mcp.tool(task=True) is still the whole authoring surface.
🧩 Server extensions — add_extension() turns capability-negotiated protocol features (SEP-2133) into a supported plugin surface instead of surgery on core.
🔐 Enterprise auth — complete server-side identity assertion (SEP-990), plus require_roles, incremental-authorization step-up challenges (SEP-2350), DCR application_type (SEP-837), and routable transport headers for gateways (SEP-2243).
⌨️ Argument completion — a @mcp.completion handler answers autocomplete for prompt arguments and resource-template parameters, and can narrow suggestions using the arguments already supplied.
Breaking changes. Server-initiated sampling and roots are removed from the server API: both pushed a request down a live connection, which the sessionless protocol no longer has, and a method that only works against old clients is a trap. Elicitation continues in a request-shaped form, and generation belongs in your server — call an LLM directly. The 3.x-era compatibility shims are also gone. The upgrade guide walks through every change.
Install the beta by pinning it explicitly:
uv add "fastmcp==4.0.0b1"
This is a beta released for testing ahead of 4.0. Pin an exact version and expect sharp edges.
<!-- Release notes generated using configuration in .github/release.yml at main -->
valid_scopes parameter to OIDC proxy valid scopes by @Educg550 in https://github.com/PrefectHQ/fastmcp/pull/4660required order deterministic by @Kludex in https://github.com/PrefectHQ/fastmcp/pull/4564Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.5...v4.0.0b1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
FastMCP 4 makes stateful MCP applications work on the sessionless 2026-07-28 protocol while one deployment continues serving handshake-era clients. Tools can ask follow-up questions across requests, preserve authenticated user state, and move long-running work into background tasks without sticky sessions or a continuously connected client.
The engine underneath changed completely. MCP Python SDK v2 rewrote the protocol layer end to end — protocol types moved into a standalone mcp_types package (still importable as mcp.types), model fields use snake_case in Python, and the server request-handling model was replaced. FastMCP absorbs nearly all of it, so most FastMCP 3 servers upgrade untouched.
🌐 Every protocol era — modern and handshake-era clients are served simultaneously, negotiated per connection. Modern requests can be handled by any replica behind an ordinary load balancer.
💬 Interactive tools — tools ask follow-up questions across complete request-response rounds. Shared request-state keys let any replica resume the next round after load balancing or a worker restart.
💾 State without a session — UserSession and SessionId give tools explicit per-user state on a protocol that deliberately has none (SEP-2567), stored server-side and keyed to the authenticated user.
⏳ Background tasks — the io.modelcontextprotocol/tasks extension (SEP-2663), shipped in the new fastmcp-tasks package on the same Docket engine FastMCP 3 used. @mcp.tool(task=True) is still the whole authoring surface.
🧩 Server extensions — add_extension() turns capability-negotiated protocol features (SEP-2133) into a supported plugin surface instead of surgery on core.
🔐 Enterprise auth — complete server-side identity assertion (SEP-990), plus require_roles, incremental-authorization step-up challenges (SEP-2350), DCR application_type (SEP-837), and routable transport headers for gateways (SEP-2243).
⌨️ Argument completion — a @mcp.completion handler answers autocomplete for prompt arguments and resource-template parameters, and can narrow suggestions using the arguments already supplied.
Breaking changes. Server-initiated sampling and roots are removed from the server API: both pushed a request down a live connection, which the sessionless protocol no longer has, and a method that only works against old clients is a trap. Elicitation continues in a request-shaped form, and generation belongs in your server — call an LLM directly. The 3.x-era compatibility shims are also gone. The upgrade guide walks through every change.
Install the beta by pinning it explicitly:
uv add "fastmcp==4.0.0b1"This is a beta released for testing ahead of 4.0. Pin an exact version and expect sharp edges.
valid_scopes parameter to OIDC proxy valid scopes by @Educg550 in #4660required order deterministic by @Kludex in #4564Note truncated.
Nothing published for this version
Document v3->v4 removals and add upgrade-reality tests
Document v3->v4 removals and add upgrade-reality tests (#4585)
* Document v3->v4 removals and add upgrade-reality tests
* Check canonical imports in a clean subprocess to avoid suite import pollution
* Address review: import_server semantics note, pin traversal error, drop redundant import
* Address review round 2: real screening test, Depends factory, remove_tool/create_proxy notes
* Validate canonical imports in-process; fix lifespan/timeout/error-code/starlette doc notes
* Reconcile with fastmcp.types trim: import protocol types from mcp_types
* Record v4 release codename arc in dev notes
This release requires certifi 2026.10.19 or later for FastMCP's HTTP stack and certifi-backed integrations following the eMudhra CA compromise. Follow
This release requires certifi 2026.10.19 or later for FastMCP's HTTP stack and certifi-backed integrations following the eMudhra CA compromise. Follow the security notice to update custom, system, and installer trust stores too; upgrading FastMCP alone is insufficient. Thanks to our 1 contributor, with no first-time contributors in this release.
Full Changelog: v3.4.10...v3.4.11
This release backports component authorization checks after transforms and prevents denied concrete resources from being served by matching templates.
This release backports component authorization checks after transforms and prevents denied concrete resources from being served by matching templates. All 3.x users are encouraged to upgrade. Thanks to our 2 contributors, including 1 first-time contributor.
Full Changelog: v3.4.9...v3.4.10
This release backports security fixes from 4.1: OpenAPI path parameters reject . and .. segments, a skill's SKILL.md must stay inside its skill folder…
This release backports security fixes from 4.1: OpenAPI path parameters reject . and .. segments, a skill's SKILL.md must stay inside its skill folder, regex tool search is bounded in time and pattern length, and JWT verifiers share JWKS refreshes instead of fetching on every unknown key ID. All 3.x users are encouraged to upgrade. Thanks to our 6 contributors, including 3 first-time contributors.
Full Changelog: v3.4.8...v3.4.9
This release backports security fixes from 4.1: OpenAPI path parameters reject . and .. segments, a skill's SKILL.md must stay inside its skill folder, regex tool search is bounded in time and pattern length, and JWT verifiers share JWKS refreshes instead of fetching on every unknown key ID. All 3.x users are encouraged to upgrade. Thanks to our 6 contributors, including 3 first-time contributors.
<!-- Release notes generated using configuration in .github/release.yml at release/3.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.8...v3.4.9
This release contains important security and bug fixes. All users are encouraged to upgrade. Thanks to our 2 contributors.
This release contains important security and bug fixes. All users are encouraged to upgrade. Thanks to our 2 contributors.
Full Changelog: v3.4.7...v3.4.8
FastMCP 3.4.7 restores CIMD private_key_jwt authentication for OAuthProxy deployments at a bare origin. Client assertions are now validated against th
FastMCP 3.4.7 restores CIMD private_key_jwt authentication for OAuthProxy deployments at a bare origin. Client assertions are now validated against the exact token endpoint advertised in authorization server metadata, eliminating the doubled-slash audience mismatch.
<!-- Release notes generated using configuration in .github/release.yml at release/3.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.6...v3.4.7
FastMCP 3.4.7 restores CIMD private_key_jwt authentication for OAuthProxy deployments at a bare origin. Client assertions are now validated against the exact token endpoint advertised in authorization server metadata, eliminating the doubled-slash audience mismatch.
Full Changelog: v3.4.6...v3.4.7
FastMCP 3.4.6 backports trusted-proxy support for SSRF-protected OAuth metadata and JWKS fetches. Deployments can now route these requests through a m
FastMCP 3.4.6 backports trusted-proxy support for SSRF-protected OAuth metadata and JWKS fetches. Deployments can now route these requests through a mandated corporate proxy while preserving custom CA certificates; FastMCP refuses the fetch when no proxy is configured instead of risking an unprotected direct request.
<!-- Release notes generated using configuration in .github/release.yml at release/3.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.5...v3.4.6
FastMCP 3.4.6 backports trusted-proxy support for SSRF-protected OAuth metadata and JWKS fetches. Deployments can now route these requests through a mandated corporate proxy while preserving custom CA certificates; FastMCP refuses the fetch when no proxy is configured instead of risking an unprotected direct request.
Full Changelog: v3.4.5...v3.4.6
FastMCP 3.4.5 collects five fixes for the 3.x line. The one that prompted it: a single Ed25519 key in a JWKS — which Rauthy, Ory Hydra, and some Keycl
FastMCP 3.4.5 collects five fixes for the 3.x line. The one that prompted it: a single Ed25519 key in a JWKS — which Rauthy, Ory Hydra, and some Keycloak configurations publish by default — made JWTVerifier reject every token, including ones correctly signed by supported keys in the same set.
<!-- Release notes generated using configuration in .github/release.yml at release/3.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.4...v3.4.5
FastMCP 3.4.5 collects five fixes for the 3.x line. The one that prompted it: a single Ed25519 key in a JWKS — which Rauthy, Ory Hydra, and some Keycloak configurations publish by default — made JWTVerifier reject every token, including ones correctly signed by supported keys in the same set.
Full Changelog: v3.4.4...v3.4.5
FastMCP 3.4.4 restores HTTP deployment compatibility after the 3.4.3 Host/Origin guard changed default behavior for existing ASGI, serverless, and rev
FastMCP 3.4.4 restores HTTP deployment compatibility after the 3.4.3 Host/Origin guard changed default behavior for existing ASGI, serverless, and reverse-proxy deployments. The guard implementation remains available for deployments that opt in with explicit trusted hosts and origins, while 3.x returns to accepting traffic that worked before the patch. This release also adds Hugging Face OAuth provider support, with docs and examples for public and private apps, PKCE, Dynamic Client Registration, and CIMD.
<!-- Release notes generated using configuration in .github/release.yml at release/3.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.3...v3.4.4
FastMCP 3.4.4 restores HTTP deployment compatibility after the 3.4.3 Host/Origin guard changed default behavior for existing ASGI, serverless, and reverse-proxy deployments. The guard implementation remains available for deployments that opt in with explicit trusted hosts and origins, while 3.x returns to accepting traffic that worked before the patch. This release also adds Hugging Face OAuth provider support, with docs and examples for public and private apps, PKCE, Dynamic Client Registration, and CIMD.
Full Changelog: v3.4.3...v3.4.4
FastMCP 3.4.3 closes out a month of SSRF and OAuth hardening: NAT64, 6to4, Teredo, and ISATAP transition addresses can no longer smuggle private IPv4
FastMCP 3.4.3 closes out a month of SSRF and OAuth hardening: NAT64, 6to4, Teredo, and ISATAP transition addresses can no longer smuggle private IPv4 targets past the SSRF allow-list, Streamable HTTP now validates Host and Origin before session handling to block DNS rebinding against localhost-bound servers, and OAuth redirect validation rejects unsafe schemes and unregistered DCR redirect URIs. Alongside the security work, this release also fixes proxy session teardown races, discriminator-tag handling in JSON schema conversion, and several smaller reliability issues.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.2...v3.4.3
FastMCP 3.4.2 restores JWT compatibility for providers that include private, non-critical JWS header parameters. Tokens from providers like Clerk can
FastMCP 3.4.2 restores JWT compatibility for providers that include private, non-critical JWS header parameters. Tokens from providers like Clerk can carry header metadata such as cat without being rejected before signature and claim validation, while unsupported critical headers are still rejected.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.1...v3.4.2
FastMCP 3.4.1 floors Starlette at >=1.0.1 so installs can no longer resolve to a version affected by CVE-2026-48710 — previously the dependency was on…
FastMCP 3.4.1 floors Starlette at >=1.0.1 so installs can no longer resolve to a version affected by CVE-2026-48710 — previously the dependency was only constrained transitively through mcp, which allowed vulnerable versions. It also makes OAuthProxy log refresh-token cache misses instead of failing silently.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.4.0...v3.4.1
FastMCP 3.4 is about reaching servers that live somewhere else. The headline is fastmcp-remote, a standalone bridge that connects stdio-only MCP hosts
FastMCP 3.4 is about reaching servers that live somewhere else. The headline is fastmcp-remote, a standalone bridge that connects stdio-only MCP hosts to servers hosted over HTTP. Around it, this release hardens the proxy layer those remote connections depend on — making bridges fail loudly instead of silently, and keeping authenticated sessions alive across the long idle periods that remote clients are prone to.
Some MCP hosts still insist on launching a local stdio command, even when the server you want is already running over HTTP. FastMCP could already proxy a remote URL through fastmcp run, but that pulls in the full server-runner surface. fastmcp-remote is the small, single-purpose version: one URL in, one local stdio proxy out.
{
"mcpServers": {
"linear": {
"command": "uvx",
"args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
}
}
}
OAuth is enabled automatically for HTTPS servers, with support for explicit bearer tokens and custom headers when you need them. The implementation stays on FastMCP primitives — Client, OAuth, create_proxy, and stdio — and credits the original npm mcp-remote project for the command shape.
Proxies are lazy bridges: they don't touch the upstream server during construction, but they do forward real MCP requests once a client connects. As of 3.4, initialize is part of that forwarded surface — so a proxy only reports a successful handshake after the upstream server initializes too. A missing backend, a wrong URL (the server root instead of /mcp), denied upstream auth, or a non-MCP upstream now fails the downstream initialize instead of producing a "connected" proxy whose capability fetches quietly come back empty. The proxy also forwards ping upstream now.
This is an intentional behavior change from 3.3, and the reason bridge callers like fastmcp-remote surface real upstream failures instead of degrading into empty tool lists.
Remote sessions sit idle, and short-lived upstream tokens punish that. fastmcp_access_token_expiry_seconds decouples the FastMCP-issued token's lifetime from the upstream expires_in — the FastMCP token is just a reference into proxy storage, re-validated and transparently refreshed on every request, so it can safely outlive a 5-minute upstream token without forcing a full OAuth flow after every idle period. When the upstream issues no refresh token, the lifetime is capped to match.
from fastmcp.server.auth.providers.github import GitHubProvider
auth = GitHubProvider(
client_id="...",
client_secret="...",
base_url="https://your-server.com",
fastmcp_access_token_expiry_seconds=60 * 60 * 24, # 24h client-facing token
)
Alongside it, token_expiry_threshold_seconds treats tokens as expired N seconds early to close refresh races, and WorkOSProvider gains valid_scopes and extra_authorize_params.
A tool could previously only signal an error by raising, which flattens to a text-only result and discards structured content. ToolResult now accepts is_error, mapping to CallToolResult.isError so a tool can hand back a rich error the model can see and act on. The proxy uses this to forward upstream tool errors intact instead of collapsing them.
@mcp.tool
def lookup(id: str) -> ToolResult:
if not found(id):
return ToolResult(
content="not found",
structured_content={"code": 404, "id": id},
is_error=True,
)
...
MontySandboxProvider() now applies a conservative baseline when constructed without limits — 30s duration, 100 MB memory — and CodeMode caps tool calls at 50 per execute block. Both remain explicitly opt-out (limits=None, max_tool_calls=None), so the safe configuration is the default instead of something you had to remember to turn on.
The auth stack migrated its JWT handling to joserfc. The fastmcp dev CLI gains --host and --log-panel/--no-log-panel. Resources created from templates now preserve annotations, meta, title, and icons; resource templates with query params work on proxied servers; OTEL spans cover the sampling step and tool execution; MCP config files are read as UTF-8; and the OAuth server metadata endpoint now answers at the /.well-known/openid-configuration alias.
8 new contributors this release.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.3.1...v3.4.0
FastMCP 3.4 introduces fastmcp-remote, a standalone Python utility for connecting stdio-only MCP hosts to remote MCP servers.
FastMCP 3.4 introduces fastmcp-remote, a standalone Python utility for connecting stdio-only MCP hosts to remote MCP servers.
When a host expects to launch a local command, fastmcp-remote runs locally, connects to a remote server over Streamable HTTP or SSE, and exposes that server back to the host over stdio:
{
"mcpServers": {
"remote-api": {
"command": "uvx",
"args": ["fastmcp-remote", "https://example.com/mcp"]
}
}
}
OAuth is enabled automatically for HTTPS servers, with support for explicit bearer tokens and custom headers when needed.
Please note: the FastMCP 3.4.0 betas are being released for testing the new fastmcp-remote package, host compatibility, and remote authentication behavior, and should not be used for production deployments yet.
FastMCP 3.3.1 is a hotfix for the 3.3 packaging split. Clean installs of 3.3.0 could fail on standalone component imports like from fastmcp.tools impo
FastMCP 3.3.1 is a hotfix for the 3.3 packaging split. Clean installs of 3.3.0 could fail on standalone component imports like from fastmcp.tools import tool because component modules reached auth and task primitives through fastmcp.server, pulling in the server/provider stack and exposing a circular import.
Component-level auth and task primitives now live in lightweight utility modules, with the old server import paths preserved as compatibility re-exports. Component imports stay lightweight, existing server-facing imports continue to work, and the release also includes small docs corrections from the 3.3 rollout.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.3.0...v3.3.1
fix(auth): silence authlib.jose DeprecationWarning at JWT import by @SarthakB11 in https://github.com/PrefectHQ/fastmcp/pull/4100
FastMCP 3.3 ships fastmcp-slim, a new lightweight distribution that separates the client from the server stack. It also closes out a meaningful backlog of security hardening, observability improvements, and auth additions that accumulated through the 3.2 cycle.
The full FastMCP package pulls in Starlette, Uvicorn, and the rest of the server machinery — necessary for running a server, but wasteful if you're writing a client, a script, or an agent that just needs to talk to MCP. fastmcp-slim is a dependency-light distribution that ships the client and transport layer without any of that.
The import namespace is unchanged:
from fastmcp import Client
async with Client("https://example.com/mcp") as client:
result = await client.call_tool("my_tool", {"arg": "value"})
Install fastmcp-slim[client] anywhere you want FastMCP's client without the server footprint — CI environments, lightweight agents, library dependencies that shouldn't force Uvicorn on downstream users.
The OAuth proxy received three hardening upgrades. Silent consent is now guarded against AS-in-the-middle attacks — a malicious authorization server can no longer silently approve a consent it wasn't meant to handle. Redirect URI allowlist matching now rejects dot-segment paths (/../, /./) that could otherwise bypass prefix checks. And ResponseCachingMiddleware partitions its cache by access token, closing a gap where different users could see each other's cached responses.
AzureB2CProvider adds first-class support for Azure AD B2C user flows. The OCI provider is fixed for 3.x installs. And OAuthProxy gains a public update_scopes() API for updating the proxy's required scopes after initialization — useful for servers that determine scope requirements at runtime.
OTEL instrumentation is now fully compliant with MCP semantic conventions. List operations (list_tools, list_resources, list_prompts, list_resource_templates) are instrumented, and delegate spans on proxy servers are enriched with backend attributes.
Sync tools run in a thread pool by default. If your tool holds thread-local state or is bound to a specific thread (UI frameworks, some database drivers), you can now opt out:
@mcp.tool(run_in_thread=False)
def my_tool() -> str:
...
Docket is now reentrant, and mounted servers enter their own lifespan — so a server with startup/shutdown logic works correctly when composed into a larger server. The FastMCP constructor accepts experimental_capabilities for passing raw capability flags. Tool errors accept a log_level parameter to control how they're logged. FormInput supports a default prefill value.
Fixes: ping loop now exits cleanly when a stream closes; sampling from background tasks works correctly; Windows startup no longer crashes on non-UTF-8 console output; blank query string values are preserved in OpenAPI routing; $defs introduced by ArgTransform are hoisted to the schema root; HTTP transports are terminated before lifespan shutdown.
13 new contributors this release.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.2.4...v3.3.0
FastMCP 3.3 introduces fastmcp-slim, a dependency-light distribution for users who want the FastMCP client without installing the full server framewor
FastMCP 3.3 introduces fastmcp-slim, a dependency-light distribution for users who want the FastMCP client without installing the full server framework.
The import namespace stays the same: client-only consumers can install fastmcp-slim[client] and continue writing ordinary FastMCP client code:
from fastmcp import Client
client = Client("https://example.com/mcp")
Please note: the FastMCP 3.3.0 betas are being released for testing the new packages, and should not be used for any other purpose.
FastMCP 3.3 introduces fastmcp-slim, a dependency-light distribution for users who want the FastMCP client without installing the full server framewor
FastMCP 3.3 introduces fastmcp-slim, a dependency-light distribution for users who want the FastMCP client without installing the full server framework.
The import namespace stays the same: client-only consumers can install fastmcp-slim[client] and continue writing ordinary FastMCP client code:
from fastmcp import Client
client = Client("https://example.com/mcp")
Please note: the FastMCP 3.3.0 betas are being released for testing the new packages, and should not be used for any other purpose.
…and stays tied to who started it. This is a breaking change for anyone relying on the old session-scoped semantics.
A grab bag of fixes, hardening, and polish.
The headline behavior change: background tasks are now scoped to the authorization context rather than the MCP session, so a task kicked off by an authenticated user survives session churn and stays tied to who started it. This is a breaking change for anyone relying on the old session-scoped semantics.
Security got three meaningful upgrades. FileUpload now validates actual decoded base64 size instead of trusting the client-reported number, so an attacker can't claim "10 bytes" and deliver 10MB. The proxy client stops forwarding inbound HTTP headers to unrelated remote servers — previously a header meant for server A could leak to server B. And AuthKit now auto-binds token audience to the resource URL per RFC 8707, closing a token-reuse gap across MCP resources.
Schema handling had a rough-edges pass. json_schema_to_type no longer crashes on Python keywords, boolean schemas, empty enums, or name collisions, and we added a 232K-schema crash test from APIs.guru to keep it honest. Gemini 2.5 Flash compatibility is fixed by stripping title fields the model rejects. Parameter descriptions are now extracted from docstrings automatically, so your tool signatures document themselves.
Plus a Keycloak OAuth provider for enterprise auth, improvements to ctx.elicit() (new response_title/response_description, deprecation warning when called without response_type), and dozens of smaller fixes across transforms, retry middleware, resource templates, and client disconnect handling.
<!-- Release notes generated using configuration in .github/release.yml at main -->
or with is not None checks for config/override merging by @strawgate in https://github.com/PrefectHQ/fastmcp/pull/3833Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.2.3...v3.2.4
fakeredis 2.35.0 shipped an undocumented rename (FakeConnection → FakeAsyncRedisConnection) that broke pydocket's memory:// backend, causing fastmcp[t
fakeredis 2.35.0 shipped an undocumented rename (FakeConnection → FakeAsyncRedisConnection) that broke pydocket's memory:// backend, causing fastmcp[tasks] installs to fail at startup with an ImportError. This pins fakeredis<2.35.0 in the tasks extra as a stopgap until a fixed pydocket ships.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.2.2...v3.2.3
The Azure audience fix in 3.2.1 overcorrected: it switched token validation from client_id to identifier_uri, which fixed custom Application ID URIs b
The Azure audience fix in 3.2.1 overcorrected: it switched token validation from client_id to identifier_uri, which fixed custom Application ID URIs but broke the default case where Azure AD v2 tokens set aud to the bare client ID GUID. Both formats are now accepted.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.2.1...v3.2.2
…and asyncio.iscoroutinefunction no longer emits deprecation warnings on Python 3.14.
Most of the fixes in this patch are about auth providers getting audience validation wrong. Cognito token verification was checking the aud JWT claim, but Cognito access tokens don't include one; they use client_id instead. Azure was hardcoding the raw client ID as the expected audience, ignoring the identifier_uri parameter even though Entra v2.0 tokens use the Application ID URI as aud. Both now validate correctly without changing the provider API. Consent cookies also had an unbounded growth problem in high-DCR-client environments, eventually blowing past reverse proxy header limits; they're now capped as an LRU.
On the OpenAPI side, nullable: true fields from 3.0 specs were leaking into tool input schemas as-is instead of being converted to JSON Schema's type: ["string", "null"]. Server variable templates in base URLs (like https://{region}.api.example.com) were also being passed through raw instead of substituted with their defaults.
Smaller fixes: form submissions from Prefab UI now correctly handle unchecked boolean checkboxes, the client no longer crashes on error responses with empty or non-text content from third-party servers, and asyncio.iscoroutinefunction no longer emits deprecation warnings on Python 3.14.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.2.0...v3.2.1
Bump PyJWT >= 2.12.0 (CVE-2026-32597) by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3515
FastMCP 3.2 is the Apps release. The 3.0 architecture gave you providers and transforms; 3.1 shipped Code Mode for tool discovery. 3.2 puts a face on it: your tools can now return interactive UIs — charts, dashboards, forms, maps — rendered right inside the conversation.
FastMCPApp is a new provider class for building interactive applications inside MCP. It separates the tools the LLM sees (@app.ui()) from the backend tools the UI calls (@app.tool()), manages visibility automatically, and gives tool references stable identifiers that survive namespace transforms and server composition — without requiring host cooperation.
from fastmcp import FastMCP, FastMCPApp
from prefab_ui.actions.mcp import CallTool
from prefab_ui.components import Column, Form, Input, Button, ForEach, Text
app = FastMCPApp("Contacts")
@app.tool()
def save_contact(name: str, email: str) -> list[dict]:
db.append({"name": name, "email": email})
return list(db)
@app.ui()
def contact_manager() -> PrefabApp:
with PrefabApp(state={"contacts": list(db)}) as view:
with Column(gap=4):
ForEach("contacts", lambda c: Text(c.name))
with Form(on_submit=CallTool("save_contact")):
Input(name="name", required=True)
Input(name="email", required=True)
Button("Save")
return view
mcp = FastMCP("Server", providers=[app])
The UI is built with Prefab, a Python component library that compiles to interactive UIs. You write Python; the user sees charts, tables, forms, and dashboards. FastMCP handles the MCP Apps protocol machinery — renderer resources, CSP configuration, structured content serialization — so you don't have to.
For simpler cases where you just want to visualize data without server interaction, set app=True on any tool and return Prefab components directly:
@mcp.tool(app=True)
def revenue_chart(year: int) -> PrefabApp:
with PrefabApp() as app:
BarChart(data=revenue_data, series=[ChartSeries(data_key="revenue")])
return app
Five ready-made providers you add with a single add_provider() call:
fastmcp dev apps launches a browser-based preview for your app tools — pick a tool, provide arguments, and see the rendered UI without connecting to an MCP host. Includes an MCP message inspector for debugging the protocol traffic.
This release includes a significant security hardening pass: SSRF/path traversal prevention, JWT algorithm restrictions, OAuth scope enforcement, CSRF fixes, and more. See the changelog for the full list.
forward_resource flag on all OAuth providers for IdPs that don't support RFC 8707. Clerk auth provider. FileResource encoding parameter. SSL verify parameter. client_log_level setting. MCP conformance tests in CI. And contributions from 13 new contributors.
<!-- Release notes generated using configuration in .github/release.yml at main -->
--config-path flag to claude-desktop install command by @Sumanshu-Nankana in https://github.com/PrefectHQ/fastmcp/pull/3380verify parameter for SSL certificate configuration by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3487McpError in initialization middleware to prevent fallthrough by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3413fastmcp list and fastmcp call by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3409version to components in FileSystemProvider by @martimfasantos in https://github.com/PrefectHQ/fastmcp/pull/3458refresh_expires_in=0 as missing, fall back to 30-day default by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3514encoding parameter to FileResource by @shulkx in https://github.com/PrefectHQ/fastmcp/pull/3580Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.1.0...v3.2.0
Pins pydantic-monty<0.0.8 to fix a breaking change in Monty that affects code mode. Monty 0.0.8 removed the external_functions constructor parameter,…
Pins pydantic-monty<0.0.8 to fix a breaking change in Monty that affects code mode. Monty 0.0.8 removed the external_functions constructor parameter, causing MontySandboxProvider to fail. This patch caps the version so existing installs work correctly.
<!-- Release notes generated using configuration in .github/release.yml at release/3.1.1 -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.1.0...v3.1.1
FastMCP 3.1 is the Code Mode release. The 3.0 architecture introduced providers and transforms as the extensibility layer — 3.1 puts that architecture
FastMCP 3.1 is the Code Mode release. The 3.0 architecture introduced providers and transforms as the extensibility layer — 3.1 puts that architecture to work, shipping the most requested capability since launch: servers that can find and execute code on behalf of agents, without requiring clients to know what tools exist.
Standard MCP has two scaling problems. The entire tool catalog loads into context upfront — with a large server, that's tens of thousands of tokens before the LLM reads a single word of the user's request. And every tool call is a round-trip: the LLM calls a tool, the result flows back through the context window, the LLM reasons about it, calls another tool, and so on. Intermediate results that only exist to feed the next step still burn tokens every time.
CodeMode is an experimental transform that solves both. Instead of seeing your tool catalog directly, the LLM gets meta-tools: it searches for relevant tools on demand (using BM25), inspects their schemas, then writes Python that chains call_tool() calls in a sandbox and returns a final answer. Discovery is staged and targeted; intermediate results never touch the model's context window.
from fastmcp import FastMCP
from fastmcp.experimental.transforms.code_mode import CodeMode
mcp = FastMCP("Server", transforms=[CodeMode()])
Your existing tools don't change — CodeMode wraps them. The default three-stage flow (search → get schemas → execute) is configurable: collapse it to two stages for smaller catalogs, skip discovery entirely for tiny ones. The sandbox supports resource limits on time, memory, and recursion depth.
Read the docs here.
Code Mode's discovery layer is also available as a standalone transform. SearchTools adds BM25 text search to any server — clients can query against tool names and descriptions and receive ranked results, without needing to know tool names upfront. This is useful anywhere the tool catalog is large, dynamic, or not known in advance.
3.1 adds early integration with Prefab, a frontend framework with a Python DSL that compiles to React. The vision: Python developers building MCP servers shouldn't have to leave Python to ship a proper UI. Prefab is still under very active development (their words: "probably shouldn't use it yet"), but the integration is here, the pieces are aligning, and 3.2 is where this gets interesting.
MultiAuth lets you compose multiple token verification sources into a single auth layer — useful when you need to accept tokens from more than one provider (e.g., internal JWTs alongside a third-party OAuth provider). This release also adds out-of-the-box support for PropelAuth and a Google GenAI sampling handler.
Heavy imports are now lazy-loaded, meaningfully reducing startup time for servers that don't use every feature. fastmcp run and dev inspector gain a -m/--module flag for module-style invocation, MCPConfigTransport now correctly persists sessions across tool calls, and search_result_serializer gives you a hook to customize how search results are serialized for markdown output. Eight new contributors, and the usual round of fixes.
<!-- Release notes generated using configuration in .github/release.yml at main -->
fastmcp run and dev inspector by @dgenio in https://github.com/PrefectHQ/fastmcp/pull/3331Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.0.2...v3.1.0
Two community-contributed fixes: auth headers from MCP transport no longer leak through to downstream OpenAPI APIs, and background task workers now co
Two community-contributed fixes: auth headers from MCP transport no longer leak through to downstream OpenAPI APIs, and background task workers now correctly receive the originating request ID. Plus a new docs example for context-aware tool factories.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.0.1...v3.0.2
Use max_completion_tokens instead of deprecated max_tokens in OpenAI handler by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3254
First patch after 3.0 — mostly smoothing out rough edges discovered in the wild. The big ones: middleware state that wasn't surviving the trip to tool handlers now does, Tool.from_tool() accepts callables again, OpenAPI schemas with circular references no longer crash discovery, and decorator overloads now return the correct types in function mode. Also adds verify_id_token to OIDCProxy for providers (like some Azure AD configs) that issue opaque access tokens but standard JWT id_tokens.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v3.0.0...v3.0.1
Background tasks with distributed Redis notification and ctx.elicit() relay. Security fixes include dropping diskcache (CVE-2025-69872) and upgrading…
FastMCP 3.0 is stable. Two betas, two release candidates, 21 new contributors, and more than 100,000 pre-release installs later — the architecture held up, the upgrade path was smooth, and we're shipping it.
The surface API is largely unchanged — @mcp.tool() still works exactly as before. What changed is everything underneath: a provider/transform architecture that makes FastMCP extensible, observable, and composable in ways v2 couldn't support. If we did our jobs right, you'll barely notice the redesign. You'll just notice that more is possible.
This is also the release where FastMCP moves from jlowin/fastmcp to PrefectHQ/fastmcp. GitHub forwards all links, PyPI is the same, imports are the same. A major version felt like the right moment to make it official.
🔌 Components no longer have to live in one file with one server. FileSystemProvider discovers tools from directories with hot-reload. OpenAPIProvider wraps REST APIs. ProxyProvider proxies remote MCP servers. SkillsProvider delivers agent skills as resources. Write your own provider for whatever source makes sense. Compose multiple providers into one server, share one across many, or chain them with transforms that rename, namespace, filter, version, and secure components as they flow to clients. ResourcesAsTools and PromptsAsTools expose non-tool components to tool-only clients.
🔐 Component versioning: serve @tool(version="2.0") alongside older versions from one codebase. Granular authorization on individual components with async auth checks, server-wide policies via AuthMiddleware, and scope-based access control. OAuth gets CIMD, Static Client Registration, Azure OBO via dependency injection, JWT audience validation, and confused-deputy protections. OpenTelemetry tracing with MCP semantic conventions. Response size limiting. Background tasks with distributed Redis notification and ctx.elicit() relay. Security fixes include dropping diskcache (CVE-2025-69872) and upgrading python-multipart and protobuf for additional CVEs.
💾 Session state persists across requests via ctx.set_state() / ctx.get_state(). ctx.enable_components() and ctx.disable_components() let servers adapt dynamically per client — show admin tools after authentication, progressively reveal capabilities, or scope access by role.
⚡ --reload auto-restarts on file changes. Standalone decorators return the original function, so decorated tools stay callable in tests and non-MCP contexts. Sync functions auto-dispatch to a threadpool. Tool timeouts, MCP-compliant pagination, composable lifespans, PingMiddleware for keepalive, and concurrent tool execution when the LLM returns multiple calls in one response.
🖥️ fastmcp list and fastmcp call query and invoke tools on any server from a terminal. fastmcp discover scans your editor configs (Claude Desktop, Cursor, Goose, Gemini CLI) and finds configured servers by name. fastmcp generate-cli writes a standalone typed CLI where every tool is a subcommand. fastmcp install registers your server with Claude Desktop, Cursor, or Goose in one command.
📱 Spec-level support for MCP Apps is in: ui:// resource scheme, typed UI metadata via AppConfig, extension negotiation, and runtime detection. The full Apps experience lands in 3.1.
If you hit 3.0 because you didn't pin your dependencies and something breaks — the upgrade guides will get you sorted. We minimized breaking changes, but a major version is a major version.
pip install fastmcp -U
📖 Documentation 🚀 Upgrade from FastMCP v2 🔀 Upgrade from MCP Python SDK 📰 What's New in FastMCP 3.0
<!-- Release notes generated using configuration in .github/release.yml at main -->
fastmcp list and fastmcp call CLI commands by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3054fastmcp generate-cli command by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3065fastmcp install stdio command by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3032fastmcp discover and name-based server resolution by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3055openapi_version Check So 3.1 Is Included by @deeleeramone in https://github.com/PrefectHQ/fastmcp/pull/2768fastmcp dev to fastmcp dev inspector by @jlowin in https://github.com/PrefectHQ/fastmcp/pull/3188McpError exceptions by @ivanbelenky in https://github.com/PrefectHQ/fastmcp/pull/2656Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v3.0.0
FastMCP 3 rc3 is being released solely to ensure that the release pipeline is intact from the new repo. If successful, it will be followed immediately
FastMCP 3 rc3 is being released solely to ensure that the release pipeline is intact from the new repo. If successful, it will be followed immediately by 3.0 GA.
RC2 is a small release with a bugfix and a breaking change (that should have been in RC1): fastmcp dev is now a subcommand group, with the inspector m…
RC2 is a small release with a bugfix and a breaking change (that should have been in RC1): fastmcp dev is now a subcommand group, with the inspector moving to fastmcp dev inspector. We're planning to add new dev tools — mock servers, apps testing — that the Inspector alone can't handle, and this is the right time to claim the CLI namespace.
<!-- Release notes generated using configuration in .github/release.yml at main -->
fastmcp dev to fastmcp dev inspector by @jlowin in https://github.com/jlowin/fastmcp/pull/3188Full Changelog: https://github.com/jlowin/fastmcp/compare/v3.0.0rc1...v3.0.0rc2
🚨 Breaking Changes — The ui= parameter is now app= with a unified AppConfig class (matching the feature's actual name), and 16 FastMCP() constructor k…
FastMCP 3 RC1 means we believe the API is stable. Beta 2 drew a wave of real-world adoption — production deployments, migration reports, integration testing — and the feedback overwhelmingly confirmed that the architecture works. This release closes gaps that surfaced under load: auth flows that needed to be async, background tasks that needed reliable notification delivery, and APIs still carrying beta-era naming. If nothing unexpected surfaces, this is what 3.0.0 looks like.
🚨 Breaking Changes — The ui= parameter is now app= with a unified AppConfig class (matching the feature's actual name), and 16 FastMCP() constructor kwargs have finally been removed. If you've been ignoring months of deprecation warnings (not you, reader, I'm talking about other users), you'll get a TypeError with specific migration instructions.
🔐 Auth Improvements — Three changes that together round out FastMCP's auth story for production. auth= checks can now be async, so you can hit databases or external services during authorization — previously, passing an async function silently passed because the unawaited coroutine was truthy. Static Client Registration lets clients provide a pre-registered client_id/client_secret directly, bypassing DCR for servers that don't support it. And Azure OBO flows are now declarative via dependency injection:
from fastmcp.server.auth.providers.azure import EntraOBOToken
@mcp.tool()
async def get_emails(
graph_token: str = EntraOBOToken(["https://graph.microsoft.com/Mail.Read"]),
):
# OBO exchange already happened — just use the token
...
⚡ Concurrent Sampling — When an LLM returns multiple tool calls in a single response, context.sample() can now execute them in parallel. Opt in with tool_concurrency=0 for unlimited parallelism, or set a bound. Tools that aren't safe to parallelize can declare sequential=True.
📡 Background Task Notifications — Background tasks now reliably push progress updates and elicit user input through the standard MCP protocol. A distributed Redis queue replaces polling (7,200 round-trips/hour → one blocking call), and ctx.elicit() in background tasks automatically relays through the client's standard elicitation_handler.
✅ OpenAPI Output Validation — When backends don't conform to their own OpenAPI schemas, the MCP SDK rejects the response and the tool fails. validate_output=False disables strict schema checking while still passing structured JSON to clients — a necessary escape hatch for imperfect APIs.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v3.0.0b2...v3.0.0rc1
chore: upgrade python-multipart to 0.0.22 (CVE-2026-24486) by @jlowin in https://github.com/jlowin/fastmcp/pull/3042
FastMCP 3 Beta 2 reflects the huge number of people that have kicked the tires on Beta 1. Seven new contributors landed changes in this release, and early migration reports have gone even smoother than expected, including teams on Prefect Horizon upgrading from v2. All of which makes a strong case for moving toward a stable release. As such, most of Beta 2 is refinement: fixing what people found, filling gaps from real usage, hardening edges. But a few new features did land along the way.
🖥️ Client CLI — fastmcp list, fastmcp call, fastmcp discover, and fastmcp generate-cli turn any MCP server into something you can poke at from a terminal. Discover servers configured in Claude Desktop, Cursor, Goose, or project-level mcp.json files and reference them by name. generate-cli reads a server's schemas and writes a standalone typed CLI script where every tool is a proper subcommand with flags and help text.
🔐 CIMD (Client ID Metadata Documents) adds an alternative to Dynamic Client Registration for OAuth. Clients host a static JSON document at an HTTPS URL; that URL becomes the client_id. Server-side support includes SSRF-hardened fetching, cache-aware revalidation, and private_key_jwt validation. Enabled by default on OAuthProxy.
📱 MCP Apps — Spec-level compliance for the MCP Apps extension: ui:// resource scheme, typed UI metadata on tools and resources, extension negotiation, and ctx.client_supports_extension() for runtime detection. This is the foundation layer; FastMCP's full Apps experience is coming soon...
⏳ Background Task Context — Context now works transparently in Docket workers. ctx.elicit() routes through Redis-based coordination so background tasks can pause for user input without any code changes.
🛡️ ResponseLimitingMiddleware caps tool response sizes with UTF-8-safe truncation for text and schema-aware error handling for structured outputs.
🪿 Goose Integration — fastmcp install goose generates deeplink URLs for one-command server installation into Goose.
<!-- Release notes generated using configuration in .github/release.yml at main -->
fastmcp list and fastmcp call CLI commands by @jlowin in https://github.com/jlowin/fastmcp/pull/3054fastmcp generate-cli command by @jlowin in https://github.com/jlowin/fastmcp/pull/3065fastmcp install stdio command by @jlowin in https://github.com/jlowin/fastmcp/pull/3032fastmcp discover and name-based server resolution by @jlowin in https://github.com/jlowin/fastmcp/pull/3055Full Changelog: https://github.com/jlowin/fastmcp/compare/v3.0.0b1...v3.0.0b2
Breaking changes are minimal: for most servers, updating the import statement is all you need. See the migration guide for details.
FastMCP 3.0 rebuilds the framework around three primitives: components, providers, and transforms. Providers source components dynamically—from decorators, filesystems, OpenAPI specs, remote servers, or anywhere else. Transforms modify components as they flow to clients—renaming, namespacing, filtering, securing. The features that required specialized subsystems in v2 now compose naturally from these building blocks.
🔌 Provider Architecture unifies how components are sourced. FileSystemProvider discovers decorated functions from directories with optional hot-reload. SkillsProvider exposes agent skill files as MCP resources. OpenAPIProvider and ProxyProvider get cleaner integrations. Providers are composable—share one across servers, or attach many to one server.
🔄 Transforms add middleware for components. Namespace mounted servers, rename verbose tools, filter by version, control visibility—all without touching source code. ResourcesAsTools and PromptsAsTools expose non-tool components to tool-only clients.
📋 Component Versioning lets you register @tool(version="2.0") alongside older versions. Clients see the highest version by default but can request specific versions. VersionFilter serves different API versions from one codebase.
💾 Session-Scoped State persists across requests. await ctx.set_state() and await ctx.get_state() now survive the full session. Per-session visibility via ctx.enable_components() lets servers adapt dynamically to each client.
⚡ DX Improvements include --reload for auto-restart during development, automatic threadpool dispatch for sync functions, tool timeouts, pagination for large component lists, and OpenTelemetry tracing.
🔐 Component Authorization via @tool(auth=require_scopes("admin")) and AuthMiddleware for server-wide policies.
...and more.
Breaking changes are minimal: for most servers, updating the import statement is all you need. See the migration guide for details.
<!-- Release notes generated using configuration in .github/release.yml at main -->
openapi_version Check So 3.1 Is Included by @deeleeramone in https://github.com/jlowin/fastmcp/pull/2768McpError exceptions by @ivanbelenky in https://github.com/jlowin/fastmcp/pull/2656Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.1...v3.0.0b1
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v2.14.6...v2.14.7
Updated deprecation URL for V2 by @SrzStephen in https://github.com/PrefectHQ/fastmcp/pull/3109
PR #2861 backported dereference_refs() to v2 but never wired it into the tool schema pipeline — $ref and $defs were still sent to MCP clients. Now fixed: compress_schema() dereferences at both tool schema creation sites, so schemas are fully inlined before reaching clients.
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/PrefectHQ/fastmcp/compare/v2.14.5...v2.14.6
Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
Fixes a memory leak in the memory:// docket broker where cancelled tasks accumulated instead of being cleaned up. Bumps pydocket to ≥0.17.2.
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.4...v2.14.5
This patch release fixes a fresh install bug where the packaging library was previously installed as a transitive dependency but is no longer—causing
This patch release fixes a fresh install bug where the packaging library was previously installed as a transitive dependency but is no longer—causing an import error on fresh installs without dev dependencies. Also includes a pydocket version pin to avoid Redis connection noise in tests, plus backports from 3.x for $ref dereferencing in tool schemas and the task capabilities location fix.
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.3...v2.14.4
This patch release fixes an HTTP transport timeout bug where connections were defaulting to 5 seconds instead of respecting MCP's 30-second default, c
This patch release fixes an HTTP transport timeout bug where connections were defaulting to 5 seconds instead of respecting MCP's 30-second default, causing premature timeouts for slower operations. Also includes OAuth token storage fixes, Redis key isolation for ACL compliance, and improved ContextVar propagation for ASGI-mounted servers. Plus, the CLI will now nudge you when updates are available (you're welcome, future you).
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.2...v2.14.3
Add v3 breaking changes notice to README and docs by @jlowin in https://github.com/jlowin/fastmcp/pull/2713
FastMCP 2.14.2 brings a wave of community contributions safely into the 2.x line. A variety of important fixes backported from 3.0 work improve OpenAPI 3.1 compatibility, MCP spec compliance for output schemas and elicitation, and correct a subtle base_url fallback issue. The CLI now gently reminds you that FastMCP 3.0 is on the horizon.
<!-- Release notes generated using configuration in .github/release.yml at release/2.x -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.1...v2.14.2
Deprecate exclude_args in favor of Depends() by @jlowin in https://github.com/jlowin/fastmcp/pull/2621
FastMCP 2.14.1 adds support for sampling with tools (SEP-1577). This exciting new feature lets servers pass tools to ctx.sample(), enabling agentic workflows where the server borrows the client's LLM and controls tool execution automatically. Pass any callable as a tool and FastMCP handles the loop: calling the LLM, executing tools, and feeding results back until a final response is produced. For fine-grained control, ctx.sample_step() makes a single LLM call and returns a SampleStep, letting you inspect tool calls, add custom logic, or build your own execution loop. Structured output via result_type returns validated Pydantic models instead of raw text. This release also adds AnthropicSamplingHandler alongside the existing OpenAI handler (newly promoted out of the experimental module), so clients and servers can provide sampling capability across major providers with ease.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.14.0...v2.14.1
…for several new spec features, and removes deprecated APIs accumulated across the 2.x series.
FastMCP 2.14 begins adopting the MCP 2025-11-25 specification, headlined by protocol-native background tasks that let long-running operations report progress without blocking clients. This release also graduates the OpenAPI parser to standard, adds first-class support for several new spec features, and removes deprecated APIs accumulated across the 2.x series.
Long-running operations (like tool calls) normally block MCP clients until they complete. The new MCP background task protocol (SEP-1686) lets clients start operations, track progress, and retrieve results without blocking. For FastMCP users, taking advantage of this new functionality is as easy as adding task=True to any async decorator. Under the hood, it's powered by Docket, the enterprise task scheduler at the heart of Prefect Cloud that handles millions of concurrent tasks every day.
from fastmcp import FastMCP
from fastmcp.dependencies import Progress
mcp = FastMCP("MyServer")
@mcp.tool(task=True)
async def train_model(dataset: str, progress: Progress = Progress()) -> str:
await progress.set_total(100)
for epoch in range(100):
# ... training work ...
await progress.increment()
return "Model trained successfully"
Clients that call this tool in task-augmented mode (for FastMCP clients, that merely means another task=True!) receive a task ID immediately, poll for progress updates, and fetch results when ready. Background tasks work out-of-the-box with an in-memory backend, and users can optionally provide a Redis URL for persistence, horizontal scaling, and single-digit millisecond task pickup latency. When using Redis, users can also add additional Docket workers to scale out their task processing.
Read the docs here!
The experimental OpenAPI parser graduates to standard. The new architecture delivers improved performance through single-pass schema processing and cleaner internal abstractions. Existing code works unchanged; users of the experimental module should update their imports.
This release begins adopting the MCP 2025-11-25 specification. Beyond the core SDK updates, FastMCP adds first-class developer experiences for:
AsyncKeyValue supportAs the MCP SDK continues to adopt more of the specification, FastMCP will add corresponding high-level APIs.
This release removes deprecated APIs accumulated across the 2.x series: BearerAuthProvider, Context.get_http_request(), the dependencies parameter, legacy resource prefix formats, and several deprecated methods. The upgrade guide provides migration paths for each.
<!-- Release notes generated using configuration in .github/release.yml at main -->
from fastmcp.settings import settings by @jlowin in https://github.com/jlowin/fastmcp/pull/2581Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.13.2...v2.14.0
MCP SDK 1.23 introduced some changes related to the 11/25/25 MCP protocol update that break some patches/workarounds that FastMCP had implemented prev
MCP SDK 1.23 introduced some changes related to the 11/25/25 MCP protocol update that break some patches/workarounds that FastMCP had implemented previously. In particular, OAuth changes in the new protocol changed some implementation details that FastMCP patched; as such 1.23 is not necessarily a breaking SDK change but it is "breaking" for certain FastMCP behaviors.
As a precaution, this release pins mcp<1.23. FastMCP 2.14 will introduce 11/25/25 support (and require mcp>=1.23).
FastMCP 2.13.2 polishes the authentication stack with fixes for token refresh, scope handling, and multi-instance deployments. Discord joins the growi
FastMCP 2.13.2 polishes the authentication stack with fixes for token refresh, scope handling, and multi-instance deployments. Discord joins the growing roster of built-in OAuth providers, Azure and Google token handling gets more reliable, and proxy classes now properly forward icons and titles. This release also adds CSP customization for consent screens and fixes an edge case where $defs could mutate during tool transforms.
Welcome to 7 new contributors who made their first FastMCP contributions in this release!
<!-- Release notes generated using configuration in .github/release.yml at main -->
title attribute to ProxyTool, ProxyResource, … by @CNSeniorious000 in https://github.com/jlowin/fastmcp/pull/2497Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.13.1...v2.13.2
Security: Update authlib to 1.6.5 (CVE-2025-61920) by @ColeMurray in https://github.com/jlowin/fastmcp/pull/2347
FastMCP 2.13.1 introduces meta parameter support for ToolResult (#2283), letting tools return metadata alongside results to enable new use cases such as OpenAI's Apps SDK. It also supports client-sent meta (#2206) as well as improved OAuth capabilities and custom token verifiers (including the new DebugTokenVerifier) and an OCI authentication provider. A large list of enhancements and bugfixes round out the release.
Note that #2422 excludes MCP SDK 1.21.1 as a permitted dependency version due to a bug that fails FastMCP integration tests.
<!-- Release notes generated using configuration in .github/release.yml at main -->
logger.exception for fastmcp run/inspect by @jakekaplan in https://github.com/jlowin/fastmcp/pull/2294enhancement/support-jwt-multiple-issuers by @coderabbitai[bot] in https://github.com/jlowin/fastmcp/pull/2282Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.13.0.1...v2.13.1
This release includes two critical dependency fixes:
This release includes two critical dependency fixes:
This release includes an important bugfix for 2.13.0 that affects how the Azure OAuth provider handles scopes.
This release includes an important bugfix for 2.13.0 that affects how the Azure OAuth provider handles scopes.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.13.0...v2.13.0.1
Fix Python 3.13 websockets deprecation warning by @jlowin in https://github.com/jlowin/fastmcp/pull/1949
FastMCP 2.13.0 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
💾 Pluggable storage backends bring persistent state to FastMCP servers. Built on py-key-value-aio, a new library from FastMCP maintainer Bill Easton (@strawgate), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more! OAuth providers now automatically persist tokens across restarts, and developers can store arbitrary state without reaching for external databases. This foundation enables long-running sessions, cached credentials, and stateful applications built on MCP.
🔐 OAuth maturity brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions while providing a clean UX with customizable branding. The OAuth proxy now issues its own tokens with automatic key derivation from client secrets, and RFC 7662 token introspection support enables enterprise auth flows. Path prefix mounting enables OAuth-protected servers to integrate into existing web applications under custom paths like /api, and MCP 1.17+ compliance with RFC 9728 ensures protocol compatibility. Combined with improved error handling and platform-aware token storage, OAuth is now production-ready and security-hardened for serious applications.
FastMCP now supports out-of-the-box authentication with:
⚡ Response Caching Middleware dramatically improves performance for expensive operations. Cache tool and resource responses with configurable TTLs, reducing redundant API calls and speeding up repeated queries.
🔄 Server lifespans provide proper initialization and cleanup hooks that run once per server instance instead of per client session. This fixes a long-standing source of confusion in the MCP SDK and enables proper resource management for database connections, background tasks, and other server-level state. Note: this is a breaking behavioral change if you were using the lifespan parameter.
✨ Developer experience improvements include Pydantic input validation for better type safety, icon support for richer UX, RFC 6570 query parameters for resource templates, improved Context API methods (list_resources, list_prompts, get_prompt), and async file/directory resources.
This release includes contributions from 20 new contributors and represents the largest feature set in a while. Thank you to everyone who tested preview builds and filed issues - your feedback shaped these improvements!
<!-- Release notes generated using configuration in .github/release.yml at main -->
initialize requests in middleware by @jlowin in https://github.com/jlowin/fastmcp/pull/1546jwt_signing_key from Client Secret, default to Encrypted Disk Store by @strawgate in https://github.com/jlowin/fastmcp/pull/2223run_http_async by @tradeqvest in https://github.com/jlowin/fastmcp/pull/2071fastmcp install claude-code by @valayDave in https://github.com/jlowin/fastmcp/pull/2165Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.4...v2.13.0
Release candidate 3 for 2.13.0
Release candidate 3 for 2.13.0
Release candidate 2 for 2.13.0
Release candidate 2 for 2.13.0
Release candidate 1 for 2.13.0
Release candidate 1 for 2.13.0
This is a point release to pin the MCP SDK below 1.17, which introduced a change that is affecting some FastMCP users who 1) are using FastMCP auth pr
This is a point release to pin the MCP SDK below 1.17, which introduced a change that is affecting some FastMCP users who 1) are using FastMCP auth providers and 2) are mounting their MCP servers as part of a larger application, resulting in the .well-known payload appearing in an unexpected location.
The only change in this release is pinning the SDK version: https://github.com/jlowin/fastmcp/commit/dab2b316ddc3883b7896a86da21cacb68da01e5c <!-- Release notes generated using configuration in .github/release.yml at v2.12.5 -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.4...v2.12.5
fix: correct documentation link in deprecation warning by @strawgate in https://github.com/jlowin/fastmcp/pull/1828
FastMCP 2.12.4 adds comprehensive OIDC support and expands authentication options with AWS Cognito and Descope providers. The release also includes improvements to logging middleware, URL handling for nested resources, persistent OAuth client registration storage, and various fixes to the experimental OpenAPI parser.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.3...v2.12.4
This release adds an integration with Gemini CLI, improves the flexibility of the OAuth Proxy, and fixes some bugs with the install commands and tool
This release adds an integration with Gemini CLI, improves the flexibility of the OAuth Proxy, and fixes some bugs with the install commands and tool content generation.
<!-- Release notes generated using configuration in .github/release.yml at main -->
uv run --with fastmcp is used by install commands by @jlowin in https://github.com/jlowin/fastmcp/pull/1769Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.2...v2.12.3
This is a hotfix for a bug where the streamable-http transport was not recognized as a valid option in fastmcp.json configuration files, despite being
This is a hotfix for a bug where the streamable-http transport was not recognized as a valid option in fastmcp.json configuration files, despite being supported by the CLI. This resulted in a parsing error when the CLI arguments were merged against the configuration spec.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.1...v2.12.2
Note: this release includes a minor breaking change for users of built-in IDP integrations, with resource_server_url renamed to base_url for clarity a…
FastMCP 2.12.1 strengthens the OAuth proxy implementation based on extensive community testing and feedback. This release fixes DCR client generation, improves client token storage reliability, adds PKCE forwarding for enhanced security, introduces configurable token endpoint authentication methods, and expands scope handling; all addressing real-world integration challenges discovered since 2.12.0. The enhanced test suite with mock providers ensures these improvements are robust and maintainable.
Note: this release includes a minor breaking change for users of built-in IDP integrations, with resource_server_url renamed to base_url for clarity and consistency. This is in line with FastMCP's breaking change policy for the auth module.
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.12.0...v2.12.1
Fix breaking change: restore output_schema=False compatibility by @jlowin in https://github.com/jlowin/fastmcp/pull/1482
FastMCP 2.12 represents one of our most significant releases to date, both in scope and community involvement. After extensive testing and iteration with the community, we're shipping major improvements to authentication, configuration, and MCP feature adoption.
🔐 OAuth Proxy for Broader Provider Support addresses a fundamental challenge: while MCP requires Dynamic Client Registration (DCR), many popular OAuth providers don't support it. The new OAuth proxy bridges this gap, enabling FastMCP servers to authenticate with providers like GitHub, Google, WorkOS, and Azure through minimal configuration. These native integrations ship today, with more providers planned based on community needs.
📋 Declarative JSON Configuration introduces a standardized, portable way to describe and deploy MCP servers. The fastmcp.json configuration file becomes the single source of truth for dependencies, transport settings, entrypoints, and server metadata. This foundation sets the stage for future capabilities like transformations and remote sources, moving toward a world where MCP servers are as portable and shareable as container images.
🧠 Sampling API Fallback tackles the chicken-and-egg problem limiting adoption of advanced MCP features. Sampling—where servers request LLM completions from clients—is powerful but underutilized due to limited client support. FastMCP now lets server authors define fallback handlers that generate sampling completions server-side when clients don't support the feature, encouraging adoption while maintaining compatibility.
This release took longer than usual to ship, and for good reason: the community's aggressive testing and feedback on the authentication system helped us reach a level of stability we're confident in. There's certainly more work ahead, but these foundations position FastMCP to handle increasingly complex use cases while remaining approachable for developers.
Thank you to our new contributors and everyone who tested preview builds. Your feedback directly shaped these features.
<!-- Release notes generated using configuration in .github/release.yml at main -->
pyright to ty by @zzstoatzz in https://github.com/jlowin/fastmcp/pull/1545StdioTransport in Client.new by @strawgate in https://github.com/jlowin/fastmcp/pull/1635just error message for static checks by @jlowin in https://github.com/jlowin/fastmcp/pull/1483Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.11.3...v2.12.0
Release candidate 1 for 2.12.0
Release candidate 1 for 2.12.0
Pin mcp SDK under 2.0 to avoid breaking changes by @jlowin in https://github.com/jlowin/fastmcp/pull/1428
<!-- Release notes generated using configuration in .github/release.yml at main -->
This release includes significant enhancements to the experimental OpenAPI parser and fixes a significant bug that led schemas not to be included in input/output schemas if they were transitive dependencies (e.g. A → B → C implies A depends on C). For users naively transforming large OpenAPI specs into MCP servers, this may result in ballooning payload sizes and necessitate curation.
Full Changelog: https://github.com/jlowin/fastmcp/compare/v2.11.2...v2.11.3
One column per month.