Claude Code

MCP 工具接入

Claude Code 连接 MCP 的 HTTP、SSE、stdio、WebSocket 配置方式,作用域、信任、OAuth 与 tool search。

MCP 让 Claude Code 接入外部工具和数据源,例如浏览器、数据库、项目管理系统、设计工具和内部 API。

MCP server 会把外部内容带进上下文,也可能执行真实操作。只连接可信服务器,对写操作配合权限规则和 Hooks。

#连接方式

Transport	推荐度	适合场景	命令
HTTP	推荐	远程 SaaS、云端 MCP	`claude mcp add --transport http`
SSE	旧方案	老 MCP 服务	`claude mcp add --transport sse`
stdio	推荐	本地脚本、本机数据库、本地浏览器	`claude mcp add <name> -- <command>`
WebSocket	特殊场景	远程服务主动推事件	`claude mcp add-json`

#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"

配置文件里的 type 可以写 http 或 streamable-http。

#SSE

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

SSE 已被官方标注为旧 transport。新服务优先选 HTTP。

#本地 stdio

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

双横线 -- 很重要:它把 Claude Code 自己的参数和 server 启动命令分开。

Claude Code 会把 CLAUDE_PROJECT_DIR 注入给 stdio MCP server,server 可以用它定位项目根目录。

#WebSocket

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

WebSocket 适合需要主动推送事件的远程 server。普通请求响应型工具用 HTTP 更简单。

#作用域

Scope	加载范围	是否共享	存储位置
local	当前项目	否	`~/.claude.json` 的项目条目
project	当前项目	是	项目根 `.mcp.json`
user	所有项目	否	`~/.claude.json`

# 默认 local,只对当前项目生效
claude mcp add --transport http stripe https://mcp.stripe.com

# project,写入 .mcp.json,可提交团队共享
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# user,所有项目可用
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project scope 的 .mcp.json 会触发信任确认。克隆来的仓库不能靠自己提交的设置自动批准 MCP server,需要用户在交互会话里确认。

#管理命令

命令	作用
`claude mcp list`	列出 server、连接状态、待批准项
`claude mcp get <name>`	查看单个 server 配置
`claude mcp remove <name>`	移除 server
`claude mcp login <name>`	运行 OAuth 登录流程
`claude mcp logout <name>`	清掉 OAuth 凭据
`/mcp`	会话内查看状态、授权、诊断

远程 server 断开后,HTTP/SSE 会自动重连。stdio 是本地进程,退出后不会自动重启。

#工具名与权限

MCP 工具名形如:

mcp__<server>__<tool>

例子:

.claude/settings.json

{
  "permissions": {
    "allow": [
      "mcp__github__get_*"
    ],
    "ask": [
      "mcp__database__write_*"
    ],
    "deny": [
      "mcp__dangerous__*"
    ]
  }
}

Hook matcher 用正则匹配 MCP 工具时,记得写完整前缀:

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [{ "type": "command", "command": "./.claude/hooks/audit-mcp.sh" }]
      }
    ]
  }
}

#Tool search 与缓存

Claude Code 会尽量把 MCP 工具延迟加载,减少系统提示体积,也减少 prompt cache 被工具定义变化打断的概率。

自定义 ANTHROPIC_BASE_URL 时,官方默认会更保守:如果网关不是 first-party host,MCP tool search 可能默认关闭。Passion8 这类网关是否能开启,取决于是否完整转发 tool_reference 等请求字段。

变量	作用
`ENABLE_TOOL_SEARCH=true`	强制尝试延迟加载工具
`ENABLE_TOOL_SEARCH=auto`	工具量小则 upfront,大则延迟
`ENABLE_TOOL_SEARCH=false`	所有工具定义进入前缀

如果开启 tool search 后请求失败,说明当前 provider 或网关没有完整支持相关字段。先关回 ENABLE_TOOL_SEARCH=false,再检查网关转发能力。

#输出和超时

变量	作用
`MCP_TIMEOUT`	server 启动连接超时
`MCP_TOOL_TIMEOUT`	工具执行超时
`MAX_MCP_OUTPUT_TOKENS`	工具返回内容 token 上限
`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`	远程工具无响应闲置超时

数据库、浏览器、日志查询工具容易返回大量内容。优先让工具分页和筛选,不要只靠提高 MAX_MCP_OUTPUT_TOKENS。

#官方参考

上一页Sandbox 与 Dev Container 下一页Hooks 自动化

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.

Support Emailsupport@passion8.cc Service Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right