v2.12.2: Perchance to Stream

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.

What's Changed

Fixes 🐞

• Hotfix: restore --transport streamable http at CLI by @jlowin in #1743

Docs 📚

• Update changelog for 2.12.1 by @jlowin in #1740

Full Changelog: v2.12.1...v2.12.2

v2.12.1: OAuth to Joy

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.

What's Changed

Enhancements 🔧

• Make openai depedency optional by @jlowin in #1701
• Remove orphaned OAuth proxy code by @jlowin in #1722
• Expose valid scopes from OAuthProxy metadata by @dmikusa in #1717
• OAuth proxy PKCE forwarding by @jlowin in #1733
• Add token_endpoint_auth_method parameter to OAuthProxy by @jlowin in #1736
• Clean up and enhance OAuth proxy tests with mock provider by @jlowin in #1738

Fixes 🐞

• refactor: replace auth provider registry with ImportString by @jlowin in #1710
• Fix OAuth resource URL handling and WWW-Authenticate header by @jlowin in #1706
• Fix OAuth proxy client storage and add retry logic by @jlowin in #1732

Docs 📚

• Fix documentation: use StreamableHttpTransport for headers in testing by @jlowin in #1702
• docs: add performance warnings for mounted servers and proxies by @strawgate in #1669
• Update documentation around scopes for google by @jlowin in #1703
• Add deployment information to quickstart by @seanpwlms in #1433
• Update quickstart by @jlowin in #1728
• Add development docs for FastMCP by @jlowin in #1719

Other Changes 🦾

• Set generics without bounds to default=Any by @strawgate in #1648

New Contributors

• @AaronPowell96 made their first contribution in #1714
• @seanpwlms made their first contribution in #1433
• @dmikusa made their first contribution in #1717

Full Changelog: v2.12.0...v2.12.1

v2.12.0: Auth to the Races

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.

What's Changed

New Features 🎉

• Add OAuth proxy that allows authentication with social IDPs without DCR support by @jlowin in #1434
• feat: introduce declarative JSON configuration system by @jlowin in #1517
• ✨ Fallback to a Completions API when Sampling is not available by @strawgate in #1145
• Implement typed source system for FastMCP declarative configuration by @jlowin in #1607

Enhancements 🔧

• Support importing custom_route endpoints when mounting servers by @jlowin in #1470
• Remove unnecessary asserts by @jlowin in #1484
• Add Claude issue triage by @jlowin in #1510
• Inline dedupe prompt by @jlowin in #1512
• Improve stdio and mcp_config clean-up by @strawgate in #1444
• involve kwargs to pass parameters on creating RichHandler for logging customization. by @itaru2622 in #1504
• Move SDK docs generation to post-merge workflow by @jlowin in #1513
• Improve label triage guidance by @jlowin in #1516
• Add code review guidelines for agents by @jlowin in #1520
• Remove trailing slash in unit tests by @jlowin in #1535
• Update OAuth callback UI branding by @jlowin in #1536
• Fix Marvin workflow to support development tools by @jlowin in #1537
• Add mounted_components_raise_on_load_error setting for debugging by @jlowin in #1534
• feat: Add --workspace flag to fastmcp install cursor by @jlowin in #1522
• switch from pyright to ty by @zzstoatzz in #1545
• feat: trigger Marvin workflow on PR body content by @jlowin in #1549
• Add WorkOS and Azure OAuth providers by @jlowin in #1550
• Adjust timeout for slow MCP Server shutdown test by @strawgate in #1561
• Update banner by @jlowin in #1567
• Added import of AuthProxy to auth init by @KaliszS in #1568
• Add configurable redirect URI validation for OAuth providers by @jlowin in #1582
• Remove invalid-argument-type ignore and fix type errors by @jlowin in #1588
• Remove generate-schema from public CLI by @jlowin in #1591
• Skip flaky windows test / mulit-client garbage collection by @jlowin in #1592
• Add setting to disable logging configuration by @isra17 in #1575
• Improve debug logging for nested Servers / Clients by @strawgate in #1604
• Add GitHub pull request template by @strawgate in #1581
• chore: Automate docs and schema updates via PRs by @jlowin in #1611
• Experiment with haiku for limited workflows by @jlowin in #1613
• feat: Improve GitHub workflow automation for schema and SDK docs by @jlowin in #1615
• Consolidate server loading logic into FileSystemSource by @jlowin in #1614
• Prevent Haiku Marvin from commenting when there are no duplicates by @jlowin in #1622
• chore: Add clarifying note to automated PR bodies by @jlowin in #1623
• feat: introduce inline snapshots by @strawgate in #1605
• Improve fastmcp.json environment configuration and project-based deployments by @jlowin in #1631
• fix: allow passing query params in OAuthProxy upstream authorization url by @danb27 in #1630
• Support multiple --with-editable flags in CLI commands by @jlowin in #1634
• feat: support comma separated oauth scopes by @jlowin in #1642
• Add allowed_client_redirect_uris to OAuth provider subclasses by @jlowin in #1662
• Consolidate CLI config parsing and prevent infinite loops by @jlowin in #1660
• Internal refactor: mcp server config by @jlowin in #1672
• Refactor Environment to support multiple runtime types by @jlowin in #1673
• Add type field to Environment base class by @jlowin in #1676

Fixes 🐞

• Fix breaking change: restore output_schema=False compatibility by @jlowin in #1482
• Fix #1506: Update tool filtering documentation from _meta to meta by @maybenotconnor in #1511
• Fix pytest warnings by @jlowin in #1559
• nest schemas under assets by @jlowin in #1593
• Skip flaky windows test by @jlowin in #1596
• ACTUALLY move schemas to fastmcp.json by @jlowin in #1597
• Fix and centralize CLI path resolution by @jlowin in #1590
• Remove client info modifications by @jlowin in #1620
• Fix $defs being discarded in input schema of transformed tool by @pldesch-chift in #1578
• Fix enum elicitation to use inline schemas for MCP compatibility by @jlowin in #1632
• Reuse session for StdioTransport in Client.new by @strawgate in #1635
• Feat: Configurable LoggingMiddleware payload serialization by @vl-kp in #1636
• Fix OAuth redirect URI validation for DCR compatibility by @jlowin in #1661
• Add default scope handling in OAuth proxy by @romanusyk in #1667
• Fix OAuth token expiry handling by @jlowin in #1671
• Add resource_server_url parameter to OAuth proxy providers by @jlowin in #1682

Breaking Changes 🛫

• Enhance inspect command with structured output and format options by @jlowin in #1481

Docs 📚

• Update changelog by @jlowin in #1453
• Update banner by @jlowin in #1472
• Update logo files by @jlowin in #1473
• Update deployment docs by @jlowin in #1486
• Update FastMCP Cloud screenshot by @jlowin in #1487
• Update authentication note in docs by @jlowin in #1488
• chore: Update installation.mdx version snippet by @thomas-te in #1496
• Update fastmcp cloud server requirements by @jlowin in http...

v2.12.0rc1

Release candidate 1 for 2.12.0

v2.11.3: API-tite for Change

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.

What's Changed

Enhancements 🔧

• Improve redirect handling to address 307's by @jlowin in #1387
• Ensure resource + template names are properly prefixed when importing/mounting by @jlowin in #1423
• fixes #1398: Add JWT claims to AccessToken by @panargirakis in #1399
• Enable Protected Resource Metadata to provide resource_name and resou… by @yannj-fr in #1371
• Pin mcp SDK under 2.0 to avoid breaking changes by @jlowin in #1428
• Clean up complexity from PR #1426 by @jlowin in #1435
• Optimize OpenAPI payload size by 46% by @jlowin in #1452
• Update static checks by @jlowin in #1448

Fixes 🐞

• Fix client-side logging bug #1394 by @chi2liu in #1397
• fix: Fix httpx_client_factory type annotation to match MCP SDK (#1402) by @chi2liu in #1405
• Fix OpenAPI allOf handling at requestBody top level (#1378) by @chi2liu in #1425
• Fix OpenAPI transitive references and performance (#1372) by @jlowin in #1426
• fix(type): lifespan is partially unknown by @ykun9 in #1389
• Ensure transformed tools generate structured content by @jlowin in #1443

Docs 📚

• docs(client/logging): reflect corrected default log level mapping by @jlowin in #1403
• Add documentation for get_access_token() dependency function by @jlowin in #1446

Other Changes 🦾

• Add comprehensive tests for utilities.components module by @chi2liu in #1395
• Consolidate agent instructions into AGENTS.md by @jlowin in #1404
• Fix performance test threshold to prevent flaky failures by @jlowin in #1406
• Update agents.md; add github instructions by @jlowin in #1410
• Add Marvin assistant by @jlowin in #1412
• Marvin: fix deprecated variable names by @jlowin in #1417
• Simplify action setup and add github tools for Marvin by @jlowin in #1419
• Update marvin workflow name by @jlowin in #1421
• Improve GitHub templates by @jlowin in #1422

New Contributors

• @panargirakis made their first contribution in #1399
• @ykun9 made their first contribution in #1389
• @yannj-fr made their first contribution in #1371

Full Changelog: v2.11.2...v2.11.3

v2.11.2: Satis-factory

What's Changed

Enhancements 🔧

• Support factory functions in fastmcp run by @jlowin in #1384
• Add async support to client_factory in FastMCPProxy (#1286) by @bianning in #1375

Fixes 🐞

• Fix server_version field in inspect manifest by @jlowin in #1383
• Fix Settings field with both default and default_factory by @jlowin in #1380

Other Changes 🦾

• Remove unused arg by @jlowin in #1382
• Add remote auth provider tests by @jlowin in #1351

New Contributors

• @bianning made their first contribution in #1375

Full Changelog: v2.11.1...v2.11.2

v2.11.1: You're Better Auth Now

What's Changed

New Features 🎉

• Introduce RemoteAuthProvider for cleaner external identity provider integration, update docs by @jlowin in #1346

Enhancements 🔧

• perf: optimize string operations in OpenAPI parameter processing by @chi2liu in #1342

Fixes 🐞

• Fix method-bound FunctionTool schemas by @strawgate in #1360
• Manually set _key after model_copy() to enable prefixing Transformed Tools by @strawgate in #1357

Docs 📚

• Docs updates by @jlowin in #1336
• Add 2.11 to changelog by @jlowin in #1337
• Update AuthKit vocab by @jlowin in #1338
• Fix typo in decorating-methods.mdx by @Ozzuke in #1344

New Contributors

• @Ozzuke made their first contribution in #1344

Full Changelog: v2.11.0...v2.11.1

v2.11.0: Auth to a Good Start

FastMCP 2.11 doubles down on what developers need most: speed and simplicity. This massive release delivers significant performance improvements and a dramatically better developer experience.

🔐 Enterprise-Ready Authentication brings comprehensive OAuth 2.1 support with WorkOS's AuthKit integration. The new AuthProvider interface leverages MCP's support for separate resource and authorization servers, handling API keys and remote authentication with Dynamic Client Registration. AuthKit integration means you can plug into existing enterprise identity systems without rebuilding your auth stack, setting the stage for plug-and-play auth that doesn't require users to become security experts overnight.

⚡ The Experimental OpenAPI Parser delivers dramatic performance improvements through single-pass schema processing and optimized memory usage. OpenAPI integrations are now significantly faster, with cleaner, more maintainable code. (Note: the experimental parser is disabled by default, set FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=1 to enable it. A message will be shown to all users on the legacy parser encouraging them to try the new one before it becomes the default.)

🧠 Context State Management finally gives you persistent state across tool calls with a simple dict interface, while enhanced meta support lets you expose rich component metadata to clients. Combined with improved type annotations, string-based argument descriptions, and UV transport support, this release makes FastMCP feel more intuitive than ever.

This release represents a TON of community contributions and sets the foundation for even more ambitious features ahead.

What's Changed

New Features 🎉

• Introduce experimental OpenAPI parser with improved performance and maintainability by @jlowin in #1209
• Add state dict to Context (#1118) by @mukulmurthy in #1160
• Expose FastMCP tags to clients via component meta dict by @jlowin in #1281
• Add _fastmcp meta namespace by @jlowin in #1290
• Add TokenVerifier protocol support alongside existing OAuthProvider authentication by @jlowin in #1297
• Add comprehensive OAuth 2.1 authentication system with WorkOS integration by @jlowin in #1327

Enhancements 🔧

• [🐶] Transform MCP Server Tools by @strawgate in #1132
• Add --python, --project, and --with-requirements options to CLI commands by @jlowin in #1190
• Support fastmcp run mcp.json by @strawgate in #1138
• Support from future import annotations by @jlowin in #1199
• Optimize OpenAPI parser performance with single-pass schema processing by @jlowin in #1214
• Log tool name on transform validation error by @strawgate in #1238
• Refactor get_http_request and context.session_id by @hopeful0 in #1242
• Support creating tool argument descriptions from string annotations by @jlowin in #1255
• feat: Add Annotations support for resources and resource templates by @chughtapan in #1260
• Add UV Transport by @strawgate in #1270
• Improve OpenAPI-to-JSONSchema conversion utilities by @jlowin in #1283
• Ensure proxy components forward meta dicts by @jlowin in #1282
• fix: server argument passing in CLI run command by @chughtapan in #1293
• Add meta support to tool transformation utilities by @jlowin in #1295
• feat: Allow Resource Metadata URL as field in OAuthProvider by @dacamposol in #1287
• Use a simple overwrite instead of a merge for meta by @jlowin in #1296
• Remove unused TimedCache by @strawgate in #1303
• refactor: standardize logging usage across OpenAPI utilities by @chi2liu in #1322
• perf: optimize OpenAPI parsing by reducing dict copy operations by @chi2liu in #1321
• Structured client-side logging by @cjermain in #1326

Fixes 🐞

• fix: preserve def reference when referenced in allOf / oneOf / anyOf by @algirdasci in #1208
• fix: add type hint to custom_route decorator by @zzstoatzz in #1210
• chore: typo by @richardkmichael in #1216
• fix: handle non-string $ref values in experimental OpenAPI parser by @jlowin in #1217
• Skip repeated type conversion and validation in proxy client elicitation handler by @chughtapan in #1222
• Ensure default fields are not marked nullable by @jlowin in #1224
• Fix stateful proxy client mixing in multi-proxies sessions by @hopeful0 in #1245
• Fix invalid async context manager usage in proxy documentation by @zzstoatzz in #1246
• fix: experimental FastMCPOpenAPI server lost headers in request when init(client with headers) by @itaru2622 in #1254
• Fix typing, add tests for tool call middleware by @jlowin in #1269
• Fix: prune hidden parameter defs by @muhammadkhalid-03 in #1257
• Fix nullable field handling in OpenAPI to JSON Schema conversion by @jlowin in #1279
• Ensure fastmcp run supports v1 servers by @jlowin in #1332

Breaking Changes 🛫

• Change server flag to --name by @jlowin in #1248

Docs 📚

• Remove unused import from FastAPI integration documentation by @mariotaddeucci in #1194
• Update fastapi docs by @jlowin in #1198
• Add docs for context state management by @jlowin in #1227
• Permit.io integration docs by @orweis in #1226
• Update docs to reflect sync tools by @jlowin in #1234
• Update changelog.mdx by @jlowin in #1235
• Update SDK docs by @jlowin in #1236
• Update --name flag documentation for Cursor/Claude by @adam-conway in #1239
• Add annotations docs by @jlowin in #1268
• Update openapi/fastapi URLs README.md by @jbn in #1278
• Add 2.11 version badge for state management by @jlowin in #1289
• Add meta parameter support to tools, resources, templates, and prompts decorators by @jlowin in #1294
• docs: update get_state and set_state references by @Maxi91f in #1306
• Add unit tests and docs for denying tool calls with middleware by @jlowin in #1333
• Remove reference to stacked decorators by @jlowin in #1334
• Eunomia authorization server can run embedded within the MCP server by @tommitt in #1317

Other Changes 🦾

• Update README.md by @jlowin in #1230
• Logcapture addition to test_server file by @Sourav-Tripathy in #1229
• Add tests for headers with both legacy and experimental openapi parser by @jlowin in #1259
• Small clean-up from MCP Tool Transform PR by @strawgate in #1267
• Add test for proxy tags visibility by @jlowin in #1302
• Add unit test for sampling with image messages by @jlowin in #1329
• Remove redundant resource_metadata_url assignment by @jlowin in #1328
• Update bug.yml by @jlowin in #1331
• Ensure validation errors are raised when masked by @jlowin in #1330

New Contributors

• @mariotaddeucci made their first contribution in #1194
• @algirdasci made their first contribution in #1208
• @chughtapan made their first contribution in #1222
• @mukulmurthy made their first contribution in #1160
• @orweis made their first contribution in #1226
• @Sourav-Tripathy made their first contribution in #1229
• @adam-conway made their first contribution in #1239
• @muhammadkhalid-03 made their first contribution in #1257
• @jbn made their first contribution in #1278
• @dacamposol made their first contr...

v2.10.6: Hymn for the Weekend

A special Saturday release with many fixes.

What's Changed

Enhancements 🔧

• Resolve #1139 -- Implement include_context argument in Context.sample by @codingjoe in #1141
• feat(settings): add log level normalization by @ka2048 in #1171
• add server name to mounted server warnings by @artificial-aidan in #1147
• Add StatefulProxyClient by @hopeful0 in #1109

Fixes 🐞

• Fix OpenAPI empty parameters by @FabrizioSandri in #1128
• Fix title field preservation in tool transformations by @jlowin in #1131
• Fix optional parameter validation in OpenAPI integration by @jlowin in #1135
• Do not silently exclude the "context" key from JSON body by @melkamar in #1153
• Fix tool output schema generation to respect Pydantic serialization aliases by @zzstoatzz in #1148
• fix: _replace_ref_with_defs; ensure ref_path is string by @itaru2622 in #1164
• Fix nesting when making OpenAPI arrays and objects optional by @melkamar in #1178
• Fix mcp-json output format to include server name by @jlowin in #1185
• Only configure logging one time by @jlowin in #1187

Docs 📚

• Update changelog.mdx by @jlowin in #1127
• Eunomia Authorization with native FastMCP's Middleware by @tommitt in #1144
• update api ref for new mdxify version by @zzstoatzz in #1182

Other Changes 🦾

• Expand empty parameter filtering and add comprehensive tests by @jlowin in #1129
• Add no-commit-to-branch hook by @zzstoatzz in #1149
• Update README.md by @jlowin in #1165
• skip on rate limit by @zzstoatzz in #1183
• Remove deprecated proxy creation by @jlowin in #1186
• Separate integration tests from unit tests in CI by @jlowin in #1188

New Contributors

• @FabrizioSandri made their first contribution in #1128
• @melkamar made their first contribution in #1153
• @codingjoe made their first contribution in #1141
• @itaru2622 made their first contribution in #1164
• @ka2048 made their first contribution in #1171
• @artificial-aidan made their first contribution in #1147

Full Changelog: v2.10.5...v2.10.6

v2.10.5: Middle Management

What's Changed

Enhancements 🔧

• Fix Claude Code CLI detection for npm global installations by @jlowin in #1106
• Fix OpenAPI parameter name collisions with location suffixing by @jlowin in #1107
• Add mirrored component support for proxy servers by @jlowin in #1105

Fixes 🐞

• Fix OpenAPI deepObject style parameter encoding by @jlowin in #1122
• xfail when github token is not set ('' or None) by @jlowin in #1123
• fix: replace oneOf with anyOf in OpenAPI output schemas by @MagnusS0 in #1119
• Fix middleware list result types by @jlowin in #1125
• Improve console width for logo by @jlowin in #1126

Docs 📚

• Improve transport + integration docs by @jlowin in #1103
• Update proxy.mdx by @coldfire-x in #1108

Other Changes 🦾

• Update github remote server tests with secret by @jlowin in #1112

New Contributors

• @coldfire-x made their first contribution in #1108
• @MagnusS0 made their first contribution in #1119

Full Changelog: v2.10.4...v2.10.5