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.mdModel Context Protocol 专题文档基于 Claude Code v2.1.119 整理系统讲解如何在 Claude Code 中接入、管理与扩展 MCPModel 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 的本质区别MCPModel Context Protocol是 Claude 访问外部工具、API 与实时数据源的标准方式。与 Memory记忆不同MCP 提供的是对不断变化数据的实时访问。其主要特征包括对外部服务的实时访问Real-time access实时数据同步Live data synchronization可扩展架构Extensible architecture安全认证Secure authentication基于工具的交互Tool-based interactions1.1 架构请求-查询-响应三段链路从源码文档给出的架构图看一次 MCP 交互遵循「Claude → MCP Server → 外部服务」的三段链路请求/响应模式上MCP 强调实时访问、不做缓存。以数据库为例1.2 生态全景一个 Claude 连接多个 MCP ServerClaude 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-token2.2 Stdio 传输本地服务器适用于本地运行的 MCP 服务器Node.js 等# 本地 Node.js 服务器 claude mcp add --transport stdio myserver -- npx myorg/mcp-server # 带环境变量 claude mcp add --transport stdio myserver --env KEYvalue -- npx server2.3 SSE 传输已弃用但仍受支持Server-Sent Events 传输因http的推出而被标记为弃用但仍可继续使用claude mcp add --transport sse legacy-server https://example.com/sse2.4 Windows 平台的注意事项原生 Windows非 WSL下npx 命令需要通过cmd /c调用claude mcp add --transport stdio my-server -- cmd /c npx -y some/package3. 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 8080OAuth 能力矩阵能力说明交互式 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设为falseENABLE_CLAUDEAI_MCP_SERVERSfalse 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-desktop5. 作用域ScopeLocal / Project / UserMCP 配置可以保存在不同的共享级别通过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-memory5.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— 列出仓库内所有 PRget_pr— 获取含 diff 的 PR 详情create_pr— 创建新 PRupdate_pr— 更新 PR 描述/标题merge_pr— 将 PR 合并到 mainreview_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, charlieIssue 管理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_TOKENyour_github_token # 或通过 CLI 直接添加: claude mcp add --transport stdio github -- npx modelcontextprotocol/server-github6.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: Ill 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_URLpostgresql://user:passlocalhost/mydb # 或通过 CLI 直接添加: claude mcp add --transport stdio database -- npx modelcontextprotocol/server-database6.3 示例三多 MCP 协作日报工作流场景每日报表生成组合四个 MCP——GitHubPR 指标、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_TOKENyour_github_token export DATABASE_URLpostgresql://user:passlocalhost/mydb export SLACK_TOKENyour_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/projects7. 环境变量与配置展开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_TOKENghp_xxxxxxxxxxxxx export DATABASE_URLpostgresql://user:passlocalhost/mydb export SLACK_TOKENxoxb-xxxxxxxxxxxxx{ env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } }8. 上下文效率机制工具搜索、动态更新与输出上限8.1 MCP 工具搜索Tool Search当 MCP 工具描述占上下文窗口超过 10% 时Claude Code 会自动启用工具搜索在不挤占模型上下文的前提下高效挑选合适的工具。设置值说明ENABLE_TOOL_SEARCHauto默认工具描述超过上下文 10% 时自动启用ENABLE_TOOL_SEARCHauto:N以自定义工具数量阈值N自动启用ENABLE_TOOL_SEARCHtrue无论工具数量多少始终启用ENABLE_TOOL_SEARCHfalse禁用所有工具描述按全量发送注意工具搜索要求 Sonnet 4 及以上或 Opus 4 及以上模型Haiku 模型不支持工具搜索。8.2 动态工具更新list_changedClaude Code 支持 MCP 的list_changed通知MCP 服务器动态增删改工具时Claude Code 会收到更新并自动调整工具列表无需重连或重启。8.3 工具描述与指令的 2 KB 上限自 v2.1.84 起Claude Code 对每个 MCP 服务器的工具描述与指令强制2 KB 上限防止单个服务器用冗长的工具定义过度消耗上下文控制上下文膨胀、保持对话高效。8.4 MCP Apps 与 ElicitationMCP Apps首个官方 MCP 扩展允许 MCP 工具调用直接返回在聊天界面内渲染的交互式 UI 组件——服务器可以在对话内联呈现丰富的仪表盘、表单、数据可视化与多步工作流而不只是纯文本响应。MCP Elicitationv2.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_TOKENS500009. 提示词、资源引用与「反向」MCP9.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 serveClaude 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. 企业管控、插件与子代理级 MCP10.1 托管 MCP 配置Enterprise企业部署中IT 管理员可通过managed-mcp.json强制 MCP 服务器策略对组织范围内允许/禁止的 MCP 服务器进行独占控制。部署位置macOS:/Library/Application Support/ClaudeCode/managed-mcp.jsonLinux:~/.config/ClaudeCode/managed-mcp.jsonWindows:%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 服务器安装插件后自动可用有两种定义方式独立.mcp.json— 放在插件根目录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 子代理作用域的 MCPMCP 服务器可以在智能体 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 ): PromiseGetDocumentResponse { return callMCPToolGetDocumentResponse( 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 MCPorterMCP 工具编排运行时MCPorter 是一个让 MCP 服务器调用「去样板化」的 TypeScript 运行时与 CLI 工具包也能通过选择性暴露工具与类型化包装器抑制上下文膨胀功能说明零配置发现自动从 Cursor、Claude、Codex、本地配置中发现 MCP 服务器类型化工具客户端mcporter emit-ts生成.d.ts接口与开箱即用的包装器可配置 APIcreateServerProxy()把工具暴露为 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 listMCPorter 与前述代码执行方案互补为「以类型化 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 配置最佳实践版本管理.mcp.json存进 git秘密走环境变量最小权限每个 MCP 服务器只授予必需权限隔离尽量让不同 MCP 服务器跑在不同进程监控为审计留痕记录所有 MCP 请求与错误测试生产部署前测试所有 MCP 配置13.3 性能提示高频访问数据在应用层缓存使用特定化的 MCP 查询减少数据量监控 MCP 操作响应时间对外部 API 考虑速率限制多操作时优先批处理14. 从零开始安装与排错14.1 前提条件已安装 Node.js 与 npm已安装 Claude Code CLI拥有外部服务的 API token/凭据14.2 分步配置添加第一个 MCP 服务器如 GitHubclaude mcp add --transport stdio github -- npx modelcontextprotocol/server-github或在项目根目录创建.mcp.json{ mcpServers: { github: { command: npx, args: [modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } } } }设置环境变量export GITHUB_TOKENyour_github_personal_access_token测试连接claude /mcp使用 MCP 工具/mcp__github__list_prs /mcp__github__create_issue Title Description14.3 各服务的 npm 包安装服务安装命令GitHub MCPnpm install -g modelcontextprotocol/server-githubDatabase MCPnpm install -g modelcontextprotocol/server-databaseFilesystem MCPnpm install -g modelcontextprotocol/server-filesystemSlack MCPnpm install -g modelcontextprotocol/server-slack14.4 常见服务器一览MCP 服务器用途常见工具认证实时Filesystem文件操作read、write、deleteOS 权限是GitHub仓库管理list_prs、create_issue、pushOAuth是Slack团队沟通send_message、list_channelsToken是DatabaseSQL 查询query、insert、update凭据是Google Docs文档访问read、write、shareOAuth是Asana项目管理create_task、update_statusAPI key是Stripe支付数据list_charges、create_invoiceAPI 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_TOKENyour_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 4oauth.authServerMetadataUrl需要 v2.1.64MCP 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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.mdModel Context Protocol 专题文档基于 Claude Code v2.1.119 整理系统讲解如何在 Claude Code 中接入、管理与扩展 MCPModel 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 的本质区别MCPModel Context Protocol是 Claude 访问外部工具、API 与实时数据源的标准方式。与 Memory记忆不同MCP 提供的是对不断变化数据的实时访问。其主要特征包括对外部服务的实时访问Real-time access实时数据同步Live data synchronization可扩展架构Extensible architecture安全认证Secure authentication基于工具的交互Tool-based interactions1.1 架构请求-查询-响应三段链路从源码文档给出的架构图看一次 MCP 交互遵循「Claude → MCP Server → 外部服务」的三段链路请求/响应模式上MCP 强调实时访问、不做缓存。以数据库为例1.2 生态全景一个 Claude 连接多个 MCP ServerClaude 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-token2.2 Stdio 传输本地服务器适用于本地运行的 MCP 服务器Node.js 等# 本地 Node.js 服务器 claude mcp add --transport stdio myserver -- npx myorg/mcp-server # 带环境变量 claude mcp add --transport stdio myserver --env KEYvalue -- npx server2.3 SSE 传输已弃用但仍受支持Server-Sent Events 传输因http的推出而被标记为弃用但仍可继续使用claude mcp add --transport sse legacy-server https://example.com/sse2.4 Windows 平台的注意事项原生 Windows非 WSL下npx 命令需要通过cmd /c调用claude mcp add --transport stdio my-server -- cmd /c npx -y some/package3. 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 8080OAuth 能力矩阵能力说明交互式 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设为falseENABLE_CLAUDEAI_MCP_SERVERSfalse 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-desktop5. 作用域ScopeLocal / Project / UserMCP 配置可以保存在不同的共享级别通过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-memory5.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— 列出仓库内所有 PRget_pr— 获取含 diff 的 PR 详情create_pr— 创建新 PRupdate_pr— 更新 PR 描述/标题merge_pr— 将 PR 合并到 mainreview_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, charlieIssue 管理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_TOKENyour_github_token # 或通过 CLI 直接添加: claude mcp add --transport stdio github -- npx modelcontextprotocol/server-github6.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: Ill 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_URLpostgresql://user:passlocalhost/mydb # 或通过 CLI 直接添加: claude mcp add --transport stdio database -- npx modelcontextprotocol/server-database6.3 示例三多 MCP 协作日报工作流场景每日报表生成组合四个 MCP——GitHubPR 指标、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_TOKENyour_github_token export DATABASE_URLpostgresql://user:passlocalhost/mydb export SLACK_TOKENyour_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/projects7. 环境变量与配置展开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_TOKENghp_xxxxxxxxxxxxx export DATABASE_URLpostgresql://user:passlocalhost/mydb export SLACK_TOKENxoxb-xxxxxxxxxxxxx{ env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } }8. 上下文效率机制工具搜索、动态更新与输出上限8.1 MCP 工具搜索Tool Search当 MCP 工具描述占上下文窗口超过 10% 时Claude Code 会自动启用工具搜索在不挤占模型上下文的前提下高效挑选合适的工具。设置值说明ENABLE_TOOL_SEARCHauto默认工具描述超过上下文 10% 时自动启用ENABLE_TOOL_SEARCHauto:N以自定义工具数量阈值N自动启用ENABLE_TOOL_SEARCHtrue无论工具数量多少始终启用ENABLE_TOOL_SEARCHfalse禁用所有工具描述按全量发送注意工具搜索要求 Sonnet 4 及以上或 Opus 4 及以上模型Haiku 模型不支持工具搜索。8.2 动态工具更新list_changedClaude Code 支持 MCP 的list_changed通知MCP 服务器动态增删改工具时Claude Code 会收到更新并自动调整工具列表无需重连或重启。8.3 工具描述与指令的 2 KB 上限自 v2.1.84 起Claude Code 对每个 MCP 服务器的工具描述与指令强制2 KB 上限防止单个服务器用冗长的工具定义过度消耗上下文控制上下文膨胀、保持对话高效。8.4 MCP Apps 与 ElicitationMCP Apps首个官方 MCP 扩展允许 MCP 工具调用直接返回在聊天界面内渲染的交互式 UI 组件——服务器可以在对话内联呈现丰富的仪表盘、表单、数据可视化与多步工作流而不只是纯文本响应。MCP Elicitationv2.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_TOKENS500009. 提示词、资源引用与「反向」MCP9.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 serveClaude 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. 企业管控、插件与子代理级 MCP10.1 托管 MCP 配置Enterprise企业部署中IT 管理员可通过managed-mcp.json强制 MCP 服务器策略对组织范围内允许/禁止的 MCP 服务器进行独占控制。部署位置macOS:/Library/Application Support/ClaudeCode/managed-mcp.jsonLinux:~/.config/ClaudeCode/managed-mcp.jsonWindows:%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 服务器安装插件后自动可用有两种定义方式独立.mcp.json— 放在插件根目录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 子代理作用域的 MCPMCP 服务器可以在智能体 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 ): PromiseGetDocumentResponse { return callMCPToolGetDocumentResponse( 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 MCPorterMCP 工具编排运行时MCPorter 是一个让 MCP 服务器调用「去样板化」的 TypeScript 运行时与 CLI 工具包也能通过选择性暴露工具与类型化包装器抑制上下文膨胀功能说明零配置发现自动从 Cursor、Claude、Codex、本地配置中发现 MCP 服务器类型化工具客户端mcporter emit-ts生成.d.ts接口与开箱即用的包装器可配置 APIcreateServerProxy()把工具暴露为 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 listMCPorter 与前述代码执行方案互补为「以类型化 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 配置最佳实践版本管理.mcp.json存进 git秘密走环境变量最小权限每个 MCP 服务器只授予必需权限隔离尽量让不同 MCP 服务器跑在不同进程监控为审计留痕记录所有 MCP 请求与错误测试生产部署前测试所有 MCP 配置13.3 性能提示高频访问数据在应用层缓存使用特定化的 MCP 查询减少数据量监控 MCP 操作响应时间对外部 API 考虑速率限制多操作时优先批处理14. 从零开始安装与排错14.1 前提条件已安装 Node.js 与 npm已安装 Claude Code CLI拥有外部服务的 API token/凭据14.2 分步配置添加第一个 MCP 服务器如 GitHubclaude mcp add --transport stdio github -- npx modelcontextprotocol/server-github或在项目根目录创建.mcp.json{ mcpServers: { github: { command: npx, args: [modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } } } }设置环境变量export GITHUB_TOKENyour_github_personal_access_token测试连接claude /mcp使用 MCP 工具/mcp__github__list_prs /mcp__github__create_issue Title Description14.3 各服务的 npm 包安装服务安装命令GitHub MCPnpm install -g modelcontextprotocol/server-githubDatabase MCPnpm install -g modelcontextprotocol/server-databaseFilesystem MCPnpm install -g modelcontextprotocol/server-filesystemSlack MCPnpm install -g modelcontextprotocol/server-slack14.4 常见服务器一览MCP 服务器用途常见工具认证实时Filesystem文件操作read、write、deleteOS 权限是GitHub仓库管理list_prs、create_issue、pushOAuth是Slack团队沟通send_message、list_channelsToken是DatabaseSQL 查询query、insert、update凭据是Google Docs文档访问read、write、shareOAuth是Asana项目管理create_task、update_statusAPI key是Stripe支付数据list_charges、create_invoiceAPI 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_TOKENyour_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 4oauth.authServerMetadataUrl需要 v2.1.64MCP 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
