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

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

【免费下载链接】claude-howtoA 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 → 外部服务」的三段链路：

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

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

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

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 能力矩阵：

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 服务器并引导完成配置与连接测试：

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：

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

可用操作一览：

配置步骤：

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 会自动启用工具搜索，在不挤占模型上下文的前提下高效挑选合适的工具。

注意：工具搜索要求 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 工具输出强制分级上限：

最大输出上限可通过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 的额外开销：

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

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

工作机制：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%。

核心优势：

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

// 无代码执行 — 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 工具包，也能通过选择性暴露工具与类型化包装器抑制上下文膨胀：

安装方式：

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 如何选：判断矩阵

判断规则可归纳为：

• 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}" } } } }

2. 设置环境变量：

export GITHUB_TOKEN="your_github_personal_access_token"

3. 测试连接：

claude /mcp

4. 使用 MCP 工具：

/mcp__github__list_prs /mcp__github__create_issue "Title" "Description"

14.3 各服务的 npm 包安装

14.4 常见服务器一览

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-howtoA 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