Claude Code MCP 完整接入指南：HTTP、SSE、stdio、OAuth 和 Channels

MCP（Model Context Protocol）让 Claude Code 连接外部工具、数据库和 API。它解决的不是"让 Claude 更聪明"，而是让 Claude 不再依赖你复制粘贴上下文。

MCP 适合什么场景？#

当你发现自己频繁把这些内容粘进 Claude：

• Jira issue 描述
• Sentry 错误日志
• Statsig/Datadog 指标
• PostgreSQL 查询结果
• Figma 设计稿说明
• Slack 里的产品反馈
• GitHub issue/PR 信息

就应该考虑 MCP。

接入后，你可以直接说：

实现 JIRA ENG-4521 描述的功能，并创建 GitHub PR。

检查 Sentry 和 Statsig，看 ENG-4521 相关功能是否有异常。

从 PostgreSQL 找 10 个使用过该功能的随机用户邮箱，用于反馈访谈。

三种 MCP 服务器类型#

1. Remote HTTP（推荐）#

适合云端服务，是当前最推荐的传输方式。

claude mcp add --transport http notion https://mcp.notion.com/mcp

带认证头：

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

.mcp.json 里也可以使用 streamable-http，它是 MCP 规范里的名称，Claude Code 会识别为 HTTP。

2. Remote SSE（已不推荐）#

claude mcp add --transport sse asana https://mcp.asana.com/sse

SSE（Server-Sent Events）已经被标记为 deprecated。除非目标服务只提供 SSE，否则优先使用 HTTP。

3. Local stdio#

适合本地工具、自定义脚本、需要直接访问文件系统的服务。

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

注意选项顺序：

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

所有 Claude 的选项必须放在服务器名之前，-- 之后才是 MCP server 自己的命令和参数。

CLAUDE_PROJECT_DIR：本地 MCP 的关键变量#

Claude Code 会给 stdio MCP server 设置 CLAUDE_PROJECT_DIR，值是项目根目录。

Node 里读取：

const projectDir = process.env.CLAUDE_PROJECT_DIR

Python 里读取：

import os
project_dir = os.environ["CLAUDE_PROJECT_DIR"]

这比依赖当前工作目录更可靠，尤其是 Claude 在会话中执行 cd 后。

管理 MCP 服务器#

# 列出所有服务器
claude mcp list

# 查看单个服务器详情
claude mcp get github

# 删除服务器
claude mcp remove github

# 在 Claude Code 内查看状态和认证
/mcp

/mcp 面板会显示每个服务器的工具数量。如果某个服务器声称支持 tools capability，但工具数量为 0，面板会提示异常。

workspace 是保留名称，不要把 MCP server 命名为 workspace。

配置作用域：local / project / user#

--scope 决定 MCP 配置存储在哪里：

推荐：

• GitHub、Jira、Sentry 这类团队共享工具：project
• 个人 Notion、个人数据库：local 或 user
• 带私密 token 的配置：优先不要提交到 .mcp.json

OAuth 和认证#

远程服务器需要 OAuth 2.0 时，用 /mcp 面板完成认证。

典型流程：

1. claude mcp add --transport http service https://service.com/mcp
2. 进入 Claude Code
3. 运行 /mcp
4. 选择服务器并完成浏览器授权
5. 工具出现在可用工具列表中

动态工具更新和自动重连#

Claude Code 支持 MCP list_changed 通知：服务器动态增删工具、prompts、resources 时，Claude Code 会自动刷新能力列表，不需要重启。

HTTP/SSE 断线时会自动重连：

• 最多 5 次
• 从 1 秒开始指数退避
• 初始连接遇到 5xx、连接拒绝、超时会最多重试 3 次
• 认证失败和 404 不重试，因为需要改配置

stdio server 是本地进程，不会自动重连。

Channels：让 MCP 主动推送消息#

MCP 不只能被 Claude 调用，也可以作为 Channel 把外部事件推到会话里。

适合：

• CI 失败推送给 Claude，让它自动分析失败原因
• 监控告警推送，让 Claude 生成排障计划
• Telegram/Discord/Webhook 消息进入会话，让 Claude 处理待办

服务端需要声明 claude/channel capability，启动时用 --channels 选择启用。

Plugin 内置 MCP Server#

插件可以自带 MCP server。启用插件后，MCP server 自动启动，工具出现在 Claude Code 里。

插件根目录 .mcp.json 示例：

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

常用变量：

• ${CLAUDE_PLUGIN_ROOT}：插件安装目录
• ${CLAUDE_PLUGIN_DATA}：插件持久化数据目录
• ${CLAUDE_PROJECT_DIR}：当前项目根目录

安全提醒#

MCP server 能把外部内容带进 Claude Code，因此有 Prompt Injection 风险。尤其是能读取网页、邮件、Issue、Slack 的服务器。

建议：

1. 只连接可信 MCP server
2. 项目共享 .mcp.json 前做安全评审
3. 对能写外部系统的工具设置权限限制
4. 对外部内容保持不可信，不把网页文字当作系统指令
5. API Key 放 Secrets 或本地配置，不提交到 Git

来源：Claude Code 官方文档 - Connect Claude Code to tools via MCP | 整理：ClaudeEagle