错误码 502 终结指南：3 步根除 MCP 加载失败难题​​

# MCP请求示例（JSON-RPC 2.0）{  "jsonrpc": "2.0",  "method": "ip_query",  "params": {"ip": "202.96.128.86"},  "id": "req-001",  "context": {  # 会话上下文    "session_id": "user-123",    "preferences": {"language": "zh"}  }}# 响应示例{  "jsonrpc": "2.0",  "result": "上海",  "id": "req-001"}

# 使用uv替代pip（速度提升10倍）curl -LsSf https://astral.sh/uv/install.sh | shsource ~/.bashrc# 创建虚拟环境uv venv .mcp-envsource .mcp-env/bin/activate# 安装核心库uv pip install fastmcp mcp-client

mcp info# 输出服务元信息表示成功

curl -X POST http://localhost:8000/tools/list \     -H "Content-Type: application/json" \     -d '{}'

# 清理缓存并重建环境uv pip uninstall fastmcpuv cleanuv pip install --no-cache fastmcp

from fastmcp import FastMCPimport ipinfomcp = FastMCP("IPLookup")# 加载IP数据库（资源仅初始化一次）@mcp.resource("ipdb")def load_ip_database():    return ipinfo.getHandler().get_all()@mcp.tooldef ip_query(ip: str) -> dict:    """查询IP地理位置"""    ipdb = mcp.access_resource("ipdb")    return ipdb.get(ip, {"city": "未知", "country": ""})if __name__ == "__main__":    # 启动HTTP+STDIO双模服务    mcp.run(transport="both", http_port=8080)

mcp call --tool ip_query --params '{"ip":"8.8.8.8"}'# 输出：{"city":"Mountain View","country":"US"}

你是一个IP查询专家，请遵循以下规则：1. 严格校验输入是否为有效IPv4地址2. 调用`ip_query`工具获取基础数据3. 若城市为空，使用备用API：https://ipapi.co/{ip}/json/4. 输出格式："IP地址 {ip} 位于{城市},{国家}"

// 用户输入{"text": "查询202.96.128.86的位置"}// Claude生成请求{  "method": "ip_query",  "params": {"ip": "202.96.128.86"},  "context": {"session_id": "claude-123"}}// 服务响应{"result": {"city":"上海","country":"中国"}}// Claude最终回复"IP地址 202.96.128.86 位于上海,中国"

# mcp-starter/config.yamlservices:  ip_service:    command: python ip_server.py    transport: stdio    description: IP地理位置查询服务

# 构建Docker镜像docker build -t mcp/ip-service .# 运行容器docker run -d \  -p 8080:8080 \  -e MCP_LOG_LEVEL=INFO \  mcp/ip-service

// .vscode/settings.json{  "mcp.servers": [    {      "name": "IP Service",      "transport": "http",      "endpoint": "http://localhost:8080"    }  ]}

from fastmcp.cache import RedisCachemcp = FastMCP("IPService", cache=RedisCache())@mcp.tool(cache_ttl=3600)  # 结果缓存1小时def ip_query(ip: str):    ...

@mcp.tooldef handle_ticket(user_id: int, question: str):    # 步骤1：分类问题    category = classify_question(question)        # 步骤2：路由到专业工具    if category == "TECH":        return kb_mcp.search(question)    elif category == "LOCATION":        ip = get_user_ip(user_id)        return ip_query(ip)