FastMCP 是一个用于构建 MCP 服务器的 TypeScript 框架，能够处理客户端会话。它构建在官方 SDK 之上，通过提供有主张的框架来消除构建 MCP 时的复杂度：自动处理所有样板代码，为常见任务提供简单直观的 API，内置最佳实践与错误处理，让开发者专注于 MCP 的核心功能。
用途与定位 FastMCP 面向希望快速构建 MCP 服务器、而不想处理底层实现细节的开发者。官方 SDK 提供了构建 MCP 的基础模块，但把大量实现细节留给开发者，包括初始化与配置所有服务器组件、处理连接、处理工具、处理响应、处理资源、添加提示与资源及资源模板、嵌入资源与图像和音频内容块等。当需要最大控制权或特定架构要求时，应使用官方 SDK，并可参考 FastMCP 的实现以避免常见陷阱。
协议版本注意 FastMCP 实现的是旧版、基于握手的 MCP 修订（2025-11-25 及更早）。它不支持当前规范 2026-07-28，该规范使协议变为无状态——没有 initialize 握手，也没有 Mcp-Session-Id。若需要面向当前规范的框架，应使用 ViteMCP。
主要能力
- 简单定义工具、资源与提示；
- OpenAPI 转 MCP；
- 通过上下文传递头部；
- 会话 ID 与请求 ID 追踪；
- HTTP 流式传输（兼容 SSE）；
- HTTPS 支持安全连接；
- 为 REST API、webhook 和管理界面提供自定义 HTTP 路由；
- 边缘运行时支持，如 Cloudflare Workers、Deno Deploy 等；
- 用于无服务器部署的无状态模式；
- 默认启用 CORS；
- 进度通知；
- 流式输出；
- 类型化服务器事件；
- 提示参数自动补全；
- 可配置的 ping 行为；
- 健康检查端点；
- 无需绑定端口即可进行单元测试的内存传输；
- 用于测试与调试的 CLI。
使用方式 基础使用上，开发者可以定义一个可工作的 MCP 服务器，并使用终端命令进行测试。若需要用于构建自有 MCP 服务器的样板仓库，可使用 fastmcp-boilerplate。远程服务器方面，FastMCP 支持多种传输选项，使托管在远程机器上的 MCP 可通过网络访问。HTTP 流式传输在支持它的环境中比 SSE 更高效，对大负载可能有更好性能。服务器可监听 HTTP 流式连接，默认端点为 /mcp，可通过 httpStream.endpoint 自定义；同时也会启动 SSE 服务器。若要在 issuer 路径下提供 HTTP 流式传输与内置 OAuth 路由，可设置 httpStream.basePath。HTTPS 方面，通过 sslCert、sslKey 以及可选的 sslCa（用于双向 TLS 认证）提供安全连接。测试时可生成自签名证书，生产环境应从受信任的 CA（如 Let's Encrypt）获取证书。CORS 默认启用，可通过 cors 选项自定义：true、false 或包含 origin、allowedHeaders、methods、exposedHeaders、credentials、maxAge 的对象。
自定义路由与边缘运行时 FastMCP 允许在 MCP 端点之外添加自定义 HTTP 路由，使用 server.getApp() 返回的底层 Hono 应用，支持 Hono 的 HTTP 方法、路径参数、通配符、查询字符串解析、请求体辅助方法、自定义状态码与响应头、中间件和路由组。自定义 Hono 路由默认是公开的，除非添加自己的路由中间件或认证检查；受保护的自定义路由应把认证逻辑放入可复用辅助函数，并在 FastMCP 的 authenticate 选项和 Hono 路由处理器中调用。公开路由适合 OAuth 发现端点、健康检查与状态页、静态资源与文档、外部服务的 webhook 端点、无需用户认证的公开 API。边缘运行时方面，FastMCP 支持 Cloudflare Workers 等，可将 MCP 服务器部署到边缘。注意 EdgeFastMCP 的内置认证计划在未来版本提供，目前可使用 Hono 中间件；通过 /edge 子路径的 EdgeFastMCP 类部署到 Cloudflare Workers。在边缘运行时中，默认无状态、无文件系统访问、使用 V8 Isolates 快速冷启动、全球部署。
无状态模式与工具定义 FastMCP 支持 HTTP 流式传输的无状态运行，每个请求独立处理而不保持持久会话，适合无服务器环境、负载均衡部署或不需要会话状态的场景。无状态模式下服务器不追踪会话，每个请求创建临时会话并在响应后丢弃，内存占用更低、可扩展性更好。可通过 stateless: true 选项、CLI 参数或环境变量启用；注意该模式仅适用于 HTTP 流式传输，依赖持久会话的功能将不可用。/ready 健康检查端点会指示服务器是否以无状态模式运行。工具定义方面，FastMCP 使用 Standard Schema 规范定义工具参数，允许使用 Zod、ArkType、Valibot 等实现该规范的库，Valibot 需要 peer 依赖 @valibot/to-json-schema；也可直接使用已有 JSON Schema，通过 jsonSchemaAdapter 包装，需要 peer 依赖 ajv 做验证，若模式使用 format 关键字还需 ajv-formats，两者在首次调用工具时导入。JSON Schema 不携带 TypeScript 类型，execute 接收 unknown 参数，需自行断言或收窄。无参数工具可省略 parameters 属性或显式定义空参数，两者均兼容包括 Cursor 在内的所有 MCP 客户端。工具可声明 outputSchema 并返回结构化数据，FastMCP 将其暴露为 MCP structuredContent，同时返回 JSON 文本回退；提供 outputSchema 时会校验结构化输出，无效则作为工具错误返回。可通过 canAccess 函数控制已认证用户可用的工具。execute 可返回字符串、带 content 属性的对象、列表消息、图像内容等；imageContent 支持 url、path 或 buffer（三者只能指定其一），url 支持 timeoutMs。
连接健康与流式保活 FastMCP 包含可配置的 ping 机制以维护连接健康，默认针对不同传输类型优化：SSE 和 HTTP 流式连接启用，stdio 连接禁用。ping 走独立的服务器到客户端流，因此不会保持单个工具调用的连接打开；在无状态模式下该流不存在。若工具长时间运行无输出，其响应连接可能因空闲超时（如 AWS ALB 默认 60 秒）被关闭。streamKeepalive 会周期性写入进行中的工具调用自身的响应流，需显式启用：每次保活是一条 notifications/message，级别可通过 logLevel 配置（默认 debug），标记为 fastmcp-keepalive 日志器，与所服务的工具调用相关；保活在工具开始执行时启动，在请求停止等待时停止。该选项对 httpStream.enableJsonResponse 无效，因为它缓冲单个 JSON 回复；且仅覆盖工具调用，其他长时间运行的请求（resources/read、prompts/get）在完成前仍不写入内容。
