5.3_配置选项

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规范,帮助您深入理解协议的技术细节和版本演进。

使用 Hugo 构建
主题 StackJimmy 设计