fastmcp-server

FastMCP 3.0 服务端开发

使用 FastMCP 3.0 构建可用于生产环境的 MCP（模型上下文协议）服务的完整参考。FastMCP 是一款快速、符合 Python 风格的框架，可将大模型连接到工具和数据。

何时使用此技能

在以下情况下使用 FastMCP 服务端：

• 在 Python 中创建新的 MCP 服务
• 向 MCP 服务添加工具、资源或提示词
• 实现身份验证（OAuth、OIDC、令牌验证）
• 设置用于日志记录、速率限制或授权的中间件
• 配置提供程序（本地、文件系统、技能、自定义）
• 构建具有遥测和存储功能的生产级 MCP 服务
• 从 FastMCP 2.x 升级到 3.0

涵盖的重点领域：

• 工具与资源（核心）：装饰器、验证、返回类型、模板
• 上下文与依赖注入（核心）：MCP 上下文、依赖注入、后台任务
• 身份验证（安全）：OAuth、OIDC、令牌验证、代理模式
• 授权（安全）：基于作用域和基于角色的访问控制
• 中间件（高级）：请求／响应管道、内置中间件
• 提供程序（高级）：本地、文件系统、技能和自定义提供程序
• 功能（高级）：分页、采样、存储、OpenTelemetry、版本控制

快速参考

核心模式

创建包含工具的服务：

from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

创建资源：

@mcp.resource("data://config")
def get_config() -> dict:
    """Return server configuration"""
    return {"version": "1.0", "debug": False}

创建资源模板：

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> dict:
    """Get a user's profile by ID"""
    return fetch_user(user_id)

创建提示词：

@mcp.prompt
def review_code(code: str, language: str = "python") -> str:
    """Review code for best practices"""
    return f"Review this {language} code:\n\n{code}"

运行服务：

if __name__ == "__main__":
    mcp.run()

# Or with transport options:
# mcp.run(transport="sse", host="0.0.0.0", port=8000)

在工具中使用上下文

from fastmcp import FastMCP, Context

mcp = FastMCP("MyServer")

@mcp.tool
def process_data(uri: str, ctx: Context) -> str:
    """Process data with logging and progress"""
    ctx.info(f"Processing {uri}")
    ctx.report_progress(0, 100)
    data = ctx.read_resource(uri)
    ctx.report_progress(100, 100)
    return f"Processed: {data}"

身份验证设置

from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider

auth = BearerAuthProvider(
    jwks_uri="https://your-provider/.well-known/jwks.json",
    audience="your-api",
    issuer="https://your-provider/"
)

mcp = FastMCP("SecureServer", auth=auth)

核心概念

工具

作为可执行能力提供给大模型的函数。使用 @mcp.tool 装饰。支持 Pydantic 验证、异步、自定义返回类型和注解（readOnlyHint、destructiveHint）。

资源与模板

由 URI 标识的静态或动态数据源。资源使用固定 URI（data://config），模板使用参数化 URI（users://{id}/profile）。支持 MIME 类型、注解和通配符参数。

上下文

Context 对象提供在工具／资源中访问 MCP 功能的能力：日志记录、进度报告、资源访问、大模型采样、用户信息征询和会话状态。

依赖注入

使用 Depends() 将值注入工具／资源函数。支持 HTTP 请求、访问令牌、自定义依赖项，以及基于生成器的清理模式。

提供程序

控制组件的来源。LocalProvider（默认，基于装饰器）、FileSystemProvider（从磁盘上的 Python 文件加载）、SkillsProvider（打包的捆绑包）或自定义提供程序。

身份验证与授权

支持多种身份验证模式：令牌验证（JWT、JWKS）、OAuth 代理、OIDC 代理、远程 OAuth 和完整的 OAuth 服务端。通过组件上的作用域和中间件实现授权。

中间件

拦截并修改请求／响应。内置中间件支持速率限制、错误处理、日志记录和响应大小限制。可通过 @mcp.middleware 使用自定义中间件。

使用参考文档

详细文档按主题整理在 references/ 文件夹中：

入门

• getting-started/installation.md - 安装 FastMCP、可选依赖项、验证设置
• getting-started/upgrade-guide.md - 从 FastMCP 2.x 迁移到 3.0
• getting-started/quickstart.md - 首个服务、工具、资源、提示词、运行

服务端

• server/server-class.md - FastMCP 服务配置、传输选项、标签筛选
• server/tools.md - 工具装饰器、参数、验证、返回类型、注解
• server/resources-and-templates.md - 资源、模板、URI、通配符、MIME 类型

上下文

• context/mcp-context.md - 上下文对象、日志记录、进度、资源访问、采样
• context/background-tasks.md - 使用任务支持处理长时间运行的操作
• context/dependency-injection.md - Depends()、自定义依赖项、HTTP 请求、访问令牌
• context/user-elicitation.md - 在执行过程中向用户请求结构化输入

功能

• features/icons.md - 为工具、资源、提示词和服务自定义图标
• features/lifespans.md - 服务生命周期管理以及启动/关闭钩子
• features/client-logging.md - 向 MCP 客户端发送日志消息
• features/middleware.md - 请求/响应管道、内置和自定义中间件
• features/pagination.md - 对大型组件列表进行分页
• features/progress-reporting.md - 报告长时间运行操作的进度
• features/sampling.md - 向客户端请求大模型补全
• features/storage-backends.md - 用于缓存和令牌的内存、文件和 Redis 存储
• features/opentelemetry.md - 分布式追踪与可观测性
• features/versioning.md - 为组件设置版本，并按版本范围筛选

身份验证

• authentication/token-verification.md - JWT、JWKS、内省、静态密钥、自定义验证
• authentication/remote-oauth.md - 将身份验证委托给上游 OAuth 提供商
• authentication/oauth-proxy.md - 支持 PKCE 和客户端管理的完整 OAuth 代理
• authentication/oidc-proxy.md - 支持自动发现的 OpenID Connect 代理
• authentication/full-oauth-server.md - 完整的内置 OAuth 服务

授权

• authorization.md - 基于作用域的访问控制、中间件授权、模式

提供方

• providers/local.md - 默认提供方，基于装饰器注册组件
• providers/filesystem.md - 从磁盘上的 Python 文件加载组件
• providers/skills.md - 打包并分发组件包
• providers/custom.md - 为任意组件来源构建自定义提供方

版本历史

v1.0.0（2026 年 2 月）

• 首次发布，涵盖 FastMCP 3.0（候选发布版）
• 7 个类别共 30 个参考文件
• 完整涵盖工具、资源、上下文、身份验证、提供方和功能