5.3 配置选项
本章详细介绍MCP服务器和客户端的配置选项,帮助您根据特定需求优化和自定义MCP应用。合理的配置可以提高性能、增强安全性,并改善用户体验。
目录
服务器配置参数
基本配置
创建MCP服务器时,可以通过FastMCP构造函数设置基本配置:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP(
name="My MCP Server", # 服务器名称
description="服务器描述", # 服务器描述
version="1.0.0", # 服务器版本
verbose=True, # 是否启用详细日志
base_path="/api/mcp" # API基本路径(用于HTTP传输)
)
基本配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name |
str |
必填 | 服务器的名称,将在服务器发现中显示 |
description |
str |
None |
服务器的描述,提供关于服务器功能的额外信息 |
version |
str |
"0.1.0" |
服务器的版本号,遵循语义化版本规范 |
verbose |
bool |
False |
是否启用详细日志输出 |
base_path |
str |
"/mcp" |
用于HTTP/WebSocket传输的基础URL路径 |
传输层配置
MCP支持多种传输方式,每种方式都有其特定的配置参数:
Stdio传输配置
if __name__ == "__main__":
mcp.run(
transport="stdio",
buffer_size=4096 # 缓冲区大小(字节)
)
SSE传输配置
if __name__ == "__main__":
mcp.run(
transport="sse",
host="0.0.0.0", # 监听地址
port=8000, # 监听端口
cors_origins=["*"], # CORS允许的源
ssl_cert="cert.pem", # SSL证书路径(可选)
ssl_key="key.pem" # SSL密钥路径(可选)
)
WebSocket传输配置
if __name__ == "__main__":
mcp.run(
transport="websocket",
host="0.0.0.0", # 监听地址
port=8000, # 监听端口
cors_origins=["*"], # CORS允许的源
ssl_cert="cert.pem", # SSL证书路径(可选)
ssl_key="key.pem", # SSL密钥路径(可选)
ping_interval=20 # 心跳间隔(秒)
)
HTTP传输配置
if __name__ == "__main__":
mcp.run(
transport="http",
host="0.0.0.0", # 监听地址
port=8000, # 监听端口
cors_origins=["*"], # CORS允许的源
ssl_cert="cert.pem", # SSL证书路径(可选)
ssl_key="key.pem" # SSL密钥路径(可选)
)
传输层配置参数详解
| 参数 | 适用传输 | 类型 | 默认值 | 描述 |
|---|---|---|---|---|
transport |
所有 | str |
"stdio" |
传输方式: "stdio", "sse", "websocket", "http" |
host |
sse, websocket, http | str |
"127.0.0.1" |
服务器监听地址 |
port |
sse, websocket, http | int |
8000 |
服务器监听端口 |
cors_origins |
sse, websocket, http | List[str] |
["*"] |
允许的CORS源 |
ssl_cert |
sse, websocket, http | str |
None |
SSL证书路径 |
ssl_key |
sse, websocket, http | str |
None |
SSL密钥路径 |
buffer_size |
stdio | int |
4096 |
读写缓冲区大小(字节) |
ping_interval |
websocket | int |
20 |
WebSocket心跳间隔(秒) |
资源配置
资源可以在注册时配置各种选项:
@mcp.resource("data://cached/{id}", cache_ttl=300)
def get_cached_data(id: str) -> dict:
"""获取缓存的数据"""
# 实现...
资源配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
cache_ttl |
int |
0 |
资源缓存的生存时间(秒),0表示不缓存 |
max_age |
int |
0 |
HTTP响应的max-age缓存控制头(秒) |
content_type |
str |
自动检测 | 资源的内容类型 |
auth_required |
bool |
False |
是否需要身份验证才能访问 |
工具配置
工具也可以配置特定选项:
@mcp.tool(timeout=30, rate_limit=10)
async def process_data(data: dict) -> dict:
"""处理数据"""
# 实现...
工具配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name |
str |
函数名 | 工具的名称 |
description |
str |
函数文档 | 工具的描述 |
timeout |
int |
10 |
工具执行的最大超时时间(秒) |
rate_limit |
int |
0 |
每分钟允许的最大调用次数,0表示无限制 |
auth_required |
bool |
False |
是否需要身份验证才能调用 |
安全配置
MCP服务器可以配置安全相关的选项:
from mcp.server.fastmcp import FastMCP, Auth
# 定义认证回调
def authenticate(token: str) -> bool:
return token == "secret-token"
mcp = FastMCP(
name="Secure MCP Server",
auth=Auth(
enabled=True,
authenticate=authenticate,
token_header="X-API-Token"
)
)
安全配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
auth.enabled |
bool |
False |
是否启用身份验证 |
auth.authenticate |
Callable |
None |
验证回调函数 |
auth.token_header |
str |
"Authorization" |
用于传递令牌的HTTP头 |
auth.token_query_param |
str |
"token" |
用于传递令牌的查询参数 |
auth.token_cookie |
str |
"mcp_token" |
用于传递令牌的cookie名称 |
性能调优
性能调优配置可以帮助优化MCP服务器的资源使用和响应时间:
mcp = FastMCP(
name="High Performance Server",
worker_threads=16, # 工作线程数
max_connection_queue=100, # 最大连接队列
resource_cache_size=1024, # 资源缓存大小
response_compression=True # 启用响应压缩
)
性能配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
worker_threads |
int |
系统CPU数 | 工作线程池大小 |
max_connection_queue |
int |
100 |
等待处理的最大连接数 |
resource_cache_size |
int |
1000 |
资源缓存的最大条目数 |
response_compression |
bool |
False |
是否启用响应压缩 |
max_request_size |
int |
1048576 (1MB) |
最大请求大小(字节) |
客户端配置参数
连接配置
客户端连接配置控制与MCP服务器的连接行为:
from mcp import ClientSession, ClientConfig
from mcp.client.sse import sse_client
async def run():
config = ClientConfig(
connect_timeout=5.0, # 连接超时(秒)
request_timeout=30.0, # 请求超时(秒)
max_redirects=5 # 最大重定向次数
)
async with sse_client(
"http://localhost:8000/mcp",
headers={"User-Agent": "MCP Client/1.0"}
) as (read, write):
async with ClientSession(read, write, config=config) as session:
# 使用会话...
连接配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
connect_timeout |
float |
10.0 |
连接超时时间(秒) |
headers |
Dict[str, str] |
{} |
连接请求头 |
ssl_verify |
bool |
True |
是否验证SSL证书 |
max_redirects |
int |
10 |
最大重定向次数 |
proxy |
str |
None |
代理服务器URL |
会话配置
会话配置控制ClientSession的行为:
config = ClientConfig(
auto_reconnect=True, # 自动重连
reconnect_attempts=3, # 重连尝试次数
reconnect_delay=1.0, # 重连延迟(秒)
session_ttl=3600 # 会话生存时间(秒)
)
会话配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
auto_reconnect |
bool |
True |
连接断开时是否自动重连 |
reconnect_attempts |
int |
3 |
最大重连尝试次数 |
reconnect_delay |
float |
1.0 |
重连尝试之间的延迟(秒) |
session_ttl |
int |
3600 |
会话最大生存时间(秒) |
session_id |
str |
自动生成 | 自定义会话ID |
错误处理配置
错误处理配置控制客户端如何响应各种错误情况:
config = ClientConfig(
retry_on_error=True, # 错误时重试
max_retries=3, # 最大重试次数
retry_delay=0.5, # 重试延迟(秒)
exponential_backoff=True # 指数退避
)
错误处理配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
retry_on_error |
bool |
False |
是否在可重试的错误上自动重试 |
max_retries |
int |
3 |
最大重试次数 |
retry_delay |
float |
1.0 |
重试之间的基础延迟(秒) |
exponential_backoff |
bool |
True |
是否使用指数退避策略 |
retry_status_codes |
List[int] |
[429, 500, 502, 503, 504] |
触发重试的HTTP状态码 |
超时配置
超时配置控制各种操作的超时行为:
config = ClientConfig(
request_timeout=30.0, # 请求超时(秒)
tool_timeout=60.0, # 工具调用超时(秒)
resource_timeout=15.0, # 资源读取超时(秒)
prompt_timeout=5.0 # 提示渲染超时(秒)
)
超时配置参数详解
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
request_timeout |
float |
30.0 |
一般请求超时(秒) |
tool_timeout |
float |
60.0 |
工具调用超时(秒) |
resource_timeout |
float |
30.0 |
资源读取超时(秒) |
prompt_timeout |
float |
10.0 |
提示渲染超时(秒) |
initialization_timeout |
float |
10.0 |
初始化超时(秒) |
环境变量
MCP支持通过环境变量配置服务器和客户端行为,这对于在不同环境(开发、测试、生产)之间切换配置特别有用。
服务器环境变量
| 环境变量 | 描述 | 默认值 |
|---|---|---|
MCP_SERVER_PORT |
服务器监听端口 | 8000 |
MCP_SERVER_HOST |
服务器监听地址 | 127.0.0.1 |
MCP_SERVER_TRANSPORT |
传输方式 | stdio |
MCP_SERVER_VERBOSE |
是否启用详细日志 | false |
MCP_SERVER_BASE_PATH |
API基本路径 | /mcp |
MCP_SERVER_SSL_CERT |
SSL证书路径 | - |
MCP_SERVER_SSL_KEY |
SSL密钥路径 | - |
MCP_SERVER_WORKER_THREADS |
工作线程数 | 系统CPU数 |
MCP_SERVER_MAX_REQUEST_SIZE |
最大请求大小(字节) | 1048576 |
MCP_SERVER_AUTH_ENABLED |
是否启用身份验证 | false |
客户端环境变量
| 环境变量 | 描述 | 默认值 |
|---|---|---|
MCP_CLIENT_SERVER_URL |
服务器URL | - |
MCP_CLIENT_CONNECT_TIMEOUT |
连接超时(秒) | 10.0 |
MCP_CLIENT_REQUEST_TIMEOUT |
请求超时(秒) | 30.0 |
MCP_CLIENT_SSL_VERIFY |
是否验证SSL证书 | true |
MCP_CLIENT_AUTO_RECONNECT |
是否自动重连 | true |
MCP_CLIENT_RETRY_ON_ERROR |
是否在错误时重试 | false |
MCP_CLIENT_MAX_RETRIES |
最大重试次数 | 3 |
MCP_CLIENT_PROXY |
代理服务器URL | - |
通用环境变量
| 环境变量 | 描述 | 默认值 |
|---|---|---|
MCP_LOG_LEVEL |
日志级别 | info |
MCP_LOG_FILE |
日志文件路径 | - |
MCP_DEBUG |
是否启用调试模式 | false |
MCP_AUTH_TOKEN |
认证令牌 | - |
使用环境变量的示例:
# 为服务器设置环境变量
export MCP_SERVER_PORT=9000
export MCP_SERVER_TRANSPORT=sse
export MCP_SERVER_VERBOSE=true
# 启动服务器
python my_server.py
# 为客户端设置环境变量
export MCP_CLIENT_SERVER_URL=http://localhost:9000/mcp
export MCP_CLIENT_REQUEST_TIMEOUT=60.0
export MCP_AUTH_TOKEN=my-secret-token
# 运行客户端
python my_client.py
配置最佳实践
以下是MCP配置的一些最佳实践:
1. 使用配置文件
对于复杂的应用,建议使用配置文件来管理设置:
import json
import os
def load_config(config_path="config.json"):
# 首先使用默认配置
config = {
"server": {
"port": 8000,
"host": "127.0.0.1",
"transport": "sse",
"worker_threads": 4
},
"security": {
"auth_enabled": False,
"ssl_enabled": False
}
}
# 从文件加载配置
if os.path.exists(config_path):
with open(config_path, "r") as f:
file_config = json.load(f)
# 递归更新配置
def update_config(target, source):
for key, value in source.items():
if key in target and isinstance(target[key], dict) and isinstance(value, dict):
update_config(target[key], value)
else:
target[key] = value
update_config(config, file_config)
# 环境变量覆盖配置
if os.environ.get("MCP_SERVER_PORT"):
config["server"]["port"] = int(os.environ["MCP_SERVER_PORT"])
return config
# 使用配置
config = load_config()
mcp = FastMCP(
name="Configured Server",
verbose=config["server"].get("verbose", False)
)
if __name__ == "__main__":
mcp.run(
transport=config["server"]["transport"],
host=config["server"]["host"],
port=config["server"]["port"],
worker_threads=config["server"]["worker_threads"]
)
2. 针对不同环境的配置
创建针对不同环境的配置文件:
/config
├── default.json # 默认配置
├── development.json # 开发环境
├── testing.json # 测试环境
└── production.json # 生产环境
然后根据环境加载相应的配置:
import os
# 获取当前环境
env = os.environ.get("MCP_ENV", "development")
# 加载配置
config = load_config(f"config/{env}.json")
3. 安全性配置
生产环境下的安全配置最佳实践:
# 生产环境下的配置
if env == "production":
# 启用SSL
mcp.run(
transport="sse",
host="0.0.0.0",
port=443,
ssl_cert="/path/to/cert.pem",
ssl_key="/path/to/key.pem"
)
# 启用身份验证
mcp = FastMCP(
name="Production Server",
auth=Auth(
enabled=True,
authenticate=lambda token: validate_token_securely(token),
token_header="X-API-Token"
)
)
4. 性能优化配置
高流量场景下的性能优化配置:
# 高性能服务器配置
mcp = FastMCP(
name="High Performance Server",
worker_threads=os.cpu_count() * 2, # CPU核心数的两倍
resource_cache_size=10000, # 大资源缓存
response_compression=True # 启用压缩
)
# 配置资源缓存
@mcp.resource("data://frequently-accessed/{id}", cache_ttl=3600)
def get_frequent_data(id: str) -> dict:
"""获取频繁访问的数据,缓存1小时"""
# 实现...
5. 监控和日志配置
生产环境中的监控和日志配置:
import logging
from logging.handlers import RotatingFileHandler
# 配置日志
log_handler = RotatingFileHandler(
'mcp_server.log', # 日志文件
maxBytes=10*1024*1024, # 10MB
backupCount=5 # 保留5个备份
)
logging.basicConfig(
level=logging.INFO if env == "production" else logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[log_handler]
)
# 在服务器中使用
mcp = FastMCP(
name="Monitored Server",
verbose=env != "production" # 仅在非生产环境启用详细日志
)
@mcp.on_initialize
async def on_server_start(ctx):
ctx.logger.info(f"服务器已启动,环境: {env}")
@mcp.on_shutdown
async def on_server_stop(ctx):
ctx.logger.info("服务器已关闭")
小结
本章详细介绍了MCP服务器和客户端的配置选项,包括基本配置、传输层配置、资源和工具配置、安全配置、性能调优等方面。通过合理配置,可以使MCP应用在不同场景下发挥最佳性能,同时满足安全性和可维护性的要求。
适当的配置是构建稳健MCP应用的重要环节。根据应用的具体需求和运行环境,灵活调整配置参数,可以显著提升应用的质量和用户体验。
下一章将介绍MCP规范,帮助您深入理解协议的技术细节和版本演进。