J'Blog

26 课 · 进阶

语义检索

基于 Chroma 向量库,与 Workspace 知识库分离。用自然语言描述你想查的内容。 非管理员每人每天可检索 5 次(消耗站点 AI 配额)。

连接 MCP 服务器

原文:Connect to MCP servers

一句话

为 Claude Code 添加 MCP 服务器,验证连接,并在磁盘上找到配置文件。

什么时候翻这页

  1. 需要为 Claude Code 添加新的工具或服务扩展功能
  2. MCP 服务器连接失败需要排查问题
  3. 需要在团队中共享 MCP 服务器配置
  4. 想了解 MCP 服务器的配置文件位置和作用域

核心概念

  • MCP (Model Context Protocol):模型上下文协议,让 Claude Code 能够使用内置工具集之外的工具
  • MCP 服务器:提供额外工具的服务,可以是本地进程或托管服务,如搜索问题跟踪器、查询数据库或控制浏览器
  • 作用域(scope):服务器的配置范围,分为三种:
    • local:仅当前项目可用,默认作用域
    • project:项目级配置,可共享给团队成员
    • user:用户级配置,在所有项目中可用
  • 传输方式(transport):服务器连接方式,常见有:
    • http:通过 URL 连接的托管服务
    • stdio:作为本地子进程运行的服务器

怎么做

添加和验证服务器

  1. 添加服务器

    claude mcp add --transport http <name> <url>
    
    • <name>:自定义的服务器名称
    • <url>:服务器托管地址
  2. 检查连接状态

    claude mcp list
    

    状态指示含义:

    • ✓ Connected:已连接,可使用
    • ! Needs authentication:需要认证
    • ✗ Failed to connect:服务器未响应
    • ✗ Connection error:连接错误
    • ⏸ Pending approval:等待项目级服务器批准
  3. 使用服务器 在 Claude 会话中指定服务器名称:

    Use the <name> server to [执行任务]
    
  4. 移除服务器

    claude mcp remove <name>
    

添加不同类型的服务器

  1. 本地服务器

    claude mcp add <name> -- <command>
    
    • 使用 -- 分隔符,后面是要执行的命令
  2. 需要认证的服务器

    • 添加服务器后,使用 /mcp 命令
    • 选择服务器并选择 Authenticate
    • 在浏览器中完成认证

直接编辑配置文件

在项目根目录创建 .mcp.json

{
  "mcpServers": {
    "<name>": {
      "type": "http",
      "url": "<url>"
    }
  }
}

命令 / 配置速查

命令/配置说明
claude mcp add --transport http <name> <url>添加 HTTP 服务器
claude mcp add <name> -- <command>添加本地 stdio 服务器
claude mcp list列出服务器及其状态
claude mcp remove <name>移除服务器
claude mcp get <name>查看服务器配置详情
.mcp.json项目级配置文件
~/.claude.json用户级配置文件
MCP_TIMEOUT环境变量,设置服务器启动超时时间(毫秒)

初学者易错点

  1. claude 会话内运行 claude mcp add 命令(应在会话外运行)
  2. 添加本地服务器时忘记使用 -- 分隔符
  3. 混淆不同作用域(local、project、user)的适用场景
  4. 修改 .mcp.json 后未重启 Claude Code 会话
  5. 忽略服务器认证需求导致连接失败

相关词条

  • mcp:MCP 协议概述
  • managed-mcp:组织级 MCP 管理
  • mcp-resources:MCP 资源引用
  • mcp-prompts:MCP 提示命令
  • env-vars:环境变量配置

官方原文:https://code.claude.com/docs/en/mcp-quickstart