首页
/ Claude Code 的 MCP 完整实战指南：传输协议、作用域、OAuth 与上下文效率（基于 claude-howto）

Claude Code 的 MCP 完整实战指南：传输协议、作用域、OAuth 与上下文效率（基于 claude-howto）

2026-09-09 17:00:58作者：齐冠琰
claude-howto
A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
项目地址：https://gitcode.com/GitHub_Trending/cl/claude-howto

本文基于 claude-howto 仓库的 ja/05-mcp/README.md（Model Context Protocol 专题文档，基于 Claude Code v2.1.119 整理），系统讲解如何在 Claude Code 中接入、管理与扩展 MCP（Model Context Protocol）服务器：从 HTTP/stdio/SSE 三种传输协议的连接命令、OAuth 2.0 认证、local/project/user 三级作用域，到工具搜索、输出上限、企业管控，以及用代码执行（Code Execution）与 MCPorter 解决规模化 MCP 带来的上下文膨胀问题。读完本文，你可以直接复制文中的命令与 .mcp.json 配置，把自己的 GitHub、数据库、Slack、文件系统等服务接入 Claude Code 并构建多 MCP 工作流。

1. MCP 的定位：与 Memory 的本质区别

MCP（Model Context Protocol）是 Claude 访问外部工具、API 与实时数据源的标准方式。与 Memory（记忆）不同，MCP 提供的是对不断变化数据的实时访问。其主要特征包括：

  • 对外部服务的实时访问（Real-time access）
  • 实时数据同步（Live data synchronization）
  • 可扩展架构（Extensible architecture）
  • 安全认证（Secure authentication）
  • 基于工具的交互（Tool-based interactions）

1.1 架构：请求-查询-响应三段链路

从源码文档给出的架构图看，一次 MCP 交互遵循「Claude → MCP Server → 外部服务」的三段链路：

graph TB
    A["Claude"]
    B["MCP Server"]
    C["External Service"]

    A -->|Request: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Request: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

请求/响应模式上，MCP 强调实时访问、不做缓存。以数据库为例：

sequenceDiagram
    participant App as Claude
    participant MCP as MCP Server
    participant DB as Database

    App->>MCP: Request: "SELECT * FROM users WHERE id=1"
    MCP->>DB: Execute query
    DB-->>MCP: Result set
    MCP-->>App: Return parsed data
    App->>App: Process result
    App->>App: Continue task

    Note over MCP,DB: Real-time access<br/>No caching

1.2 生态全景：一个 Claude 连接多个 MCP Server

Claude Code 可以同时接入文件系统、GitHub、数据库、Slack、Google Docs 等多类 MCP Server，各自代理到不同的底层资源：

graph TB
    A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
    A -->|MCP| C["GitHub<br/>MCP Server"]
    A -->|MCP| D["Database<br/>MCP Server"]
    A -->|MCP| E["Slack<br/>MCP Server"]
    A -->|MCP| F["Google Docs<br/>MCP Server"]

    B -->|File I/O| G["Local Files"]
    C -->|API| H["GitHub Repos"]
    D -->|Query| I["PostgreSQL/MySQL"]
    E -->|Messages| J["Slack Workspace"]
    F -->|Docs| K["Google Drive"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#f3e5f5,stroke:#333,color:#333
    style F fill:#f3e5f5,stroke:#333,color:#333
    style G fill:#e8f5e9,stroke:#333,color:#333
    style H fill:#e8f5e9,stroke:#333,color:#333
    style I fill:#e8f5e9,stroke:#333,color:#333
    style J fill:#e8f5e9,stroke:#333,color:#333
    style K fill:#e8f5e9,stroke:#333,color:#333

2. 接入 MCP 服务器：四种传输方式

Claude Code 支持多种传输协议（transport）连接 MCP 服务器。

2.1 HTTP 传输（官方推荐）

# 基本的 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"

2.2 Stdio 传输（本地服务器）

适用于本地运行的 MCP 服务器（Node.js 等）：

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

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

2.3 SSE 传输（已弃用但仍受支持）

Server-Sent Events 传输因 http 的推出而被标记为弃用，但仍可继续使用：

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

2.4 Windows 平台的注意事项

原生 Windows（非 WSL）下，npx 命令需要通过 cmd /c 调用：

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

3. OAuth 2.0 认证与元数据覆盖

Claude Code 支持需要 OAuth 2.0 的 MCP 服务器。连接 OAuth 服务器时，Claude Code 会处理完整的认证流程。

# 连接支持 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 能力矩阵：

能力 说明
交互式 OAuth 通过 /mcp 触发基于浏览器的 OAuth 流程
预置 OAuth 客户端 针对 Notion、Stripe 等常见服务的内置 OAuth 客户端（v2.1.30 起）
预置凭据 --client-id、--client-secret、--callback-port 标志，用于自动化配置
令牌存储 令牌安全地存储在系统钥匙串（system keychain）中
步进认证（step-up） 支持特权操作的步进式认证
发现缓存 OAuth 发现元数据会被缓存，加速重连
元数据覆盖 可通过 .mcp.json 中的 oauth.authServerMetadataUrl 覆盖默认的 OAuth 元数据发现

3.1 覆盖 OAuth 元数据发现地址

当 MCP 服务器在标准 OAuth 元数据端点（/.well-known/oauth-authorization-server）上返回错误、但公布了另一个可用的 OIDC 端点时，可以在服务器配置的 oauth 对象中设置 authServerMetadataUrl，指定 Claude Code 从哪个 URL 获取 OAuth 元数据：

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

注意：该 URL 必须使用 https://，且此选项需要 Claude Code v2.1.64 及以上版本。

3.2 Claude.ai MCP 连接器

在 Claude.ai 账号中配置的 MCP 服务器会自动在 Claude Code 中可用——即通过 Claude.ai Web 界面设置的 MCP 连接，无需额外配置即可访问。Claude.ai MCP 连接器自 v2.1.83 起在 --print（无交互/脚本）模式下也可用。

启动说明（v2.1.117 起）： 当同时配置了本地与 claude.ai 的 MCP 服务器时，默认采用并行连接（此前为串行连接），可减少多服务器场景下的启动延迟。

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

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

注意：该功能仅对已登录 Claude.ai 账号的用户可用。

4. 设置流程与日常管理命令

4.1 交互式设置流程

输入 /mcp 后，Claude Code 会列出所有可用 MCP 服务器并引导完成配置与连接测试：

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Config as Config File
    participant Service as External Service

    User->>Claude: Type /mcp
    Claude->>Claude: List available MCP servers
    Claude->>User: Show options
    User->>Claude: Select GitHub MCP
    Claude->>Config: Update configuration
    Config->>Claude: Activate connection
    Claude->>Service: Test connection
    Service-->>Claude: Authentication successful
    Claude->>User: ✅ MCP connected!

4.2 完整的 CLI 管理命令

# 添加 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

5. 作用域（Scope）：Local / Project / User

MCP 配置可以保存在不同的共享级别，通过 claude mcp add 的 --scope（短形式 -s）指定，缺省为 local：

作用域 标志 存储位置 说明 共享对象 是否需要审批
Local（默认） --scope local ~/.claude.json（项目路径下） 仅当前用户、当前项目可见（旧版本中称为 project） 仅自己 否
Project --scope project .mcp.json 会被提交进 git 仓库 团队成员 需要（首次使用时）
User --scope user ~/.claude.json 所有项目可用（旧版本中称为 global） 仅自己 否 
# Project 作用域 — 写入 .mcp.json，团队共享
claude mcp add --scope project --transport http github https://api.github.com/mcp

# User 作用域 — 所有项目可用
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory

5.1 Project 作用域的 .mcp.json 示例

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

团队成员首次使用项目级 MCP 时会收到审批提示。

5.2 服务器去重（Deduplication）

同一 MCP 服务器在多个作用域（local、project、user）中都有定义时，本地配置优先，从而可以无冲突地用本地自定义覆盖项目级或用户级设置。

6. 四个实战示例（可复制配置）

claude-howto 仓库的 ja/05-mcp/ 目录下提供了四个现成的 stdio 型配置示例文件，可直接查看或作为 .mcp.json 的起点：github-mcp.json、database-mcp.json、filesystem-mcp.json、multi-mcp.json（同时挂载 GitHub、Database、Slack、Filesystem 四个服务器）。

6.1 示例一：GitHub MCP

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

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

仓库中 github-mcp.json 即该配置的 stdio 版本（多一个 "type": "stdio" 字段）。可用的 GitHub MCP 工具按功能分组：

Pull Request 管理

  • list_prs — 列出仓库内所有 PR
  • get_pr — 获取含 diff 的 PR 详情
  • create_pr — 创建新 PR
  • update_pr — 更新 PR 描述/标题
  • merge_pr — 将 PR 合并到 main
  • review_pr — 添加评审评论

调用示例（MCP 提示词以斜杠命令形式暴露）：

/mcp__github__get_pr 456

# 返回:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie

Issue 管理：list_issues（列出全部 Issue）、get_issue（详情）、create_issue（新建）、close_issue（关闭）、add_comment（添加评论）。

仓库信息：get_repo_info（仓库详情）、list_files（文件树）、get_file_content（读取文件内容）、search_code（全库代码搜索）。

提交操作：list_commits（提交历史）、get_commit（指定提交详情）、create_commit（新建提交）。

配置步骤：

export GITHUB_TOKEN="your_github_token"
# 或通过 CLI 直接添加:
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

6.2 示例二：Database MCP

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

使用效果示例——自然语言驱动实时 SQL 查询：

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# 调用 MCP 数据库工具:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# 结果:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

配置步骤：

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
# 或通过 CLI 直接添加:
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

6.3 示例三：多 MCP 协作（日报工作流）

场景：每日报表生成，组合四个 MCP——GitHub（PR 指标）、Database（销售数据）、Slack（发布报告）、Filesystem（保存报告）：

# 使用多个 MCP 的 Daily Report 工作流

## 配置
1. GitHub MCP - 获取 PR 指标
2. Database MCP - 查询销售数据
3. Slack MCP - 发布报告
4. Filesystem MCP - 保存报告

## 工作流

### Step 1: 获取 GitHub 数据
/mcp__github__list_prs completed:true last:7days

输出:
- PR 总数: 42
- 平均合并时长: 2.3 小时
- 评审周转: 1.1 小时

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

输出:
- 销量: 247
- 营收: $12,450

### Step 3: 生成报告
将数据组合为 HTML 报告

### Step 4: 保存到文件系统
将 report.html 写入 /reports/

### Step 5: 推送到 Slack
把摘要发送到 #daily-reports 频道

最终输出:
✅ 报告已生成并发布
📊 本周合并 47 个 PR
💰 日销售额 $12,450

配置步骤：

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
# 用 CLI 逐个添加各 MCP 服务器，或在 .mcp.json 中统一配置

仓库中 multi-mcp.json 正是该场景的四服务器统一配置（github/database/slack/filesystem 全部以 stdio + npx 方式声明，认证信息均通过 ${...} 环境变量注入）。

6.4 示例四：Filesystem MCP

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

可用操作一览：

操作 命令 用途
列出文件 ls ~/projects 显示目录内容
读取文件 cat src/main.ts 读取文件内容
写入文件 create docs/api.md 创建新文件
编辑文件 edit src/app.ts 修改文件
搜索 grep "async function" 在文件内搜索
删除 rm old-file.js 删除文件

配置步骤：

claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

7. 环境变量与配置展开

MCP 配置支持环境变量展开与回退默认值，${VAR} 与 ${VAR:-default} 两种语法在 command、args、env、url、headers 字段中均有效：

{
  "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}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

变量在运行时展开，规则为：

  • ${VAR} — 使用环境变量；未设置则报错
  • ${VAR:-default} — 使用环境变量；未设置则回退到 default

敏感凭据建议统一放入环境变量（~/.bashrc 或 ~/.zshrc），再在 MCP 配置中引用：

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

8. 上下文效率机制：工具搜索、动态更新与输出上限

8.1 MCP 工具搜索（Tool Search）

当 MCP 工具描述占上下文窗口超过 10% 时，Claude Code 会自动启用工具搜索，在不挤占模型上下文的前提下高效挑选合适的工具。

设置 值 说明
ENABLE_TOOL_SEARCH auto（默认） 工具描述超过上下文 10% 时自动启用
ENABLE_TOOL_SEARCH auto:<N> 以自定义工具数量阈值 N 自动启用
ENABLE_TOOL_SEARCH true 无论工具数量多少始终启用
ENABLE_TOOL_SEARCH false 禁用；所有工具描述按全量发送

注意：工具搜索要求 Sonnet 4 及以上或 Opus 4 及以上模型；Haiku 模型不支持工具搜索。

8.2 动态工具更新（list_changed）

Claude Code 支持 MCP 的 list_changed 通知：MCP 服务器动态增删改工具时，Claude Code 会收到更新并自动调整工具列表，无需重连或重启。

8.3 工具描述与指令的 2 KB 上限

自 v2.1.84 起，Claude Code 对每个 MCP 服务器的工具描述与指令强制 2 KB 上限，防止单个服务器用冗长的工具定义过度消耗上下文，控制上下文膨胀、保持对话高效。

8.4 MCP Apps 与 Elicitation

  • MCP Apps：首个官方 MCP 扩展，允许 MCP 工具调用直接返回在聊天界面内渲染的交互式 UI 组件——服务器可以在对话内联呈现丰富的仪表盘、表单、数据可视化与多步工作流，而不只是纯文本响应。
  • MCP Elicitation（v2.1.49 起）：MCP 服务器可通过交互式对话框向用户请求结构化输入（确认提示、选项选择、必填字段录入等），让工作流中途也能补充信息。

8.5 MCP 输出上限

为防止上下文溢出，Claude Code 对 MCP 工具输出强制分级上限：

上限 阈值 行为
警告 10,000 token 显示输出过大的警告
默认最大值 25,000 token 超限输出会被截断
磁盘持久化 50,000 字符 超过 50K 字符的工具结果写入磁盘

最大输出上限可通过 MAX_MCP_OUTPUT_TOKENS 环境变量调整：

# 将最大输出提升到 50,000 token
export MAX_MCP_OUTPUT_TOKENS=50000

9. 提示词、资源引用与「反向」MCP

9.1 MCP 提示词作为斜杠命令

MCP 服务器可以发布以斜杠命令形式呈现的提示词，命名规则为：

/mcp__<server>__<prompt>

例如 github 服务器发布 review 提示词时，可通过 /mcp__github__review 调用。

9.2 用 @ 提及引用 MCP 资源

@ 提及语法可在提示词中直接引用 MCP 资源：

@server-name:protocol://resource/path

例如引用数据库资源：

@database:postgres://mydb/users

这样 Claude 就能把 MCP 资源内容作为对话上下文的一部分内联获取。

9.3 把 Claude 本身变成 MCP 服务器：claude mcp serve

Claude Code 自身可以作为其他应用程序的 MCP 服务器，让外部工具、编辑器、自动化系统通过标准 MCP 协议使用 Claude 的能力：

# 以 stdio 方式启动 Claude Code 作为 MCP 服务器
claude mcp serve

其他应用可以像连接普通 stdio MCP 服务器一样连接它。例如把一个 Claude Code 实例作为 MCP 服务器添加到另一个 Claude Code 实例：

claude mcp add --transport stdio claude-agent -- claude mcp serve

这是构建多智能体工作流（一个 Claude 实例编排另一个实例）的实用方式。

10. 企业管控、插件与子代理级 MCP

10.1 托管 MCP 配置（Enterprise）

企业部署中，IT 管理员可通过 managed-mcp.json 强制 MCP 服务器策略，对组织范围内允许/禁止的 MCP 服务器进行独占控制。

部署位置：

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

能力：

  • allowedMcpServers — 允许服务器的白名单
  • deniedMcpServers — 禁止服务器的黑名单
  • 支持按服务器名、命令、URL 模式匹配
  • 在用户配置之前强制组织级 MCP 策略
  • 阻止未经授权的服务器连接

配置示例：

{
  "allowedMcpServers": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "deniedMcpServers": [
    {
      "serverName": "untrusted-*"
    },
    {
      "serverUrl": "http://*"
    }
  ]
}

注意：当同一服务器同时匹配 allowedMcpServers 与 deniedMcpServers 时，deny 规则优先。

10.2 插件提供的 MCP 服务器

插件可以捆绑自己的 MCP 服务器，安装插件后自动可用，有两种定义方式：

  1. 独立 .mcp.json — 放在插件根目录
  2. plugin.json 内联定义 — 在插件清单中直接定义

用 ${CLAUDE_PLUGIN_ROOT} 变量引用插件安装目录的相对路径：

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

10.3 子代理作用域的 MCP

MCP 服务器可以在智能体 frontmatter 中用 mcpServers: 键内联定义，从而把作用域限定在某个特定子代理而非整个项目。这在某个智能体需要、而其他工作流成员不需要某个 MCP 服务器时非常有用：

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.

子代理作用域的 MCP 服务器仅在该智能体的执行上下文中可用，不会与父智能体或兄弟智能体共享。仓库中 ja/04-subagents/README.md 的 frontmatter 参考表也列出了 mcpServers 字段（v2.1.117 起，智能体通过 claude --agent <name> 作为主线程智能体调用时加载），可配合本节的配置方式交叉参考。

11. 规模化 MCP 的上下文膨胀：代码执行方案与 MCPorter

随着 MCP 普及，连接数十个服务器、数百乃至数千个工具会带来最大问题——上下文膨胀。Anthropic 工程团队在「Code Execution with MCP: Building More Efficient Agents」一文中给出了优雅的解法：与其直接调用工具，不如执行代码。

11.1 问题：token 浪费的两个来源

1. 工具定义压垮上下文窗口：大多数 MCP 客户端会预加载全部工具定义，连接数千个工具时，模型在读取用户请求之前就要先处理数十万 token。

2. 中间结果进一步消耗 token：所有中间工具结果都要穿过模型上下文。以把 Google Drive 的会议转录转到 Salesforce 为例，整段转录要在上下文里流 两次——读取一次、写入一次。2 小时会议的转录可能带来 50,000+ token 的额外开销：

graph LR
    A["Model"] -->|"Tool Call: getDocument"| B["MCP Server"]
    B -->|"Full transcript (50K tokens)"| A
    A -->|"Tool Call: updateRecord<br/>(re-sends full transcript)"| B
    B -->|"Confirmation"| A

    style A fill:#ffcdd2,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333

11.2 解法：把 MCP 工具当作代码 API

与其让工具定义与结果穿过上下文窗口，不如让智能体编写代码、把 MCP 工具作为 API 调用。代码运行在沙箱化执行环境中，只有最终结果返回模型：

graph LR
    A["Model"] -->|"Writes code"| B["Code Execution<br/>Environment"]
    B -->|"Calls tools directly"| C["MCP Servers"]
    C -->|"Data stays in<br/>execution env"| B
    B -->|"Only final result<br/>(minimal tokens)"| A

    style A fill:#c8e6c9,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333

工作机制：MCP 工具以「带类型函数」的文件树形式呈现：

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── ...

每个工具文件包含一个带类型的包装器：

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

智能体随后编写代码来编排工具：

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

// 数据在工具之间直接流动 — 不经过模型
const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

按原文给出的示例数据，该场景 token 用量从约 150,000 降到约 2,000，削减约 98.7%。

核心优势：

优势 说明
渐进式披露 智能体按需浏览文件系统读取所需工具定义，而非预加载全部
上下文友好的结果 数据在执行环境中过滤/变换后才返回模型
强控制流 循环、条件分支、错误处理无需往返模型即可在代码中完成
隐私保护 中间数据（PII、机密记录）留在执行环境内，不进入模型上下文
状态持久化 智能体可把中间结果存文件，构建可复用的技能函数

大规模数据过滤示例（对比有无代码执行）：

// 无代码执行 — 10,000 行全部流经上下文
// TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
//   -> returns 10,000 rows in context

// 有代码执行 — 在执行环境内过滤
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(
  row => row["Status"] === 'pending'
);
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // 仅 5 行到达模型

无往返的轮询示例：

// 轮询部署通知 — 全部在代码内完成
let found = false;
while (!found) {
  const messages = await slack.getChannelHistory({
    channel: 'C123456'
  });
  found = messages.some(
    m => m.text.includes('deployment complete')
  );
  if (!found) await new Promise(r => setTimeout(r, 5000));
}
console.log('Deployment notification received');

需要权衡的代价：执行智能体生成的代码要求具备——带资源限额的安全沙箱、对执行代码的监控与日志、相对直接工具调用的额外基础设施开销。只有少数 MCP 服务器的智能体可能直接调工具更简单；对规模化的智能体（数十服务器、数百工具），代码执行是显著改进。

11.3 MCPorter：MCP 工具编排运行时

MCPorter 是一个让 MCP 服务器调用「去样板化」的 TypeScript 运行时与 CLI 工具包，也能通过选择性暴露工具与类型化包装器抑制上下文膨胀：

功能 说明
零配置发现 自动从 Cursor、Claude、Codex、本地配置中发现 MCP 服务器
类型化工具客户端 mcporter emit-ts 生成 .d.ts 接口与开箱即用的包装器
可配置 API createServerProxy() 把工具暴露为 camelCase 方法，并提供 .text()、.json()、.markdown() 助手
CLI 生成 mcporter generate-cli 把任意 MCP 服务器变成独立 CLI，支持 --include-tools / --exclude-tools 过滤
参数隐藏 可选参数默认隐藏，降低 schema 冗余

安装方式：

npx mcporter list          # 无需安装 — 立即发现服务器
pnpm add mcporter          # 添加到项目
brew install steipete/tap/mcporter  # macOS 的 Homebrew 渠道

TypeScript 编排示例：

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

// 数据不经过模型上下文，在工具之间直接流动
const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

CLI 直接调用示例：

# 直接调用特定工具
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# 列出可用服务器与工具
npx mcporter list

MCPorter 与前述代码执行方案互补，为「以类型化 API 调用 MCP 工具」提供运行时基础设施，使中间数据可以保留在模型上下文之外。

12. MCP 与 Memory 如何选：判断矩阵

graph TD
    A["Need external data?"]
    A -->|No| B["Use Memory"]
    A -->|Yes| C["Does it change frequently?"]
    C -->|No/Rarely| B
    C -->|Yes/Often| D["Use MCP"]

    B -->|Stores| E["Preferences<br/>Context<br/>History"]
    D -->|Accesses| F["Live APIs<br/>Databases<br/>Services"]

    style A fill:#fff3e0,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#fff3e0,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#e8f5e9,stroke:#333,color:#333
    style F fill:#e8f5e9,stroke:#333,color:#333

判断规则可归纳为：

  • Memory：存储持久、不变的数据（配置、上下文、历史）——用户偏好、对话历史、学习到的上下文；
  • MCP：访问实时变化数据（API、数据库、实时服务）——当前 GitHub Issue、实时数据库查询。

二者可以组合：用 Memory + MCP 共同构建更丰富的上下文，在提示词中使用 MCP 工具改善推理，复杂工作流则组合多个 MCP。

13. 最佳实践：安全、配置与性能

13.1 安全考虑

推荐 ✅

  • 所有凭据使用环境变量
  • 定期轮换 token 与 API key（建议每月）
  • 尽可能使用只读 token
  • 最小化 MCP 服务器的访问范围
  • 监控 MCP 服务器用量与访问日志
  • 外部服务优先使用 OAuth
  • 为 MCP 请求实施速率限制
  • 上线前测试 MCP 连接
  • 文档化所有运行中的 MCP 连接
  • 保持 MCP 服务器包更新

禁止 ❌

  • 不要在配置文件里硬编码凭据
  • 不要把 token/秘密提交进 git
  • 不要在团队聊天或邮件里分享 token
  • 不要将个人 token 用于团队项目
  • 不要授予不必要的权限
  • 不要忽略认证错误
  • 不要暴露 MCP 端点
  • 不要以 root/admin 权限运行 MCP 服务器
  • 不要在日志中缓存机密数据
  • 不要禁用认证机制

13.2 配置最佳实践

  1. 版本管理：.mcp.json 存进 git，秘密走环境变量
  2. 最小权限：每个 MCP 服务器只授予必需权限
  3. 隔离：尽量让不同 MCP 服务器跑在不同进程
  4. 监控：为审计留痕记录所有 MCP 请求与错误
  5. 测试：生产部署前测试所有 MCP 配置

13.3 性能提示

  • 高频访问数据在应用层缓存
  • 使用特定化的 MCP 查询减少数据量
  • 监控 MCP 操作响应时间
  • 对外部 API 考虑速率限制
  • 多操作时优先批处理

14. 从零开始：安装与排错

14.1 前提条件

  • 已安装 Node.js 与 npm
  • 已安装 Claude Code CLI
  • 拥有外部服务的 API token/凭据

14.2 分步配置

  1. 添加第一个 MCP 服务器（如 GitHub）：
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

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

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
  1. 设置环境变量：
export GITHUB_TOKEN="your_github_personal_access_token"
  1. 测试连接：
claude /mcp
  1. 使用 MCP 工具：
/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

14.3 各服务的 npm 包安装

服务 安装命令
GitHub MCP npm install -g @modelcontextprotocol/server-github
Database MCP npm install -g @modelcontextprotocol/server-database
Filesystem MCP npm install -g @modelcontextprotocol/server-filesystem
Slack MCP npm install -g @modelcontextprotocol/server-slack

14.4 常见服务器一览

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 是
Asana 项目管理 create_task、update_status API key 是
Stripe 支付数据 list_charges、create_invoice API key 是
Memory 持久记忆 store、retrieve、delete 本地 否

14.5 故障排查

MCP 服务器找不到：

# 确认 MCP 服务器已安装
npm list -g @modelcontextprotocol/server-github

# 未安装则安装
npm install -g @modelcontextprotocol/server-github

认证失败：

# 确认环境变量已设置
echo $GITHUB_TOKEN

# 必要时重新设置
export GITHUB_TOKEN="your_token"

并确认 token 具备正确权限范围（scope）。

连接超时：

  • 检查网络连通性：ping api.github.com
  • 确认 API 端点可达
  • 检查 API 速率限制
  • 尝试在配置中延长超时
  • 排查防火墙或代理问题

MCP 服务器崩溃：

  • 查看 MCP 服务器日志：~/.claude/logs/
  • 确认所有环境变量已设置
  • 检查文件权限
  • 尝试重新安装 MCP 服务器包
  • 检查是否有进程争用同一端口

15. 小结与延伸阅读

这篇指南覆盖了 claude-howto 仓库 MCP 专题文档的完整脉络：传输协议选择（HTTP 优先、stdio 本地、SSE 弃用）、OAuth 2.0 全流程与 authServerMetadataUrl 覆盖、三级作用域与去重规则、${VAR}/${VAR:-default} 环境变量展开、工具搜索与 list_changed 动态更新、2 KB 描述上限与 10K/25K/50K 输出分级、claude mcp serve 反向暴露、企业 managed-mcp.json 管控、插件与子代理级 MCP，直至用代码执行 + MCPorter 化解规模化上下文膨胀。文中所有 .mcp.json 示例均可与仓库现成示例对照：github-mcp.json、database-mcp.json、filesystem-mcp.json、multi-mcp.json；英文原版文档见 05-mcp/README.md，子代理 frontmatter 中的 mcpServers 用法可进一步参阅 ja/04-subagents/README.md。

适用前提与版本边界（以该文档基于 Claude Code v2.1.119、2026-04-24 更新为准）：工具搜索要求 Sonnet 4+/Opus 4+；oauth.authServerMetadataUrl 需要 v2.1.64+；MCP Apps/Elicitation 分别依赖 v2.1.49+ 等更新版本；ENABLE_CLAUDEAI_MCP_SERVERS 关闭 Claude.ai 服务器仅对已登录 Claude.ai 的用户有意义。

（完）

claude-howto
A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
项目地址：https://gitcode.com/GitHub_Trending/cl/claude-howto
登录后查看全文

相关内容推荐

1 claude-howto MCP 完全指南：用 Model Context Protocol 为 Claude Code 接入 GitHub、数据库与文件系统2 claude-howto MCP 完全指南：传输协议、OAuth 认证、多作用域配置与企业级管控3 Claude How To 功能全目录指南：从 Slash Commands 到 Plugins 的 Claude Code 完整能力地图4 Claude Code 功能全景总览：claude-howto 仓库的 158 项能力清单与一键落地指南5 Claude Code 功能全目录实战指南：从 Slash Commands 到 Hooks 的一站式能力地图6 Claude Code 学习路线图：claude-howto 十大模块结构与快速上手实战指南7 Claude Code 学习路线图（claude-howto）：11 小时从新手到高阶用户的系统化进阶指南8 claude-howto Claude Code 功能目录：命令、子代理、技能、插件、Hook 与 MCP 的快速参考和安装指南9 claude-howto 资源导航：Claude Code 官方文档清单、30 分钟速成技巧与新旧仓库工作流10 从更新日志看 claude-howto 的版本同步与文档质量工程：Claude Code 教程仓库的演进实录
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
docsdocs
暂无描述
Markdown
900
5.83 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.14 K
2.75 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
860
1.35 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
927
1.85 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.84 K
1.02 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
533
603
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.37 K
1.46 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
548
397
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.04 K
525