PrefectHQ/fastmcp

FastMCP is a Python framework for building and consuming Model Context Protocol (MCP) servers and clients, providing a comprehensive toolkit for exposing tools, resources, and prompts to AI agents. It supports advanced interaction patterns including human-in-the-loop approvals, structured form inputs, and background task execution, while offering robust authentication integrations with major identity providers. The system enables dynamic component discovery, server-side transforms for tool management, and seamless integration with interactive UIs via Prefab.

46 changes.

This period focused on the comprehensive migration to the FastMCP v2 API, replacing the legacy server implementation with a new decorator-based architecture and splitting the package into modular sub-packages. Extensive test coverage was added to validate the new SDK, authentication providers, and transport layers, while a wide array of new examples demonstrated capabilities in OAuth, background tasks, and third-party integrations.

74 changes.

This period focused on introducing the fastmcp-slim package and migrating the codebase to the MCP Python SDK v2, which involved rewriting transports, resources, and authentication modules. It also introduced a comprehensive suite of interactive UI examples using PrefabUI and added new capabilities for background tasks, dynamic component providers, and server-side transforms.

This change introduces a new example ATProto MCP server located in \examples/atproto\_mcp/src/atproto\_mcp\ that enables interaction with the Bluesky social network. The server exposes read-only resources for checking profile status, fetching the user's timeline, and retrieving notifications, alongside tools for state-modifying actions such as posting (with support for images, quotes, replies, and rich text), following users, liking and reposting posts, searching for content, and creating threaded posts. Configuration is handled via a \Settings\ class that reads environment variables for credentials and default limits.

_examples/atproto\_mcp/src/atproto\mcp · high confidence

New example projects are now available in the \examples/auth\ directory to demonstrate securing FastMCP servers with enterprise identity providers. The \examples/auth/aws\_oauth\ directory provides a complete server and client setup for AWS Cognito, including a tool to inspect user claims, while \examples/auth/authkit\ demonstrates integration with WorkOS AuthKit, featuring automatic binding of the JWT audience to the server's resource URL per RFC 8707.

_examples/auth/aws\oauth · high confidence

This change introduces a new example in the \examples/auth/auth0\_mcp\ directory that demonstrates how to protect a FastMCP server using Auth0's Auth for MCP. It includes a server implementation (\server.py\) utilizing the \Auth0MCPProvider\ for token validation, a corresponding client example (\client.py\) configured for OAuth, and setup instructions (\README.md\) for configuring the Auth0 tenant and running the integration.

(repo-wide) · high confidence

The form example application now includes a new server script that demonstrates the FormInput provider. This allows users to collect structured data via Pydantic models, specifically showcasing examples for shipping addresses and bug reports with defined fields and UI hints.

examples/apps/form · high confidence

This change introduces a new example demonstrating how to protect a FastMCP server using Hugging Face OAuth. It includes a server implementation that configures the \HuggingFaceProvider\ for authentication and exposes a \get\_user\_info\ tool to verify the authenticated user's identity, along with a corresponding client example that connects to the server using OAuth credentials.

_examples/auth/huggingface\oauth · high confidence

A new example in examples/auth/keycloak\_oauth demonstrates how to secure a FastMCP server using Keycloak OAuth. The server.py file configures a KeycloakAuthProvider to handle authentication, requiring Keycloak 26.6.0 or later with Dynamic Client Registration enabled, and exposes a tool to retrieve access token claims. The accompanying client.py shows how to connect to this protected server using OAuth authentication.

_examples/auth/keycloak\_oauth, examples/auth/scalekit\oauth · high confidence

Added a new example in the \examples/auth/oci\_oauth\ directory demonstrating how to protect a FastMCP server using Oracle OCI IAM OAuth. The entry includes a server configuration using \OCIProvider\, a corresponding OAuth client for testing, and setup instructions for registering an OCI application and configuring environment variables.

_examples/auth/oci\oauth · high confidence

Added a new example in the \examples/auth/propelauth\_oauth\ directory demonstrating how to protect a FastMCP server using PropelAuth OAuth. The server implementation (\server.py\) configures a \PropelAuthProvider\ using environment variables for the auth URL and introspection credentials, enabling authentication for tools like \echo\ and \whoami\. A corresponding client example (\client.py\) shows how to connect to the protected server, handle the OAuth flow, and call authenticated tools.

_examples/auth/propelauth\oauth · high confidence

A new example application in examples/apps/qr\_server demonstrates FastMCP's MCP Apps capabilities, including linking a tool to a ui:// resource via AppConfig, serving embedded HTML with Content-Security-Policy metadata for CDN-loaded dependencies, and returning ImageContent from a tool. The example includes the server implementation (qr\_server.py), configuration (fastmcp.json), and documentation (README.md).

_examples/apps/qr\server · high confidence

The \fastmcp-slim\ client package now includes a \sampling\ module with built-in handlers for Anthropic, OpenAI, and Google GenAI, allowing users to delegate LLM sampling requests directly from the client side. These handlers convert MCP sampling parameters (messages, tools, model preferences) into the respective provider's API formats, supporting features like tool use, image/audio content, and model selection. Users can instantiate these handlers (e.g., \AnthropicSamplingHandler\, \OpenAISamplingHandler\, \GoogleGenaiSamplingHandler\) and pass them to the \Client\ constructor to enable seamless integration with these LLM providers without requiring a separate server-side sampling implementation.

_fastmcp\slim/fastmcp/client/sampling · high confidence

The contacts example application now uses the new FastMCPApp provider, enabling a composable architecture where the UI is defined via the @app.ui() decorator and backend logic is exposed through @app.tool() functions. This change allows the model to launch the contact manager interface, which utilizes PrefabUI components to display, search, and save contacts. The app demonstrates key features such as auto-generated forms from Pydantic models, callable tool references for state updates, and toast notifications for user feedback.

examples/apps/contacts · high confidence

An example demonstrating the experimental CodeMode transform has been added to the examples/code\_mode directory. This feature collapses a tool catalog into two meta-tools—search for discovery and execute for running Python scripts server-side—allowing the LLM to chain multiple tool calls in a single round-trip to reduce context window usage. The example includes a FastMCP server applying the CodeMode transform and a client script that showcases searching for tools and executing chained operations.

_examples/code\mode · high confidence

A new example application has been added at examples/apps/file\_upload that demonstrates how to bypass the LLM context window to upload files directly to a server. The app uses the FastMCP framework with a dedicated FileUpload provider to handle file ingestion.

_examples/apps/file\upload · high confidence

An interactive map example has been added to the examples/apps/map directory. This new map\_server.py tool allows users to input addresses or place names, which are then geocoded using the OpenStreetMap Nominatim service via the httpx2 library. The results are rendered as markers on an interactive Leaflet map within a PrefabApp interface, accompanied by a data table showing the location details.

examples/apps/map · high confidence

A new quiz application example has been added to examples/apps/quiz, showcasing how to build multi-turn conversational state using FastMCP and Prefab UI. The app allows an LLM to generate quiz questions and launch a UI where users answer via multiple-choice buttons; each answer triggers a backend tool to grade the response, update the score, and manage state transitions (such as showing feedback or finishing the quiz) without requiring form submissions.

examples/apps/quiz · high confidence

Two new example applications are now available in the examples directory: a Sales Dashboard that visualizes monthly revenue trends, segment breakdowns, and recent deals using static mock data, and a System Monitor that provides a live dashboard of CPU, memory, and disk usage with auto-refresh capabilities powered by the psutil library.

_examples/apps/sales\dashboard · high confidence

New example applications have been added to demonstrate the Approval and Choice providers. The Approval app shows how to require human sign-off before an agent acts, while the Choice app demonstrates letting users pick from predefined options instead of typing. These examples serve as reference implementations for integrating these specific interaction patterns.

examples/apps/approval, examples/apps/choice · high confidence

Added an example demonstrating how to protect a FastMCP server using the Azure (Microsoft Entra) OAuth provider. The server configuration uses the AzureProvider with required scopes and tenant ID settings, while the client example shows how to authenticate and list available tools.

_examples/auth/azure\oauth · high confidence

Added a new LocalProvider class that allows users to register tools, resources, templates, and prompts via decorators or direct methods. This provider supports standalone usage and can be attached to multiple FastMCP servers, handling duplicate registration behaviors and version mixing constraints to ensure consistent component management.

_fastmcp\_slim/fastmcp/server/providers/local\provider · high confidence

FastMCP now includes an OAuth Proxy provider that acts as a transparent proxy to upstream OAuth Authorization Servers, enabling authentication with providers that do not support Dynamic Client Registration (DCR) or have restricted registration policies. The proxy implements local DCR with fixed upstream credentials, validates tokens using upstream JWKS, and maintains minimal local state for bookkeeping. It supports enhanced security features such as consent management with CSRF protection, PKCE, and support for SEP-990 ID-JAG tokens. The implementation is based on the OAuth 2.1 specification and is designed for production use with enterprise identity providers.

_fastmcp\_slim/fastmcp/server/auth/oauth\proxy · high confidence

FastMCP now includes a new middleware system that allows you to intercept and modify server requests and responses. This release adds built-in middleware for authorization (AuthMiddleware), response caching (CachingMiddleware), JSON schema dereferencing (DereferenceRefsMiddleware), error handling and retries (ErrorHandlingMiddleware, RetryMiddleware), request logging (LoggingMiddleware), connection keep-alive pings (PingMiddleware), rate limiting (RateLimitingMiddleware, SlidingWindowRateLimitingMiddleware), response size limiting (ResponseLimitingMiddleware), and request timing (TimingMiddleware, DetailedTimingMiddleware). These components are now available in the fastmcp.server.middleware package for easy integration into your server setup.

_fastmcp\slim/fastmcp/server/middleware · high confidence

The server now supports a new \Provider\ abstraction that allows tools, resources, and prompts to be discovered and loaded dynamically at runtime. This includes a base \Provider\ class for custom implementations, an \AggregateProvider\ to combine multiple sources, and built-in providers like \FileSystemProvider\ for scanning directories and \FastMCPProvider\ for wrapping other servers. This change enables flexible, modular server composition where components can be injected or updated without restarting the server.

_fastmcp\slim/fastmcp/server/providers · high confidence

The \fastmcp/experimental\ module now includes a new \code\_mode\ transform that allows tools to execute LLM-generated Python code in an isolated sandbox. This feature introduces a \MontySandboxProvider\ backed by \pydantic-monty\, which enforces default resource limits (30 seconds duration, 100 MB memory) to prevent unbounded execution. The implementation includes robust error handling that provides legible validation errors to the model, including parameter schemas and required fields, and ensures proper cancellation of sandbox tasks. This is a new capability for users who need to dynamically generate and run code within their FastMCP applications.

_fastmcp\slim/fastmcp/experimental · high confidence

Added the \fastmcp-remote\ package, a standalone CLI tool that acts as a local stdio bridge to remote MCP servers hosted over Streamable HTTP or SSE. This allows MCP clients that expect local stdio processes to connect to remote endpoints. The tool supports configuring the transport protocol (HTTP or SSE), passing custom headers for authentication (including OAuth), ignoring specific tools via glob patterns, and controlling TLS certificate verification (including disabling it or specifying a CA bundle).

_fastmcp\remote · high confidence

A new \fastmcp\slim\ package provides a lightweight, client-only installation of the FastMCP CLI. This location introduces the CLI entry points (\\\init\\.py\, \\\main\\_.py\) and a suite of commands for managing MCP servers without requiring the full server runtime. Key capabilities include server discovery from editor configs (Claude Desktop, Cursor, Gemini CLI, Goose), client-side tool invocation, and one-click installation of MCP servers into various IDEs and clients via the \fastmcp install\ subcommand group. It also adds utilities for generating standalone CLI scripts from MCP servers and handling authentication metadata (CIMD).

_fastmcp\slim/fastmcp/cli · high confidence

The \fastmcp-slim\ package now provides a standalone client installation that includes the full \Client\ implementation, transport layer, and authentication helpers (OAuth, Bearer, JWT) without requiring the server-side components. This release adds a \KeyValueResponseCacheStore\ that adapts the MCP SDK's caching protocol to any \AsyncKeyValue\ backend (such as Redis), enabling distributed response caching across fleets of clients. It also introduces \ClientGroup\ for coordinating independent connections to multiple servers, automatically namespacing tool routes, and managing their lifecycle. The client now supports modern protocol negotiation (mode="auto"), handles server elicitation requests, and exposes telemetry spans with proper attribute preservation.

_fastmcp\slim/fastmcp/client · high confidence

The fastmcp-slim package now includes a new in-process streaming ASGI transport (\StreamingASGITransport\) that allows HTTP clients to communicate with FastMCP servers without real sockets, enabling efficient in-process testing and bridging. Additionally, the utilities module adds new authentication and authorization helpers, including JWT decoding, scope-based checks (\require\_scopes\), and role-based checks (\require\_roles\) with support for provider-specific claim extraction. The module also introduces improved async utilities like a lazy \gather\ function to prevent coroutine leaks, and enhanced component metadata handling with version coercion and key generation.

_fastmcp\slim/fastmcp/utilities · high confidence

A new \fastmcp-tasks\ package provides the first complete server- and client-side implementation of the Model Context Protocol's SEP-2663 background tasks extension. Users can now install the \tasks\ extra (\fastmcp\[tasks\]\) and register \TasksExtension\ on their FastMCP server to offload long-running tool calls to a durable, poll-based backend (backed by Docket and Redis). The package includes the server-side engine, client-side transparent polling and input handling, and a dedicated out-of-process worker CLI, enabling distributed task execution that survives disconnects and server restarts.

_fastmcp\tasks · high confidence

FastMCP servers can now opt into client-side caching by setting \cache\_ttl\ and \cache\_scope\ on the \FastMCP\ constructor, which applies a uniform hint to all cacheable methods (tools, prompts, resources, etc.) via the MCP SDK v2.0.0b2+ runner. Additionally, servers can now handle argument completion requests using the \@mcp.completion\ decorator, allowing them to return candidate values for prompt or resource template arguments, with automatic truncation to 100 candidates and proper pagination hints.

_fastmcp\slim/fastmcp/server · high confidence

Added a new example in the \examples/atproto\_mcp\ directory that demonstrates a FastMCP server for interacting with the AT Protocol (Bluesky). This example provides a unified API with resources for reading profile status, timelines, and notifications, alongside tools for posting (including rich text, images, quotes, and replies), creating threads, searching, and social actions like following and liking. It includes a \fastmcp.json\ configuration file, a demo script, and comprehensive documentation.

_examples/atproto\mcp · high confidence

Added an example demonstrating the recommended way to configure FastMCP servers using a \fastmcp.json\ file. This example shows how to declare dependencies (such as \pyautogui\ and \Pillow\) and environment settings in the configuration file instead of passing them directly to the \FastMCP\ constructor, highlighting benefits like environment isolation and IDE support.

_examples/fastmcp\_config\demo · high confidence

Added example files in the examples/fastmcp\_config directory that illustrate how to configure a FastMCP server using a fastmcp.json file. These examples cover basic setups with source paths and stdio transport, full configurations including Python version, dependencies, and HTTP transport settings, and environment variable interpolation for deployment parameters.

_examples/fastmcp\config · high confidence

The \examples/testing\_demo\ area now includes a complete example demonstrating how to test FastMCP servers using \pytest-asyncio\. It provides a sample server (\server.py\) with tools, resources, and prompts, alongside a test suite (\tests/test\_server.py\) that showcases async fixtures, parametrized tests, and assertions using \dirty-equals\ and \inline-snapshot\. The example also includes a \README.md\ explaining the setup, including the \asyncio\_mode = "auto"\ configuration in \pyproject.toml\, and a \uv.lock\ file to manage dependencies.

_examples/testing\demo · high confidence

Three new example applications have been added to the examples directory, demonstrating the FastMCPApp framework with PrefabUI. The Approvals app showcases a multi-step workflow with tabs, status badges, and action chaining for managing request states. The Explorer app provides a data visualization interface featuring sortable tables, charts, and filtering capabilities. The Inventory app implements full CRUD operations with auto-generated forms, searchable data tables, and toast notifications. These examples illustrate how to build interactive UIs using @app.ui() entry points, backend tools, and state management via PrefabApp.

examples/apps/approvals, examples/apps/explorer, examples/apps/inventory · high confidence

Added example projects for both GitHub and Google OAuth authentication. The GitHub example demonstrates server protection using the explicit \GitHubProvider\ and client-side authentication via the \OAuth\ helper, while the Google example shows server protection with \GoogleProvider\ and client-side authentication using the string-based \auth="oauth"\ configuration. Both examples include setup instructions for creating OAuth apps, configuring environment variables, and running the server and client scripts.

_examples/auth/github\oauth · high confidence

Added a suite of runnable example applications in the examples/apps directory that demonstrate how to build interactive UIs using the Prefab UI library with FastMCP. These include a sales dashboard with bar charts, a team directory with sortable data tables and pie charts, a generative UI studio that allows LLMs to build custom Prefab UIs on the fly, a multilingual greeter, a component showcase displaying various UI elements, and an inspector demo for testing MCP message types.

examples/apps · high confidence

Added an example in examples/providers/sqlite that demonstrates how to build an MCP server with tools configured at runtime via a SQLite database. The example includes a server implementation (server.py) that queries the database on every list\_tools and call\_tool request, allowing tools to be added, modified, or disabled without restarting the server, along with a setup script (setup\_db.py) to initialize and seed the database with sample arithmetic tools.

examples/providers · high confidence

Added scripts to automate GitHub issue lifecycle management: \auto\_close\_duplicates.py\ closes issues marked with the 'potential-duplicate' label, while \auto\_close\_needs\_mre.py\ closes issues labeled 'needs MRE' after 7 days of inactivity, with logic to exempt maintainers (owners, members, collaborators) from this closure. Additionally, \benchmark\_http\_startup.py\ and \benchmark\_imports.py\ were introduced to measure and optimize FastMCP's cold-start performance and import times.

scripts · high confidence

The \fastmcp-slim\ package now includes a dedicated \fastmcp.client.auth\ module that provides authentication capabilities for client-only installations. This module introduces \BearerAuth\ for simple token-based authorization and machine-to-machine (M2M) OAuth providers (\ClientCredentialsOAuthProvider\ and \PrivateKeyJWTOAuthProvider\) that handle client credentials and private key JWT assertions without requiring a browser. These M2M providers include built-in token caching and support for scope-based step-up challenges, wrapping the underlying MCP SDK's authentication extensions to provide a consistent interface for securing FastMCP client connections.

_fastmcp\slim/fastmcp/client/auth · high confidence

The \fastmcp.contrib\ package now includes three new community-contributed modules. The \BulkToolCaller\ adds tools (\call\_tools\_bulk\, \call\_tool\_bulk\) that allow clients to execute multiple tool calls in a single request, reducing overhead. The \ComponentManager\ provides HTTP endpoints to enable or disable tools, resources, and prompts at runtime, supporting optional authentication scopes and mounted servers. The \MCPMixin\ introduces a base class and decorators (\@mcp\_tool\, \@mcp\_resource\, \@mcp\_prompt\) that allow developers to define class methods and register them with a FastMCP server using \register\_all\ or similar methods, supporting features like enabling/disabling components and passing metadata.

_fastmcp\slim/fastmcp/contrib · high confidence

This change introduces a new \fastmcp\_slim/fastmcp/server/auth/providers\ package containing dedicated OAuth/OIDC provider implementations for major identity platforms. Users can now easily secure their FastMCP servers with \Auth0Provider\ (including a new \Auth0MCPProvider\ for Auth0 Auth for MCP), \AWSCognitoProvider\ (with specific claim filtering for \client\_id\), \AzureProvider\ (handling Microsoft Entra ID scopes and authority overrides), \ClerkProvider\ (using RFC 7662 introspection), \DescopeProvider\ (supporting DCR and flexible issuer validation), \DiscordProvider\ (verifying opaque tokens via the \/oauth2/@me\ endpoint), and \GitHubProvider\. These providers standardize the configuration of client credentials, base URLs, and token verification, abstracting away the complexity of each platform's specific OAuth flow.

_fastmcp\slim/fastmcp/server/auth/providers · high confidence

Added an example in the \examples/resources\_as\_tools\ directory that shows how to use the \ResourcesAsTools\ transform to expose resources as tools. The server example defines static and templated resources, while the client example demonstrates calling the generated \list\_resources\ and \read\_resource\ tools.

_examples/resources\_as\tools · high confidence

Added a new example in \examples/skills\ that shows how to use the \SkillsDirectoryProvider\ to expose agent skills (such as PDF processing and code-review capabilities) as MCP resources. The example includes a server (\server.py\) that loads skills from a local directory, a client (\client.py\) that discovers and reads these skills, and a utility script (\download\_skills.py\) that demonstrates how to list and download skills to a local directory using the \list\_skills\ and \sync\_skills\ client utilities. This helps users understand how to integrate skill providers into their MCP servers and how clients can interact with them.

examples/skills · high confidence

Added an example in examples/prompts\_as\_tools that shows how to use the PromptsAsTools transform to expose MCP prompts as standard tools. The server-side code (server.py) defines several prompts with arguments and applies the transform to generate list\_prompts and get\_prompt tools, while the client-side code (client.py) demonstrates connecting to this server, listing available prompts, and invoking them as tools.

_examples/prompts\_as\tools · high confidence

Added a new example in \examples/auth/mounted\ that demonstrates how to host multiple OAuth-protected MCP servers (GitHub and Google) within a single application. The example uses Starlette to mount separate server instances under distinct paths (e.g., \/api/mcp/github\ and \/api/mcp/google\) and configures path-aware OAuth discovery endpoints compliant with RFC 8414, allowing each provider to have its own metadata endpoint.

examples/auth/mounted · high confidence

The \examples/filesystem-provider\ directory now includes a complete example demonstrating how to use \FileSystemProvider\ to automatically discover and register tools, resources, and prompts from the filesystem. The example features a \server.py\ that scans a \components\ directory for decorated functions, along with sample implementations for tools (calculator, greeting), resources (app config, environment-specific config, feature flags), and prompts (code review, concept explanation). This allows users to see how to structure an MCP server where components are defined by decorators rather than explicit registration code.

examples/filesystem-provider · high confidence

The \\fastmcp.apps\\ package now provides a suite of composable providers that add interactive UI capabilities to FastMCP servers. \\FastMCPApp\\ serves as the base provider for binding backend tools with UI resources, while specialized providers like \\Approval\\ (human-in-the-loop confirmation), \\Choice\\ (discrete option selection), \\FileUpload\\ (drag-and-drop file handling), \\FormInput\\ (Pydantic-backed structured forms), and \\GenerativeUI\\ (LLM-generated sandboxed UIs) enable rich, interactive user experiences. These components rely on the \\prefab-ui\\ library for rendering and support configuration via \\AppConfig\\ for visibility, Content Security Policies, and iframe permissions.

_fastmcp\slim/fastmcp/apps · high confidence

Added an example in \examples/persistent\_state\ that demonstrates session-scoped state persistence using \Context.get\_state()\ and \set\_state()\. The example includes a server (\server.py\) exposing \set\_value\, \get\_value\, and \list\_session\_info\ tools, along with HTTP (\client.py\) and STDIO (\client\_stdio.py\) clients that show how state persists across tool calls within a single session but remains isolated between different clients and sessions.

_examples/persistent\state · high confidence

The examples/tasks directory now contains a complete, runnable client/server pair demonstrating SEP-2663 background tasks. The server exposes a \slow\_computation\ tool that reports progress, while the client supports three interaction modes: transparent execution (blocking until completion), explicit handle usage (polling for status and result), and parallel execution of multiple tasks. The example defaults to an in-memory backend for zero-config testing but supports distributed workers via Redis, configurable through environment variables or a provided \.envrc\ and \docker-compose.yml\.

examples/tasks · high confidence

The \examples/search\ directory now includes a complete demo for search-based tool discovery, featuring two strategies: RegexSearchTransform for pattern-based matching and BM25SearchTransform for natural language relevance ranking. The example provides both server implementations (\server\_regex.py\, \server\_bm25.py\) and corresponding client scripts (\client\_regex.py\, \client\_bm25.py\) that illustrate how clients can use \search\_tools\ to discover specific tools from a large catalog and then execute them via \call\_tool\.

examples/search · high confidence

FastMCP introduces a new \server/transforms\ module that allows server authors to modify tools, resources, prompts, and resource templates before they are exposed to clients. This system includes a base \Transform\ class and several concrete implementations: \Namespace\ for prefixing component names, \VersionFilter\ for restricting visibility by version range, \ToolTransform\ for renaming or altering tool schemas, \PromptsAsTools\ and \ResourcesAsTools\ for exposing non-tool components as callable tools, and \BM25SearchTransform\/\RegexSearchTransform\ for replacing large tool catalogs with on-demand search interfaces.

_fastmcp\slim/fastmcp/server/transforms · high confidence

Added a suite of reusable skills under \.agents/skills/\ to standardize how agents handle repository workflows. The \code-review\ and \fix-issue\ skills provide structured guidance for reviewing changes and carrying bug fixes through to validation. The \release\ skill and its accompanying \changelog\_entry.py\ script automate the generation of release notes, insertion into changelog files, and verification of PyPI and documentation deployments. Additional skills (\python-tests\, \review-issue\, \review-pr\, \review-security-report\, \triage\) cover testing conventions, issue triage gates, PR monitoring, security report classification, and backlog selection, ensuring consistent behavior across these maintenance tasks.

.agents · high confidence

This change introduces a new skills provider subsystem in \fastmcp/server/providers/skills\ that allows FastMCP servers to automatically discover and expose local agent skills (structured as directories containing a \SKILL.md\ manifest) as MCP resources. It includes a core \SkillProvider\ for single folders and a \SkillsDirectoryProvider\ for scanning multiple roots, along with vendor-specific providers for Claude, Cursor, VS Code, Codex, Gemini, Goose, Copilot, and OpenCode that point to their respective default skill directories (e.g., \\~/.claude/skills/\). The implementation adds robust frontmatter parsing using \yaml.BaseLoader\ with a line-based fallback, handles UTF-8 BOMs, and enforces path safety via \safe\_join\ to prevent directory traversal when reading skill files.

_fastmcp\slim/fastmcp/server/providers/skills · high confidence

The smart-home example has been refreshed to use the FastMCP framework and support Hue V2 with native effects. It now includes a modular structure with a hub that mounts the lights server under the 'hue' namespace, a settings module for configuring the Hue bridge IP and credentials via environment variables, and entry points for running the example as a module or package.

_examples/smart\_home/src/smart\home · high confidence

Added three new example scripts in the \examples/versioning\ directory that demonstrate how to use the FastMCP versioning capabilities. \client\_version\_selection.py\ shows how clients can discover available tool versions via metadata and invoke specific versions. \version\_filters.py\ demonstrates using \VersionFilter\ transforms to expose distinct API surfaces (e.g., v1, v2, v3) from a shared component pool. \versioned\_components.py\ illustrates registering multiple versions of tools, resources, and prompts under the same name, where clients see the highest version by default but can request specific ones.

examples/versioning · high confidence

The FastMCP CLI now includes a new \deploy\ module that enables users to authenticate with and deploy to Prefect Horizon. This change introduces a device authorization workflow (OAuth 2.0 Device Code flow) for interactive login, secure local storage of API keys and configuration, and a typed HTTP client to communicate with the Horizon control plane. Users can now sign in via the CLI, which handles credential resolution from environment variables or local state, and the CLI provides structured terminal and JSON output for authentication status and errors.

_fastmcp\slim/fastmcp/cli/deploy · high confidence

Establishes the foundational repository structure and development standards for FastMCP. This change introduces a Code of Conduct, a Security Policy, and a comprehensive Contributing guide that defines the issue-to-PR workflow, including assignment gates and review expectations. It adds CLAUDE.md and AGENTS.md to provide detailed development guidelines for both human and AI-driven engineering agents, covering required pre-commit checks (prek, ty, ruff), release procedures, and code standards. Additionally, it configures automated dependency management via Renovate, enforces file size limits through loq, and sets up pre-commit hooks for validation, formatting, and type checking.

(repo-wide) · high confidence

Added an example demonstrating how to organize tools into namespaces (e.g., finance, admin) that are hidden by default and activated per-session. The example shows using tags to group tools, \server.disable()\ to hide them globally, and \ctx.enable\_components()\ to make them visible only for the current session, along with a \deactivate\_all\ tool to reset visibility.

_examples/namespace\activation · high confidence

The \src/fastmcp\ directory has been completely removed, deleting the legacy \FastMCPServer\ class, its associated resource and tool managers, the CLI entry point, and version metadata. This eliminates the previous server architecture and command-line interface from the product.

src/fastmcp · high confidence

The decorator logic for tools, resources, and prompts has been reorganized into separate mixin classes (ToolDecoratorMixin, ResourceDecoratorMixin, PromptDecoratorMixin) within the local provider's decorator package. This refactoring centralizes the registration and decoration behavior for these components, making the LocalProvider's internal structure more modular while preserving the existing @provider.tool, @provider.resource, and @provider.prompt functionality for users.

_fastmcp\_slim/fastmcp/server/providers/local\provider/decorators · high confidence

The server implementation in the \fastmcp\_slim\ package has been restructured by extracting core responsibilities into three new mixin classes: \LifespanMixin\ (managing server lifecycle and shared context), \MCPOperationsMixin\ (handling MCP protocol request handlers), and \TransportMixin\ (managing HTTP/stdio transport and custom routes). This change organizes the server's internal logic into modular components without altering the public API.

_fastmcp\slim/fastmcp/server/mixins · high confidence

A new rule file has been added to document the four major MCP object types (Tools, Resources, Resource Templates, and Prompts) and clarify that changes affecting interactions with one type, such as adding tags or importing, should be applied and tested across all others.

.cursor · high confidence

Cloud sessions now automatically install the GitHub CLI (gh) at startup if it is missing, ensuring tools like \gh\ are available without manual setup. Additionally, repository-specific skills (code-review, fix-issue, python-tests, release, review-issue, review-pr, review-security-report, and triage) are now linked from the local \.claude/skills\ directory to the shared \.agents/skills\ location, allowing agents to access these capabilities consistently across different environments.

.claude · high confidence

The client now exposes dedicated mixin classes (ClientPromptsMixin, ClientResourcesMixin, ClientToolsMixin) that provide methods for listing and invoking prompts, resources, and tools. These methods support automatic pagination (up to 250 pages by default) and manual cursor-based pagination, and they integrate with the modern MCP protocol's response caching and trace-context injection.

_fastmcp\slim/fastmcp/client/mixins · high confidence

The authorization handler in the server auth module has been replaced with an enhanced version that provides better user experience when clients attempt to authorize with unregistered client IDs. This change introduces content negotiation to return styled HTML error pages for browser requests and enhanced JSON responses with registration endpoint hints for API clients. The handler now includes helpful guidance for users to resolve authentication issues, such as clearing tokens and reconnecting, while maintaining OAuth 2.1 compliance by returning 400 errors for invalid client IDs.

_fastmcp\slim/fastmcp/server/auth/handlers · high confidence

The examples directory has been completely refreshed to demonstrate the new FastMCP v2 API. The legacy \FastMCPServer\ class and its methods (such as \add\_dir\_resource\, \add\_http\_resource\, and \run\_stdio\) have been replaced by the \FastMCP\ class, which uses decorators like \@mcp.tool\, \@mcp.resource\, and \@mcp.prompt\ for defining server components. This update introduces support for new features including complex Pydantic input validation, user elicitation for interactive prompts, background task handling with input requirements, and mounting sub-applications with namespaced tools and resources. Additionally, new examples demonstrate custom tool serialization, OpenTelemetry tracing integration, and in-memory proxying.

examples · high confidence

The new fastmcp-slim package provides a lightweight, client-only installation option that defers the import of server-side and CLI dependencies until they are actually used, improving startup performance for users who only need client functionality. To support the migration to MCP Python SDK v2, which renamed protocol fields from camelCase to snake\_case, the package installs runtime compatibility shims that allow legacy camelCase attribute reads (such as \inputSchema\ or \isError\) to continue working while emitting deprecation warnings; this behavior is controlled by the new \mcp\_camelcase\_compat\ setting, which can be disabled to enforce strict snake\_case usage.

_fastmcp\slim/fastmcp · high confidence

The server authentication module has been significantly restructured to enhance security and add new enterprise capabilities. This update introduces server-side identity assertion (ID-JAG) support for SEP-990, allowing corporate identity providers to assert employee identities via JWT bearer grants. It also adds Client ID Metadata Document (CIMD) support as a simpler alternative to Dynamic Client Registration. Security is strengthened with comprehensive SSRF protection for all external fetches (including JWKS and OIDC discovery), blocking of unsafe OAuth redirect schemes (javascript, data, file, vbscript), and stricter validation of redirect URIs. The token endpoint now correctly returns HTTP 401 for invalid or expired tokens per the MCP spec, and authentication middleware provides more detailed error messages to help developers troubleshoot issues. Additionally, JWT token issuance has been migrated to use the joserfc library.

_fastmcp\slim/fastmcp/server/auth · high confidence

The client transport layer has been rewritten to align with the MCP Python SDK v2, replacing the legacy \httpx\ dependency with \httpx2\ and adopting the modern sessionless Streamable HTTP transport as the default for HTTP URLs. This update introduces a \TransportOptions\ configuration to manage protocol era negotiation (legacy vs. modern), allowing multi-server configurations to automatically resolve a compatible protocol version across all backends. Additionally, the \infer\_transport\ function now prefers \pathlib.Path\ over strings for local scripts to avoid ambiguity, and proxies can now forward eligible HTTP headers to backend connections while maintaining separate transport states.

_fastmcp\slim/fastmcp/client/transports · high confidence

The \fastmcp/resources\ package has been replaced with a new implementation aligned with the MCP Python SDK v2. Resources now support richer metadata (annotations, icons, titles) and use a unified \ResourceResult\ type for responses. A key behavioral change is the introduction of \ResourceSecurity\ for templated resources, which screens URI parameters by default to reject path traversal, absolute paths, and null bytes, preventing injection attacks. The HTTP resource implementation has migrated from \httpx\ to \httpx2\.

_fastmcp\slim/fastmcp/resources · high confidence

A new OpenAPI provider implementation has been added to replace the legacy server module, introducing a stateless architecture that uses \RequestDirector\ and \openapi-core\ for zero-latency startup and robust parameter handling (including deepObject and collision resolution). The provider now requires \httpx2\ for HTTP requests, while maintaining backward compatibility with legacy \httpx\ clients via a deprecation warning. Users can customize how OpenAPI routes map to MCP components (Tools, Resources, or ResourceTemplates) using \RouteMap\ configurations and \route\_map\_fn\ callbacks.

_fastmcp\slim/fastmcp/server/providers/openapi · high confidence

The fastmcp\_slim/fastmcp/tools package introduces a new implementation for tool execution and result handling. Tool results now support an explicit error flag (is\_error) to allow tools to return error states without raising exceptions, and structured content is serialized via Pydantic with support for field-level strict validation. Output schema inference is suppressed for unconstrained sequences (e.g., bare list or Sequence) to avoid generating empty constraints, and tool titles are always emitted (derived from the name) to ensure compatibility with clients that drop tools without titles. Transformed tools now use deterministic ordering for parameters, and argument validation raises fastmcp.ValidationError for invalid inputs.

_fastmcp\slim/fastmcp/tools · high confidence

The prompts subsystem has been rewritten to align with the MCP Python SDK v2, introducing new base classes (\Message\, \PromptResult\) that handle automatic serialization of content types (strings, dicts, lists) into MCP-compatible formats. The \@prompt\ decorator now enforces stricter argument handling by rejecting functions with \\args\ or \\\*kwargs\ and extracting parameter descriptions from docstrings to populate the JSON schema. This change ensures that prompt arguments are preserved as string-compatible types and that prompt results correctly map to the new \GetPromptResult\ structure.

_fastmcp\slim/fastmcp/prompts · high confidence

The ATProto implementation module has been restructured into dedicated files for client management, posting, reading, profile, and social actions. A key behavioral change is in post creation: URLs embedded in post text are now automatically detected and converted into clickable links via facets, in addition to supporting explicit link and mention parameters. The posting API also now supports creating threaded posts, replying to specific posts, quoting posts, and attaching images. Other operations like fetching the timeline, searching posts, retrieving notifications, and social actions (follow, like, repost) have been consolidated into this new structure.

_examples/atproto\_mcp/src/atproto\_mcp/\atproto · high confidence

The OpenAPI integration utilities have been restructured into a new modular package under \fastmcp\_slim/fastmcp/utilities/openapi\, introducing a \RequestDirector\ that builds HTTP requests on-demand using \openapi-core\ to eliminate startup latency. This change migrates the underlying HTTP client from \httpx\ to \httpx2\ and implements comprehensive parameter handling, including deep-object serialization, collision resolution, and correct multipart/form-data encoding. The refactoring also includes a dedicated JSON Schema converter to properly handle OpenAPI 3.0/3.1 differences, such as nullable types and discriminator tags, ensuring robust compliance for both server and client-side OpenAPI tool/resource generation.

_fastmcp\slim/fastmcp/utilities/openapi · high confidence

The smart home example now uses the \phue2\ library to interact with the Philips Hue V2 API, replacing the previous numeric IDs with UUIDs for lights and rooms. This update introduces support for native light effects (such as candle and fire) via the \hue\_set\_light\ tool, while room-wide controls are handled by \hue\_set\_room\. The example also introduces a new \fastmcp.json\ configuration system for defining entrypoints and dependencies, adds a \README\ with setup and agent workflow instructions, and includes a \pi\_harness.py\ script for testing with the Pi agent. Existing group-based tools have been replaced by room-scoped discovery and control tools.

_examples/smart\home · high confidence

The smart home example has been refreshed to use the Philips Hue V2 API, introducing support for native light effects (such as candle flicker and fire), precise color temperature control in Kelvin, and scene activation with dynamic palettes. This change replaces the previous Hue integration with a new implementation that manages a pooled bridge connection via FastMCP's lifespan system and exposes tools for discovering rooms, lights, and scenes, as well as controlling individual lights and rooms with detailed state verification.

_examples/smart\_home/src/smart\home/lights · high confidence

Added HTTP server test suite; Added MCP conformance test suite for FastMCP; Added comprehensive test coverage for server provider implementations; Added comprehensive test coverage for the experimental CodeMode transform; Added comprehensive test coverage for tool transformation logic; Added comprehensive test suite for CLI commands and integrations; Added comprehensive test suite for MCP Apps, SDK v2 compatibility, and error handling; Added comprehensive test suite for OpenAPI provider; Added comprehensive test suite for proxy server behavior; Added comprehensive test suite for server mounting behavior; Added comprehensive test suite for server versioning; Added experimental test suite structure; Added integration tests for GitHub MCP remote and HTTP transport timeout handling; Added integration tests for GitHub and Keycloak OAuth providers; Added server-side tests for SEP-2663 background tasks; Added telemetry tests for FastMCP server tracing; Added test coverage for OAuth client authentication features; Added test coverage for server transforms; Added test suite for FastMCP utilities; Added test suite for tool argument validation, concurrency, and result handling; Added tests for Approval, Choice, FileUpload, and FormInput providers; Added tests for ClientGroup independent negotiation and context reentrancy; Added tests for FastMCP telemetry interoperability and span attributes; Added tests for Horizon CLI authentication and deployment commands; Added tests for client transport behavior and security; Added tests for client-side OpenTelemetry tracing; Added tests for contrib components; Added tests for filesystem-based component discovery and provider; Added tests for maintainer exemption in auto-close logic; Added tests for prompt rendering and standalone decorator behavior; Added tests for removed include/exclude tags parameters; Added tests for sampling handlers; Added tests for standalone decorators, future annotations, thread affinity, and tool timeouts; Added tests for the MCP SEP-2663 background task client; Added unit tests for server authentication providers; Comprehensive test coverage for server middleware; Comprehensive test suite for the FastMCP client; Expanded client test coverage for elicitation, extensions, logging, and security; Expanded server test coverage for state, auth, caching, and dependencies; Expanded test coverage for JSON Schema type conversion; Expanded test coverage for server authentication and authorization components; Tests added for removed FastMCP initialization arguments and settings access.

The FastMCP distribution is now split into multiple packages to reduce installation size and clarify dependencies. The main \fastmcp\ package now acts as a meta-package that pulls in \fastmcp-slim\ (the core client/server runtime) and optional extras like \fastmcp-remote\ (for bridging remote MCP servers) and \fastmcp-tasks\ (for background task execution). This restructuring allows users to install only the components they need, such as using \fastmcp-slim\ for lightweight client-only scenarios or adding \fastmcp-tasks\ for SEP-2663 task support, while the main package provides a unified entry point for all features.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 61.

• Code Health 82
• Architecture 87
• Maturity 71
• Readiness 48
• Security 70

• 300 commits — 252 feature/other, 48 fixes

• fastmcp_slim/fastmcp — 91 commits
• (root) — 23 commits
• docs/servers — 19 commits
• (repo) — 16 commits
• fastmcp_tasks/fastmcp_tasks — 16 commits
• .github/workflows — 14 commits
• docs/changelog.mdx — 14 commits
• docs/getting-started — 13 commits
• docs/python-sdk — 13 commits
• tests/server — 13 commits
• docs/clients — 11 commits
• docs/development — 10 commits
• tests/client — 7 commits
• tests/tasks — 7 commits
• .claude/skills — 5 commits
• docs/integrations — 4 commits
• .github/actions — 3 commits
• docs/more — 3 commits
• tests/experimental — 3 commits
• dev-docs/v4-notes — 2 commits

• fix: Audit v4 docs: fix missing version badges, fill whats-new gaps (#4668)
• fix: Baseline tools-call-sampling; fix removal leftovers flagged by ruff
• fix: Fix #5115: OAuthProxy accepts self-contained ID-JAG tokens even when iden (#5119)
• fix: Fix CodeMode tool error propagation (#4704)
• fix: Fix FAQ: sampling/roots/elicitation legacy-mode advice, SessionProvider registration (#4672)
• fix: Fix File helper extension handling (#4531)
• fix: Fix OAuth proxy override typing (#4612)
• fix: Fix OpenAPI allOf reference fields (#4653)
• fix: Fix OpenAPI query explode defaults (#5065)
• fix: Fix StatefulProxyClient reconnection after session failure (#4829)
• fix: Fix broken Docket links in task docs
• fix: Fix double slash in issuer_url well-known log hint
• fix: Fix flaky stdio crash-recovery tests: assert eventual recovery (#4594)
• fix: Fix multipart string-array default encoding (#5121)
• fix: Fix partial hint resolution on Python 3.14 (#4796)
• fix: Fix percent-encoded skill file names unreadable in resources mode (#4590)
• fix: Fix proxy forwarding of MCP transport headers (#4853)
• fix: Fix response cache partitioning for versioned components (#4948)
• fix: Fix self-referential connection error causes (#4720)
• fix: Fix skill frontmatter with UTF-8 BOM (#4533)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

PrefectHQ/fastmcp was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.