MCP（模型上下文协议）

本节包含 MCP 服务器配置和在 Claude Code 中使用 MCP 的完整文档与示例。

概述

MCP（Model Context Protocol，模型上下文协议）是 Claude 访问外部工具、API 和实时数据源的标准化方式。与记忆系统不同，MCP 提供对动态变化数据的实时访问。

核心特性：

实时访问外部服务
数据实时同步
可扩展架构
安全认证
基于工具的交互方式

MCP 架构

MCP 生态系统

MCP 安装方式

Claude Code 支持多种传输协议连接 MCP 服务器：

HTTP 传输（推荐）

bash

# 基本 HTTP 连接
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证头的 HTTP 连接
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Stdio 传输（本地）

用于本地运行的 MCP 服务器：

bash

# 本地 Node.js 服务器
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# 带环境变量
claude mcp add --transport stdio myserver --env KEY=value -- npx server

SSE 传输（已废弃）

Server-Sent Events 传输已废弃，建议使用 http，但仍受支持：

bash

claude mcp add --transport sse legacy-server https://example.com/sse

WebSocket 传输

用于持久双向连接：

bash

claude mcp add --transport ws realtime-server wss://example.com/mcp

Windows 特别说明

在原生 Windows（非 WSL）上，npx 命令需使用 cmd /c：

bash

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

OAuth 2.0 认证

Claude Code 支持 OAuth 2.0 认证的 MCP 服务器，会自动处理完整认证流程：

bash

# 连接支持 OAuth 的 MCP 服务器（交互式流程）
claude mcp add --transport http my-service https://my-service.example.com/mcp

# 非交互式配置 OAuth 凭证
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

功能	说明
交互式 OAuth	使用 `/mcp` 触发浏览器 OAuth 流程
预配置 OAuth 客户端	Notion、Stripe 等常用服务的内置 OAuth 客户端（v2.1.30+）
预配置凭证	使用 `--client-id`、`--client-secret`、`--callback-port` 自动配置
Token 存储	Token 安全存储在系统密钥链中
升级认证	支持特权操作的升级认证
发现缓存	OAuth 发现元数据缓存以加快重连速度
元数据覆盖	在 `.mcp.json` 中使用 `oauth.authServerMetadataUrl` 覆盖默认发现地址

Claude.ai MCP 连接器

在 Claude.ai 账户中配置的 MCP 服务器会自动在 Claude Code 中可用，无需额外配置。

Claude.ai MCP 连接器也支持 --print 模式（v2.1.83+），可用于非交互式和脚本化使用。

如需在 Claude Code 中禁用 Claude.ai MCP 服务器，将环境变量 ENABLE_CLAUDEAI_MCP_SERVERS 设为 false：

bash

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

注意： 此功能仅适用于使用 Claude.ai 账户登录的用户。

MCP 配置管理

添加 MCP 服务器

bash

# 添加 HTTP 服务器
claude mcp add --transport http github https://api.github.com/mcp

# 添加本地 stdio 服务器
claude mcp add --transport stdio database -- npx @company/db-server

# 列出所有 MCP 服务器
claude mcp list

# 查看特定服务器详情
claude mcp get github

# 移除 MCP 服务器
claude mcp remove github

# 重置项目特定的审批选择
claude mcp reset-project-choices

# 从 Claude Desktop 导入
claude mcp add-from-claude-desktop

MCP 作用域

MCP 配置可存储在不同作用域：

作用域	位置	说明	共享对象	需要审批
本地（默认）	`~/.claude.json`（项目路径下）	仅当前用户、当前项目可用	仅自己	否
项目	`.mcp.json`	提交到 git 仓库	团队成员	是（首次使用）
用户	`~/.claude.json`	所有项目均可用	仅自己	否

常用 MCP 服务器

MCP 服务器	用途	常用工具	认证方式	实时
Filesystem	文件操作	read, write, delete	OS 权限	✅ 是
GitHub	仓库管理	list_prs, create_issue, push	OAuth	✅ 是
Slack	团队通信	send_message, list_channels	Token	✅ 是
Database	SQL 查询	query, insert, update	凭证	✅ 是
Google Docs	文档访问	read, write, share	OAuth	✅ 是
Memory	持久记忆	store, retrieve, delete	本地	❌ 否

实战示例

示例一：GitHub MCP 配置

文件： .mcp.json（项目根目录）

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

配置：

bash

export GITHUB_TOKEN="your_github_token"
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

示例二：数据库 MCP

json

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

示例三：多 MCP 工作流

综合使用 GitHub MCP + 数据库 MCP + Slack MCP 生成日报：

markdown

# 每日报告工作流

## 步骤一：获取 GitHub 数据
/mcp__github__list_prs completed:true last:7days

## 步骤二：查询数据库
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders WHERE created_at > NOW() - INTERVAL '1 day'

## 步骤三：生成报告并发布到 Slack

配置中的环境变量扩展

MCP 配置支持带默认值的环境变量扩展：

json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    }
  }
}

${VAR} —— 使用环境变量，未设置则报错
${VAR:-default} —— 使用环境变量，未设置则回退到默认值

Claude 作为 MCP 服务器

Claude Code 本身也可以作为 MCP 服务器，供其他应用使用：

bash

# 以 MCP 服务器模式启动 Claude Code
claude mcp serve

# 在另一个 Claude Code 实例中添加
claude mcp add --transport stdio claude-agent -- claude mcp serve

企业托管 MCP 配置

IT 管理员可通过 managed-mcp.json 强制执行 MCP 服务器策略：

macOS：/Library/Application Support/ClaudeCode/managed-mcp.json
Linux：~/.config/ClaudeCode/managed-mcp.json
Windows：%APPDATA%\ClaudeCode\managed-mcp.json

json

{
  "allowedMcpServers": [
    { "serverName": "github", "serverUrl": "https://api.github.com/mcp" }
  ],
  "deniedMcpServers": [
    { "serverUrl": "http://*" }
  ]
}

MCP 工具搜索

当 MCP 工具描述超过上下文窗口的 10% 时，Claude Code 自动启用工具搜索：

设置	值	说明
`ENABLE_TOOL_SEARCH`	`auto`（默认）	超过阈值时自动启用
`ENABLE_TOOL_SEARCH`	`true`	始终启用
`ENABLE_TOOL_SEARCH`	`false`	始终禁用

MCP 输出限制

限制	阈值	行为
警告	10,000 tokens	显示输出过大的警告
默认上限	25,000 tokens	超出部分被截断
磁盘持久化	50,000 字符	超出时结果持久化到磁盘

bash

# 调整最大输出 Token 数
export MAX_MCP_OUTPUT_TOKENS=50000

用代码执行解决上下文膨胀

随着 MCP 的规模化使用，大量工具定义会造成严重的上下文膨胀。Anthropic 工程团队提出了一种优雅的解决方案——用代码执行替代直接工具调用。

效果：Token 使用量从 ~150,000 降至 ~2,000，减少 98.7%。

最佳实践

安全注意事项

✅ 推荐做法：

所有凭证使用环境变量
定期轮换 Token 和 API Key（建议每月）
尽量使用只读 Token
最小权限原则
监控 MCP 使用日志
外部服务优先使用 OAuth

❌ 禁止做法：

禁止在配置文件中硬编码凭证
禁止将 Token/Secret 提交到 git
禁止在团队聊天或邮件中分享 Token
禁止为团队项目使用个人 Token

故障排查

MCP 服务器未找到

bash

npm list -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-github

认证失败

bash

echo $GITHUB_TOKEN
export GITHUB_TOKEN="your_token"

连接超时

检查网络：ping api.github.com
确认 API 端点可访问
检查 API 限流
尝试增加超时时间

MCP vs 记忆系统

记忆系统：存储持久不变的数据（偏好、上下文、历史）
MCP：访问动态变化的数据（API、数据库、实时服务）

其他资源

官方 MCP 文档
MCP 协议规范
MCPorter — TypeScript 运行时，无样板代码调用 MCP 服务器
Code Execution with MCP — Anthropic 工程博客

MCP（模型上下文协议） ​

概述 ​

MCP 架构 ​

MCP 生态系统 ​

MCP 安装方式 ​

HTTP 传输（推荐） ​

Stdio 传输（本地） ​

SSE 传输（已废弃） ​

WebSocket 传输 ​

Windows 特别说明 ​

OAuth 2.0 认证 ​

Claude.ai MCP 连接器 ​

MCP 配置管理 ​

添加 MCP 服务器 ​

MCP 作用域 ​

常用 MCP 服务器 ​

实战示例 ​

示例一：GitHub MCP 配置 ​

示例二：数据库 MCP ​

示例三：多 MCP 工作流 ​

配置中的环境变量扩展 ​

Claude 作为 MCP 服务器 ​

企业托管 MCP 配置 ​

MCP 工具搜索 ​

MCP 输出限制 ​

用代码执行解决上下文膨胀 ​

最佳实践 ​

安全注意事项 ​

故障排查 ​

MCP 服务器未找到 ​

认证失败 ​

连接超时 ​

MCP vs 记忆系统 ​

其他资源 ​

MCP（模型上下文协议）

概述

MCP 架构

MCP 生态系统

MCP 安装方式

HTTP 传输（推荐）

Stdio 传输（本地）

SSE 传输（已废弃）

WebSocket 传输

Windows 特别说明

OAuth 2.0 认证

Claude.ai MCP 连接器

MCP 配置管理

添加 MCP 服务器

MCP 作用域

常用 MCP 服务器

实战示例

示例一：GitHub MCP 配置

示例二：数据库 MCP

示例三：多 MCP 工作流

配置中的环境变量扩展

Claude 作为 MCP 服务器

企业托管 MCP 配置

MCP 工具搜索

MCP 输出限制

用代码执行解决上下文膨胀

最佳实践

安全注意事项

故障排查

MCP 服务器未找到

认证失败

连接超时

MCP vs 记忆系统

其他资源