mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-27 15:51:33 +02:00
07d89c4038* Consolidate tool transformation logic into TransformingProvider
Tool transformations were previously scattered across LocalProvider,
ProxyProvider, and MCPConfig. This consolidates all transformation
logic into TransformingProvider via with_transforms(tool_transforms={...}).
- Add tool_transforms parameter to TransformingProvider
- Add tool_transforms to Provider.with_transforms()
- Remove transformation storage from LocalProvider and ProxyProvider
- Remove add_tool_transformation() and remove_tool_transformation() from FastMCP
- Add tool_transforms parameter to factory methods (from_openapi, from_fastapi, create_proxy)
- Update tests to use new patterns
* Fix: reject tool lookups by pre-transform name
* Add collision validation for tool_transforms and fix docstring examples
- Validate duplicate target names in tool_transforms raise ValueError
- Fix docstring examples to use arguments/ArgTransformConfig (not args/ArgTransform)
- Add test for collision validation
* Add server-level tool transform APIs and fix task registration
- Add AggregateProvider to present multiple providers as one
- Add _get_root_provider() to apply server-level transforms uniformly
- Fix _docket_lifespan to use root provider (ensures renamed tools
register with correct keys for background execution)
- Add tool_transforms kwarg to __init__ (non-deprecated)
- Add add_tool_transform(), remove_tool_transform(), tool_transforms property
- Deprecate old API names (tool_transformations, add_tool_transformation, etc.)
- Update tests to use new API
* Add graceful degradation for provider errors in AggregateProvider
* Match original behavior: parallel queries with DEBUG logging
* Refactor transforms to middleware-style call_next pattern
Replaces the ad-hoc transformation system with a unified Transform
abstraction using the same call_next pattern as server middleware.
Key changes:
- New src/fastmcp/server/transforms/ module with Transform base class
- Namespace, ToolTransform, Visibility all implement the same interface
- Transforms compose via functools.partial chain building
- Visibility is now just the first transform in provider._transforms
- Server-level transforms apply after provider aggregation
- Task registration now applies full transform chain
Removes TransformingProvider, _BoundTransform, ComponentSource protocol.
User-facing API unchanged: mount(), add_transform(), enable/disable all
work as before.
* Add comprehensive transforms and visibility documentation
New docs/servers/providers/transforms.mdx covering:
- Mental model for middleware-style transform pattern
- Built-in transforms (Namespace, ToolTransform)
- Server vs provider-level transforms and ordering
- Tool modification (immediate vs deferred)
- Custom transform creation
New docs/servers/visibility.mdx covering:
- Enable/disable API for runtime visibility control
- Keys and tags for targeting components
- Allowlist mode with only=True
- Server vs provider visibility layering
Updates existing docs to reference new pages and simplifies
redundant content. Visibility is documented as a user feature,
not as an implementation detail.
* Restructure transforms docs and delete tool-transformation pattern
* Cleanup: simplify get_tasks and remove unused Provider.get_component
* Update loq
* Update loq limits and add loq note to AGENTS.md
* Deprecate add_tool_transformation and tool_transformations param
* Address PR review feedback: remove redundant imports, fix path reference
* Add missing imports to code examples in v3-features.mdx
80 lines
4.6 KiB
Text
80 lines
4.6 KiB
Text
---
|
|
title: Providers
|
|
sidebarTitle: Overview
|
|
description: How FastMCP sources tools, resources, and prompts
|
|
icon: layer-group
|
|
---
|
|
|
|
import { VersionBadge } from '/snippets/version-badge.mdx'
|
|
|
|
<VersionBadge version="3.0.0" />
|
|
|
|
Every FastMCP server has one or more component providers. A provider is a source of tools, resources, and prompts - it's what makes components available to clients.
|
|
|
|
## What Is a Provider?
|
|
|
|
When a client connects to your server and asks "what tools do you have?", FastMCP asks each provider that question and combines the results. When a client calls a specific tool, FastMCP finds which provider has it and delegates the call.
|
|
|
|
You're already using providers. When you write `@mcp.tool`, you're adding a tool to your server's `LocalProvider` - the default provider that stores components you define directly in code. You just don't have to think about it for simple servers.
|
|
|
|
Providers become important when your components come from multiple sources: another FastMCP server to include, a remote MCP server to proxy, or a database where tools are defined dynamically. Each source gets its own provider, and FastMCP queries them all seamlessly.
|
|
|
|
## Why Providers?
|
|
|
|
The provider abstraction solves a common problem: as servers grow, you need to organize components across multiple sources without tangling everything together.
|
|
|
|
**Composition**: Break a large server into focused modules. A "weather" server and a "calendar" server can each be developed independently, then mounted into a main server. Each mounted server becomes a `FastMCPProvider`.
|
|
|
|
**Proxying**: Expose a remote MCP server through your local server. Maybe you're bridging transports (remote HTTP to local stdio) or aggregating multiple backends. Remote connections become `ProxyProvider` instances.
|
|
|
|
**Dynamic sources**: Load tools from a database, generate them from an OpenAPI spec, or create them based on user permissions. Custom providers let components come from anywhere.
|
|
|
|
## Built-in Providers
|
|
|
|
FastMCP includes providers for common patterns:
|
|
|
|
| Provider | What it does | How you use it |
|
|
|----------|--------------|----------------|
|
|
| `LocalProvider` | Stores components you define in code | `@mcp.tool`, `mcp.add_tool()` |
|
|
| `FastMCPProvider` | Wraps another FastMCP server | `mcp.mount(server)` |
|
|
| `ProxyProvider` | Connects to remote MCP servers | `create_proxy(client)` |
|
|
|
|
Most users only interact with `LocalProvider` (through decorators) and occasionally mount or proxy other servers. The provider abstraction stays invisible until you need it.
|
|
|
|
## Transforms
|
|
|
|
[Transforms](/servers/providers/transforms) modify components as they flow from providers to clients. Each transform sits in a chain, intercepting queries and modifying results before passing them along.
|
|
|
|
| Transform | Purpose |
|
|
|-----------|---------|
|
|
| `Namespace` | Prefixes names to avoid conflicts |
|
|
| `ToolTransform` | Modifies tool schemas (rename, description, arguments) |
|
|
|
|
The most common use is namespacing mounted servers to prevent name collisions. When you call `mount(server, namespace="api")`, FastMCP creates a `Namespace` transform automatically.
|
|
|
|
Transforms can be added to individual providers (affecting just that source) or to the server itself (affecting all components). See [Transforms](/servers/providers/transforms) for the full picture.
|
|
|
|
## Provider Order
|
|
|
|
When a client requests a tool, FastMCP queries providers in registration order. The first provider that has the tool handles the request.
|
|
|
|
`LocalProvider` is always first, so your decorator-defined tools take precedence. Additional providers are queried in the order you added them. This means if two providers have a tool with the same name, the first one wins.
|
|
|
|
## When to Care About Providers
|
|
|
|
**You can ignore providers entirely** if you're building a simple server with decorators. Just use `@mcp.tool`, `@mcp.resource`, and `@mcp.prompt` - FastMCP handles the rest.
|
|
|
|
**Learn about providers when** you want to:
|
|
- [Mount another server](/servers/providers/mounting) into yours
|
|
- [Proxy a remote server](/servers/providers/proxy) through yours
|
|
- [Control visibility](/servers/visibility) of components
|
|
- [Build dynamic sources](/servers/providers/custom) like database-backed tools
|
|
|
|
## Next Steps
|
|
|
|
- [Local](/servers/providers/local) - How decorators work
|
|
- [Mounting](/servers/providers/mounting) - Compose servers together
|
|
- [Proxying](/servers/providers/proxy) - Connect to remote servers
|
|
- [Transforms](/servers/providers/transforms) - Namespace, rename, and modify components
|
|
- [Visibility](/servers/visibility) - Control which components clients can see
|
|
- [Custom](/servers/providers/custom) - Build your own providers
|