前置阅读:MCP 协议概览 了解 Resources / Tools / Prompts / Sampling 四大原语,以及 MCP Server 开发 了解 Server 如何暴露能力。
1. MCP Client 接入全景
┌──────────────────────────────────────┐
│ MCP Client 类型 │
├──────────────────────────────────────┤
│ 原生应用 │ Claude Desktop │
├──────────────────────────────────────┤
│ IDE 插件 │ Cline (VSCode) │
│ │ Continue (VSCode/JetBrains)│
├──────────────────────────────────────┤
│ 代码库 │ 自建 Python/Node Agent │
├──────────────────────────────────────┤
│ CLI 工具 │ Claude Code / mcp-cli │
└──────────────────────────────────────┘
2. Claude Desktop 配置详解
2.1 配置文件位置
| 操作系统 | 路径 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
2.2 配置模板
{
"mcpServers": {
"filesystem": {
"command": "python3",
"args": ["/Users/alex/mcp-servers/fs_mcp.py", "/Users/alex/workspace"]
},
"sqlite": {
"command": "python3",
"args": ["/Users/alex/mcp-servers/sqlite_mcp.py", "/Users/alex/data.db"]
},
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-github-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxx"
}
}
}
}
2.3 验证连接
- 保存配置文件
- 完全退出 Claude Desktop(Cmd+Q / Alt+F4)
- 重新启动
- 点击左侧工具栏的 🔧 图标,查看已连接的 Server
2.4 故障排查
| 症状 | 原因 | 解决方案 |
|---|---|---|
| 🔧 图标不显示 | 配置格式错误 | 用 jsonlint.com 验证 JSON |
command not found | PATH 问题 | 使用绝对路径或用 which 查找 |
| Server 显示「红色」 | Server 进程启动失败 | 查看 Claude Desktop 日志 |
| 工具调用了但没返回 | Server 处理超时 | 检查 Server 的日志输出 |
日志路径:
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# 查看所有 MCP 相关日志
tail -f ~/Library/Logs/Claude/*.log | grep -i mcp
3. Cline(VSCode 插件)配置
Cline 是基于 VSCode 的 AI 编码助手,原生支持 MCP。
3.1 安装
- VSCode 扩展商店搜索 “Cline”
- 或
code --install-extension saoudrizwan.claude-dev
3.2 配置 MCP Server
打开命令面板(Cmd+Shift+P)→ Cline: MCP Server Settings
{
"mcpServers": {
"filesystem": {
"command": "python3",
"args": ["${workspaceFolder}/mcp/fs_mcp.py", "${workspaceFolder}"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-postgres-server"],
"env": {
"DATABASE_URL": "postgresql://localhost:5432/mydb"
}
}
}
}
3.3 在对话中使用
在 Cline 聊天中直接描述需求,Agent 会自动调用 MCP 工具:
User: 查看项目根目录下有哪些文件
Cline: [调用 filesystem/list_dir] → 返回文件列表
User: 帮我读取 README.md
Cline: [调用 filesystem/read_file] → 返回内容
4. Continue(开源 IDE 插件)配置
Continue 是功能类似 Cline 的开源替代,支持 VSCode 和 JetBrains。
4.1 安装
# VSCode
code --install-extension Continue.continue
# JetBrains
Settings → Plugins → Marketplace → 搜索 "Continue"
4.2 配置 MCP
// ~/.continue/config.json
{
"mcpServers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "python3",
"args": ["/path/to/fs_mcp.py", "/path/to/workspace"]
},
{
"name": "github-search",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-github-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
]
}
4.3 故障排查
Continue 的 MCP 调试工具更友好:
- 打开 Continue 侧边栏 → ⚙️ 设置 → MCP Servers
- 实时查看 Server 连接状态、工具列表、最近调用记录
5. 自建 Python Agent 接入 MCP
如果需要在自己的应用程中集成 MCP,使用官方 SDK:
pip install mcp
5.1 基础客户端
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio
async def main():
# 配置 Server 启动参数
server_params = StdioServerParameters(
command="python3",
args=["./fs_mcp.py", "./workspace"],
env=None,
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# 初始化
await session.initialize()
# 发现可用工具
tools = await session.list_tools()
print("可用工具:")
for tool in tools.tools:
print(f" - {tool.name}: {tool.description}")
# 调用工具
result = await session.call_tool(
"read_file",
arguments={"path": "README.md"},
)
print(f"\n文件内容:\n{result.content}")
asyncio.run(main())
5.2 多 Server 聚合
class MultiMCPClient:
def __init__(self):
self.sessions = {}
async def connect(self, name: str, params: StdioServerParameters):
read, write = await stdio_client(params).__aenter__()
session = ClientSession(read, write)
await session.initialize()
self.sessions[name] = session
async def list_all_tools(self):
all_tools = []
for name, session in self.sessions.items():
tools = await session.list_tools()
for tool in tools.tools:
# 前缀命名空间避免冲突
tool.name = f"{name}:{tool.name}"
all_tools.append(tool)
return all_tools
async def call_tool(self, namespaced_name: str, arguments: dict):
server_name, tool_name = namespaced_name.split(":", 1)
session = self.sessions[server_name]
return await session.call_tool(tool_name, arguments)
6. 跨客户端兼容性矩阵
| MCP Server 功能 | Claude Desktop | Cline | Continue | 自建 Agent |
|---|---|---|---|---|
| Tools (list/call) | ✅ | ✅ | ✅ | ✅ |
| Resources (list/read) | ✅ | ⚠️ 部分 | ⚠️ 部分 | ✅ |
| Prompts (list/get) | ✅ | ❌ | ❌ | ✅ |
| Sampling | ✅ | ❌ | ❌ | ✅ |
| stdio 传输 | ✅ | ✅ | ✅ | ✅ |
| SSE 传输 | ✅ | ⚠️ 实验 | ⚠️ 实验 | ✅ |
| WebSocket | ❌ | ❌ | ❌ | ✅ |
7. 安全最佳实践
每个 MCP Server 的权限策略
├── 文件系统 → 只读写指定目录(chroot)
├── 数据库 → 只读账号,禁止 DROP/DELETE
├── API 调用 → 最小 Scope OAuth Token
├── 代码执行 → 沙箱环境(Docker/WASM)
└── 网络访问 → 仅限白名单域名
8. 常见问题速查
Q: Claude Desktop 修改配置后需要重启吗?
A: 必须完全退出(不是最小化窗口),然后重新启动才能加载新配置。
Q: 如何在 VSCode 中同时使用多个 MCP Server?
A: Cline 和 Continue 都支持在配置文件的 mcpServers 中注册多个 Server。它们会自动聚合所有可用工具并在需要时选择最合适的。
Q: MCP 和 VSCode 的 GitHub Copilot 扩展冲突吗?
A: 不冲突。Copilot 和 MCP 是不同层次的功能。Copilot 提供代码补全,MCP 提供工具调用,两者可以并存。
Q: 自建 Agent 中 MCP 调用失败怎么调试?
A: 1) 先用 stdio_client 直接连接测试;2) 检查 Server 的 stderr 输出;3) 验证 JSON-RPC 消息格式;4) 使用 Wireshark 或 tcpdump 抓包(SSE 模式)。
📂 相关阅读:
- MCP 协议概览 — 四大原语
- MCP Server 开发实战 — SQLite/文件系统/GitHub Server 实现
- MCP 工具生态速查 — 20+ 官方/社区 Server 清单
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。