# Claude Code MCP 工具接入

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

URL: https://docs.passion8.cc/docs/claude-code/mcp
Language: zh-CN
Publisher: Passion8

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

```bash
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

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

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

### 本地 stdio

```bash
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

```bash
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` |

```bash
# 默认 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 工具名形如:

```text
mcp__<server>__<tool>
```

例子:

```json title=".claude/settings.json"
{
  "permissions": {
    "allow": [
      "mcp__github__get_*"
    ],
    "ask": [
      "mcp__database__write_*"
    ],
    "deny": [
      "mcp__dangerous__*"
    ]
  }
}
```

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

```json title=".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`。

## 官方参考

- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp.md)
- [MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart.md)
- [Prompt caching and MCP tool changes](https://code.claude.com/docs/en/prompt-caching.md)