记录一次完整的Model Context Protocol实验，从本地STDIO到远程API调用的全流程踩坑与解决方案。
测试目标
构建一个Hello Claude MCP服务器，支持基础工具调用，并测试本地和远程集成方案。
实验环境
- Python 3.10+
- MCP SDK 1.13.0
- Claude Desktop 0.12.112
- fastmcp包（第三方）
第一步：本地STDIO实现
基础搭建
使用官方mcp包快速搭建：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-claude")
@mcp.tool()
def say_hello(name: str = "Claude") -> str:
current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
return f"你好 {name}! 🎉 当前时间是 {current_time}"
if __name__ == "__main__":
mcp.run() # 默认STDIO模式
配置Claude Desktop：
{
"mcpServers": {
"hello-claude": {
"command": "python",
"args": ["path/to/hello_claude_mcp.py"]
}
}
}
结果： ✅ 成功。Claude Desktop能正常调用工具。
第二步：远程HTTP部署
第一个坑：官方包限制
尝试添加host和port参数：
# ❌ 报错：FastMCP.run() got an unexpected keyword argument 'port'
mcp.run(transport="sse", host="0.0.0.0", port=8000)
原因： 官方mcp包的run()方法不支持host和port参数。
解决方案：切换到fastmcp包
pip uninstall mcp -y
pip install fastmcp
from fastmcp import FastMCP # 改用第三方包
mcp = FastMCP("hello-claude")
if __name__ == "__main__":
# ✅ 支持host和port参数
mcp.run(transport="sse", host="0.0.0.0", port=8000)
配置FRP内网穿透：
- 本地端口：8000
- 公网地址：xxx:8001
- SSE端点：
http://xxx:8001/sse
结果： ✅ 服务器成功运行，端点可访问。
第三步：API集成测试
尝试Claude API调用
headers = {
"X-API-Key": API_KEY,
"anthropic-beta": "mcp-client-2025-04-04" # 启用MCP
}
payload = {
"model": "claude-sonnet-4-20250514",
"messages": [{"role": "user", "content": "向我说声你好"}],
"mcp_servers": [
{
"type": "url",
"url": "http://xxx:8001/sse",
"name": "hello-claude-mcp"
}
]
}
第二个坑：第三方API不支持MCP
使用api.gptsapi.net测试，Claude响应的是通用回答，没有调用自定义MCP工具。
对比测试：
- Claude Desktop：✅ 正确调用工具，返回个性化时间戳
- 第三方API：❌ 忽略MCP配置，使用内置知识
结论： 第三方API代理可能不支持最新的MCP功能。
第四步：Claude Desktop远程集成
第三个坑：mcp-remote安全限制
配置远程MCP服务器：
{
"mcpServers": {
"hello-claude-remote": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://xxx:8001/sse"]
}
}
}
报错：
Error: Non-HTTPS URLs are only allowed for localhost or when --allow-http flag is provided
解决方案：添加安全标志
{
"mcpServers": {
"hello-claude-remote": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"http://xxx:8001/sse",
"--allow-http" // 关键参数
]
}
}
}
结果： ✅ 成功连接远程MCP服务器。
第五步：连接机制发现
第四个坑：重启服务器导致连接错误
实验： 在Claude Desktop运行期间关闭并重启MCP服务器。
现象：
MCP error -32602: Invalid request parameters
原因分析：
- Claude Desktop在启动时建立MCP连接
- 运行期间不会自动重连
- 服务器重启后是新实例，旧连接已失效
- 客户端仍使用断开的连接状态
核心发现：MCP连接机制
启动阶段：Claude Desktop → 读取配置 → 建立连接
运行阶段：复用已建立连接，无自动重连
故障场景：服务器重启 → 必须重启Claude Desktop
解决方案： 重启Claude Desktop重新建立连接。
技术总结
包选择建议
| 需求 | 推荐包 | 原因 |
|---|---|---|
| 本地开发 | 官方mcp |
稳定可靠 |
| 远程部署 | 第三方fastmcp |
支持host/port参数 |
部署架构
本地开发：Python脚本 ←→ Claude Desktop (STDIO)
远程部署：Python服务器 ←→ FRP穿透 ←→ Claude Desktop (SSE + mcp-remote)
API集成：需要官方Claude API支持
测试完成时间：2025年8月
MCP版本：1.13.0
Claude Desktop版本：0.12.112
评论区