快速手搓一个MCP服务指南（二）：FastMCP Servers概述

一、FastMCP 服务器概述

FastMCP 服务器是构建 MCP（工具调用协议）应用的核心组件，负责管理工具、资源、提示等组件，并处理与客户端的通信。其本质是一个容器，将功能组件抽象为可被 LLM 调用的接口，同时屏蔽底层通信细节。

二、服务器创建与初始化

1. 基础实例化

from fastmcp import FastMCP

# 创建基础服务器
mcp = FastMCP(name="MyAssistantServer")

# 创建带说明的服务器（帮助客户端理解功能）
mcp_with_instructions = FastMCP(
    name="HelpfulAssistant",
    instructions="""
    此服务器提供数据分析工具，调用 get_average() 分析数值数据。
    """
)

2. 构造函数参数详解

参数名	类型	默认值	说明
name	str	“FastMCP”	服务器可读名称，用于日志和客户端识别
instructions	`str	None`	None
lifespan	AsyncContextManager	None	服务器生命周期管理（启动/关闭逻辑）
tags	set[str]	None	服务器标签，用于全局过滤
tools	list[Tool]	None	预注册工具列表，替代@mcp.tool装饰器
include_tags	set[str]	None	仅暴露包含指定标签的组件
exclude_tags	set[str]	None	隐藏包含指定标签的组件

三、服务器核心组件

FastMCP 服务器支持四种核心组件，均通过装饰器注册：

1. 工具（Tools）

可被客户端调用的功能函数，用于执行具体操作：

@mcp.tool
def multiply(a: float, b: float) -> float:
    """两数相乘"""
    return a * b

2. 资源（Resources）

暴露可读取的数据源，无参数：

@mcp.resource("data://config")
def get_config() -> dict:
    """获取应用配置"""
    return {"theme": "dark", "version": "1.0"}

3. 资源模板（Resource Templates）

带参数的动态资源，URI 中的变量会作为参数传入：

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """根据ID获取用户资料"""
    return {"id": user_id, "name": f"User {user_id}"}

4. 提示（Prompts）

LLM 提示模板，可复用并传入参数：

@mcp.prompt
def analyze_data(data_points: list[float]) -> str:
    """生成数据分析提示"""
    return f"分析这些数据点：{', '.join(str(p) for p in data_points)}"

四、标签过滤系统（2.8.0+ 新特性）

通过标签精确控制组件暴露范围，支持组合过滤：

1. 组件标签定义

@mcp.tool(tags={"public", "utility"})
def public_tool():
    """公开工具"""
    return "Public tool"

@mcp.tool(tags={"internal", "admin"})
def admin_tool():
    """管理员工具"""
    return "Admin only"

2. 服务器过滤配置

# 仅暴露带"public"标签的组件
mcp = FastMCP(include_tags={"public"})

# 隐藏带"internal"或"deprecated"标签的组件
mcp = FastMCP(exclude_tags={"internal", "deprecated"})

# 组合过滤：仅暴露"admin"标签且非"deprecated"的组件
mcp = FastMCP(include_tags={"admin"}, exclude_tags={"deprecated"})

3. 过滤优先级

• exclude_tags 优先级高于 include_tags
• 组件自身 enabled=False 可强制隐藏（优先级最高）

五、服务器运行与传输协议

1. 启动服务器（STDIO 传输，默认）

# my_server.py
from fastmcp import FastMCP

mcp = FastMCP(name="MyServer")

@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()  # 启动服务器，默认使用STDIO
    # 可选HTTP传输：mcp.run(transport="http", host="127.0.0.1", port=9000)

2. 支持的传输协议

• STDIO：本地文本协议（默认，适用于本地工具）
• Streamable HTTP：流式HTTP（推荐Web服务）
• SSE：服务器发送事件（旧版，已弃用）

3. CLI 运行方式

# 运行服务器（自动识别mcp对象）
fastmcp run my_server.py

# 指定服务器对象
fastmcp run my_server.py:mcp

六、服务器组合与代理

1. 组合多个服务器（2.2.0+ 新特性）

from fastmcp import FastMCP

main = FastMCP(name="Main")
sub = FastMCP(name="Sub")

@sub.tool
def hello():
    return "hi"

# 方式1：静态导入
main.import_server(sub)

# 方式2：动态挂载（带前缀）
main.mount(sub, prefix="sub")

2. 服务器代理（2.0.0+ 新特性）

from fastmcp import FastMCP, Client

# 代理远程SSE服务器
backend = Client("http://example.com/mcp/sse")
proxy = FastMCP.as_proxy(backend, name="ProxyServer")

# 本地访问远程工具
result = await proxy.call_tool("remote_tool", {"param": "value"})

七、服务器配置详解

1. 构造时配置

mcp = FastMCP(
    name="ConfiguredServer",
    dependencies=["requests", "pandas>=2.0.0"],  # 服务器依赖
    include_tags={"public", "api"},            # 暴露标签
    exclude_tags={"internal"},                # 隐藏标签
    on_duplicate_tools="replace",             # 重复工具处理策略
    on_duplicate_resources="warn",
)

2. 全局设置（环境变量/.env文件）

import fastmcp

# 查看全局设置
print(fastmcp.settings.log_level)        # 日志级别
print(fastmcp.settings.mask_error_details)  # 错误详情屏蔽

# 环境变量配置
export FASTMCP_LOG_LEVEL=DEBUG
export FASTMCP_MASK_ERROR_DETAILS=True

3. 传输特定配置

# 运行时指定HTTP传输配置
mcp.run(
    transport="http",
    host="0.0.0.0",  # 绑定所有接口
    port=9000,       # 自定义端口
    log_level="DEBUG"  # 覆盖全局日志级别
)

八、自定义工具序列化（2.2.7+ 新特性）

默认使用JSON序列化工具返回值，可自定义格式（如YAML）：

import yaml
from fastmcp import FastMCP

# 自定义YAML序列化函数
def yaml_serializer(data):
    return yaml.dump(data, sort_keys=False)

# 创建带自定义序列化的服务器
mcp = FastMCP(name="MyServer", tool_serializer=yaml_serializer)

@mcp.tool
def get_config():
    """返回YAML格式配置"""
    return {"api_key": "abc123", "debug": True}

九、核心概念总结

模块	功能描述
FastMCP 类	服务器核心容器，管理组件注册与客户端通信
组件装饰器	@mcp.tool/@mcp.resource 等用于注册可调用功能
标签过滤	通过include_tags/exclude_tags控制组件暴露范围
传输协议	STDIO（本地）、HTTP（网络）等多种通信方式
服务器组合	import_server/mount支持模块化应用开发
自定义序列化	支持非JSON格式的工具返回值处理

十、实践建议

1. 开发阶段：使用STDIO传输+标签过滤快速迭代功能
2. 生产环境：采用HTTP传输+自定义序列化（如YAML）提升可读性
3. 大型应用：通过服务器组合拆分模块，使用代理整合远程服务
4. 安全控制：结合exclude_tags与组件enabled状态实现细粒度权限管理

通过上述功能，FastMCP 服务器提供了从开发到生产的完整解决方案，尤其适合构建与LLM交互的工具型应用系统。