Claude Code MCP Server 集成全解析

Claude Code MCP Server Integration 深度解析

作为 AI 前端架构师，本文将从架构设计、协议原理、配置实践到安全模型，系统梳理 Claude Code 的 MCP Server Integration 全貌。

一、什么是 MCP？

MCP（Model Context Protocol） 是一套标准化协议，允许 Claude Code 与外部服务器通信，从而调用外部工具、获取资源、执行提示模板。它的核心价值在于：无需在 Claude Code 内置每一种集成，而是通过统一协议对接任意外部系统 （GitHub、数据库、Slack、自定义 API 等）。 1

二、整体架构

MCP 集成由三个主要层次构成：
#mermaid-svg-bBJY8ZwfgPnjtddF{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bBJY8ZwfgPnjtddF .error-icon{fill:#552222;}#mermaid-svg-bBJY8ZwfgPnjtddF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bBJY8ZwfgPnjtddF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bBJY8ZwfgPnjtddF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bBJY8ZwfgPnjtddF .marker.cross{stroke:#333333;}#mermaid-svg-bBJY8ZwfgPnjtddF svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bBJY8ZwfgPnjtddF p{margin:0;}#mermaid-svg-bBJY8ZwfgPnjtddF .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster-label text{fill:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster-label span{color:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster-label span p{background-color:transparent;}#mermaid-svg-bBJY8ZwfgPnjtddF .label text,#mermaid-svg-bBJY8ZwfgPnjtddF span{fill:#333;color:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF .node rect,#mermaid-svg-bBJY8ZwfgPnjtddF .node circle,#mermaid-svg-bBJY8ZwfgPnjtddF .node ellipse,#mermaid-svg-bBJY8ZwfgPnjtddF .node polygon,#mermaid-svg-bBJY8ZwfgPnjtddF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bBJY8ZwfgPnjtddF .rough-node .label text,#mermaid-svg-bBJY8ZwfgPnjtddF .node .label text,#mermaid-svg-bBJY8ZwfgPnjtddF .image-shape .label,#mermaid-svg-bBJY8ZwfgPnjtddF .icon-shape .label{text-anchor:middle;}#mermaid-svg-bBJY8ZwfgPnjtddF .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bBJY8ZwfgPnjtddF .rough-node .label,#mermaid-svg-bBJY8ZwfgPnjtddF .node .label,#mermaid-svg-bBJY8ZwfgPnjtddF .image-shape .label,#mermaid-svg-bBJY8ZwfgPnjtddF .icon-shape .label{text-align:center;}#mermaid-svg-bBJY8ZwfgPnjtddF .node.clickable{cursor:pointer;}#mermaid-svg-bBJY8ZwfgPnjtddF .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bBJY8ZwfgPnjtddF .arrowheadPath{fill:#333333;}#mermaid-svg-bBJY8ZwfgPnjtddF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bBJY8ZwfgPnjtddF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bBJY8ZwfgPnjtddF .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bBJY8ZwfgPnjtddF .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bBJY8ZwfgPnjtddF .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bBJY8ZwfgPnjtddF .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster text{fill:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF .cluster span{color:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-bBJY8ZwfgPnjtddF .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bBJY8ZwfgPnjtddF rect.text{fill:none;stroke-width:0;}#mermaid-svg-bBJY8ZwfgPnjtddF .icon-shape,#mermaid-svg-bBJY8ZwfgPnjtddF .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bBJY8ZwfgPnjtddF .icon-shape p,#mermaid-svg-bBJY8ZwfgPnjtddF .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bBJY8ZwfgPnjtddF .icon-shape .label rect,#mermaid-svg-bBJY8ZwfgPnjtddF .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bBJY8ZwfgPnjtddF .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bBJY8ZwfgPnjtddF .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bBJY8ZwfgPnjtddF :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 外部 MCP 服务器
MCP 基础设施层
Claude Code 核心
用户请求层
查询注册表
调用工具
协议 RPC
上下文 > 10%
用户自然语言请求
Agent System
Tool Executor
Permission Classifier
MCPSearch Tool

(动态工具发现)
配置注册表

~/.claude/mcp-servers.json

.claude/mcp-servers.json

.mcp.json
Connection Manager

(管理活跃连接)
Transport Layer

(stdio / SSE / HTTP / WS)
本地 stdio 进程

(GitHub, 自定义工具)
远程 SSE 服务

(Slack + OAuth)
claude.ai MCP Connectors

(远程托管服务器)

三、四种传输协议详解

Claude Code 支持四种传输机制，选择依据是服务的部署形态：

传输类型	协议	适用场景	进程管理
stdio	本地标准输入/输出	本地工具、自定义脚本	Claude Code 负责子进程生命周期
SSE	Server-Sent Events	云端托管服务	自动处理 OAuth，断线自动重连
HTTP	REST API	无状态交互	标准 HTTP 头部鉴权
WebSocket	双向实时通信	低延迟场景	持久连接，支持 `wss://`

配置 Schema 与传输类型的映射关系

#mermaid-svg-DoamfbDml7jFyFOU{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-DoamfbDml7jFyFOU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-DoamfbDml7jFyFOU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-DoamfbDml7jFyFOU .error-icon{fill:#552222;}#mermaid-svg-DoamfbDml7jFyFOU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-DoamfbDml7jFyFOU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-DoamfbDml7jFyFOU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-DoamfbDml7jFyFOU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-DoamfbDml7jFyFOU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-DoamfbDml7jFyFOU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-DoamfbDml7jFyFOU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-DoamfbDml7jFyFOU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-DoamfbDml7jFyFOU .marker.cross{stroke:#333333;}#mermaid-svg-DoamfbDml7jFyFOU svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-DoamfbDml7jFyFOU p{margin:0;}#mermaid-svg-DoamfbDml7jFyFOU .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-DoamfbDml7jFyFOU .cluster-label text{fill:#333;}#mermaid-svg-DoamfbDml7jFyFOU .cluster-label span{color:#333;}#mermaid-svg-DoamfbDml7jFyFOU .cluster-label span p{background-color:transparent;}#mermaid-svg-DoamfbDml7jFyFOU .label text,#mermaid-svg-DoamfbDml7jFyFOU span{fill:#333;color:#333;}#mermaid-svg-DoamfbDml7jFyFOU .node rect,#mermaid-svg-DoamfbDml7jFyFOU .node circle,#mermaid-svg-DoamfbDml7jFyFOU .node ellipse,#mermaid-svg-DoamfbDml7jFyFOU .node polygon,#mermaid-svg-DoamfbDml7jFyFOU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-DoamfbDml7jFyFOU .rough-node .label text,#mermaid-svg-DoamfbDml7jFyFOU .node .label text,#mermaid-svg-DoamfbDml7jFyFOU .image-shape .label,#mermaid-svg-DoamfbDml7jFyFOU .icon-shape .label{text-anchor:middle;}#mermaid-svg-DoamfbDml7jFyFOU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-DoamfbDml7jFyFOU .rough-node .label,#mermaid-svg-DoamfbDml7jFyFOU .node .label,#mermaid-svg-DoamfbDml7jFyFOU .image-shape .label,#mermaid-svg-DoamfbDml7jFyFOU .icon-shape .label{text-align:center;}#mermaid-svg-DoamfbDml7jFyFOU .node.clickable{cursor:pointer;}#mermaid-svg-DoamfbDml7jFyFOU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-DoamfbDml7jFyFOU .arrowheadPath{fill:#333333;}#mermaid-svg-DoamfbDml7jFyFOU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-DoamfbDml7jFyFOU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-DoamfbDml7jFyFOU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DoamfbDml7jFyFOU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-DoamfbDml7jFyFOU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DoamfbDml7jFyFOU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-DoamfbDml7jFyFOU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-DoamfbDml7jFyFOU .cluster text{fill:#333;}#mermaid-svg-DoamfbDml7jFyFOU .cluster span{color:#333;}#mermaid-svg-DoamfbDml7jFyFOU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-DoamfbDml7jFyFOU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-DoamfbDml7jFyFOU rect.text{fill:none;stroke-width:0;}#mermaid-svg-DoamfbDml7jFyFOU .icon-shape,#mermaid-svg-DoamfbDml7jFyFOU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DoamfbDml7jFyFOU .icon-shape p,#mermaid-svg-DoamfbDml7jFyFOU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-DoamfbDml7jFyFOU .icon-shape .label rect,#mermaid-svg-DoamfbDml7jFyFOU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DoamfbDml7jFyFOU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-DoamfbDml7jFyFOU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-DoamfbDml7jFyFOU :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 传输参数
配置文件
mcp-servers.json / .mcp.json
command + args + env

→ stdio
type: sse + url

→ SSE + OAuth
type: http + url + headers

→ HTTP REST
type: ws + url

→ WebSocket

stdio 配置示例：

json 复制代码

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

SSE 配置示例（带 OAuth）：

json 复制代码

{
  "mcpServers": {
    "slack": {
      "type": "sse",
      "url": "https://mcp.slack.com/sse"
    }
  }
}

HTTP 配置示例（带自定义 Header）：

json 复制代码

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

所有配置均支持环境变量展开，如 ${GITHUB_TOKEN}、${CLAUDE_PROJECT_DIR} 等。

四、配置作用域与优先级

MCP 服务器配置有三个作用域，优先级从高到低：
#mermaid-svg-qIqjMW9McSZehW10{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-qIqjMW9McSZehW10 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-qIqjMW9McSZehW10 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-qIqjMW9McSZehW10 .error-icon{fill:#552222;}#mermaid-svg-qIqjMW9McSZehW10 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qIqjMW9McSZehW10 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-qIqjMW9McSZehW10 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qIqjMW9McSZehW10 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qIqjMW9McSZehW10 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-qIqjMW9McSZehW10 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qIqjMW9McSZehW10 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qIqjMW9McSZehW10 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qIqjMW9McSZehW10 .marker.cross{stroke:#333333;}#mermaid-svg-qIqjMW9McSZehW10 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qIqjMW9McSZehW10 p{margin:0;}#mermaid-svg-qIqjMW9McSZehW10 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-qIqjMW9McSZehW10 .cluster-label text{fill:#333;}#mermaid-svg-qIqjMW9McSZehW10 .cluster-label span{color:#333;}#mermaid-svg-qIqjMW9McSZehW10 .cluster-label span p{background-color:transparent;}#mermaid-svg-qIqjMW9McSZehW10 .label text,#mermaid-svg-qIqjMW9McSZehW10 span{fill:#333;color:#333;}#mermaid-svg-qIqjMW9McSZehW10 .node rect,#mermaid-svg-qIqjMW9McSZehW10 .node circle,#mermaid-svg-qIqjMW9McSZehW10 .node ellipse,#mermaid-svg-qIqjMW9McSZehW10 .node polygon,#mermaid-svg-qIqjMW9McSZehW10 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qIqjMW9McSZehW10 .rough-node .label text,#mermaid-svg-qIqjMW9McSZehW10 .node .label text,#mermaid-svg-qIqjMW9McSZehW10 .image-shape .label,#mermaid-svg-qIqjMW9McSZehW10 .icon-shape .label{text-anchor:middle;}#mermaid-svg-qIqjMW9McSZehW10 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-qIqjMW9McSZehW10 .rough-node .label,#mermaid-svg-qIqjMW9McSZehW10 .node .label,#mermaid-svg-qIqjMW9McSZehW10 .image-shape .label,#mermaid-svg-qIqjMW9McSZehW10 .icon-shape .label{text-align:center;}#mermaid-svg-qIqjMW9McSZehW10 .node.clickable{cursor:pointer;}#mermaid-svg-qIqjMW9McSZehW10 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-qIqjMW9McSZehW10 .arrowheadPath{fill:#333333;}#mermaid-svg-qIqjMW9McSZehW10 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qIqjMW9McSZehW10 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qIqjMW9McSZehW10 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qIqjMW9McSZehW10 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-qIqjMW9McSZehW10 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qIqjMW9McSZehW10 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-qIqjMW9McSZehW10 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qIqjMW9McSZehW10 .cluster text{fill:#333;}#mermaid-svg-qIqjMW9McSZehW10 .cluster span{color:#333;}#mermaid-svg-qIqjMW9McSZehW10 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qIqjMW9McSZehW10 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-qIqjMW9McSZehW10 rect.text{fill:none;stroke-width:0;}#mermaid-svg-qIqjMW9McSZehW10 .icon-shape,#mermaid-svg-qIqjMW9McSZehW10 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qIqjMW9McSZehW10 .icon-shape p,#mermaid-svg-qIqjMW9McSZehW10 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-qIqjMW9McSZehW10 .icon-shape .label rect,#mermaid-svg-qIqjMW9McSZehW10 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qIqjMW9McSZehW10 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-qIqjMW9McSZehW10 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-qIqjMW9McSZehW10 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 企业管理设置

(managed-settings.json)

最高优先级
用户级

~/.claude/mcp-servers.json

全局生效
项目级

.claude/mcp-servers.json 或 .mcp.json

可提交到 Git 仓库
插件捆绑

plugin.json 内 mcpServers 字段

或独立 .mcp.json

用户级：个人工具，不随项目分发
项目级：团队共享，可提交到版本控制，新成员 clone 后即可使用
插件捆绑 ：插件可通过独立 .mcp.json（推荐，关注点分离）或 plugin.json 内联 mcpServers 字段声明

五、工具发现与命名规范

注册流程

"MCP Server" "Connection Manager" "Claude Code" "MCP Server" "Connection Manager" "Claude Code" #mermaid-svg-LQyoDPfk3jI9jmDM{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-LQyoDPfk3jI9jmDM .error-icon{fill:#552222;}#mermaid-svg-LQyoDPfk3jI9jmDM .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-LQyoDPfk3jI9jmDM .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-LQyoDPfk3jI9jmDM .marker{fill:#333333;stroke:#333333;}#mermaid-svg-LQyoDPfk3jI9jmDM .marker.cross{stroke:#333333;}#mermaid-svg-LQyoDPfk3jI9jmDM svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-LQyoDPfk3jI9jmDM p{margin:0;}#mermaid-svg-LQyoDPfk3jI9jmDM .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LQyoDPfk3jI9jmDM text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-LQyoDPfk3jI9jmDM .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-LQyoDPfk3jI9jmDM .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-LQyoDPfk3jI9jmDM #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-LQyoDPfk3jI9jmDM .sequenceNumber{fill:white;}#mermaid-svg-LQyoDPfk3jI9jmDM #sequencenumber{fill:#333;}#mermaid-svg-LQyoDPfk3jI9jmDM #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-LQyoDPfk3jI9jmDM .messageText{fill:#333;stroke:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LQyoDPfk3jI9jmDM .labelText,#mermaid-svg-LQyoDPfk3jI9jmDM .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .loopText,#mermaid-svg-LQyoDPfk3jI9jmDM .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-LQyoDPfk3jI9jmDM .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-LQyoDPfk3jI9jmDM .noteText,#mermaid-svg-LQyoDPfk3jI9jmDM .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-LQyoDPfk3jI9jmDM .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LQyoDPfk3jI9jmDM .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LQyoDPfk3jI9jmDM .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LQyoDPfk3jI9jmDM .actorPopupMenu{position:absolute;}#mermaid-svg-LQyoDPfk3jI9jmDM .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-LQyoDPfk3jI9jmDM .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LQyoDPfk3jI9jmDM .actor-man circle,#mermaid-svg-LQyoDPfk3jI9jmDM line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-LQyoDPfk3jI9jmDM :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 工具可用于 Agent 调用解析配置文件建立连接 (stdio spawn / HTTP connect) 返回工具列表 (tools/list) 注册工具（带命名空间前缀）调用工具 (tools/call) 返回结果

工具命名格式

为避免名称冲突，所有 MCP 工具自动添加命名空间前缀：

复制代码

mcp__plugin_<plugin-name>_<server-name>__<tool-name>

例如：mcp__plugin_asana_asana__create_task

动态工具搜索（MCPSearch）

当 MCP 工具描述超过上下文窗口的 10% 时，Claude Code 自动启用 MCPSearch 工具进行按需发现，而非一次性加载所有工具 schema，显著降低 token 消耗。

可通过 auto:N 语法自定义阈值（N 为 0-100 的百分比），或设置 alwaysLoad: true 让特定服务器的工具始终可用，跳过延迟加载。

六、认证体系

Claude Code 支持三种认证模式，覆盖主流场景：

OAuth 关键特性：

首次使用时自动弹出浏览器授权页
Token 在过期前主动刷新，避免中断
支持 oauth.authServerMetadataUrl 自定义授权服务器（兼容 ADFS 等企业 IdP）
多实例并发刷新时有跨进程锁保护，防止 Token 竞争覆盖 10 11

七、权限与安全模型

MCP 工具与 Claude Code 内置工具共享同一套权限系统：

权限规则配置

json 复制代码

{
  "permissions": {
    "allow": [
      "mcp__plugin_asana_asana__create_task",
      "mcp__plugin_github_github__*"
    ],
    "deny": [
      "mcp__plugin_dangerous_server__delete_*"
    ]
  }
}

精确匹配：指定完整工具名，避免重复授权提示
通配符匹配 ：mcp__server__* 允许/拒绝某服务器的所有工具
待审批状态 ：来自未批准 .mcp.json 的服务器显示为 Pending approval，需用户明确同意后才建立连接 12

企业管控

企业可通过 managed-settings.json 配置 MCP 服务器的允许列表 和拒绝列表 ，集中管控哪些 MCP 服务器可以被使用。 13

八、管理命令速查

命令	用途
`/mcp`	交互式管理面板：查看状态、重连、启用/禁用
`claude mcp list`	列出所有服务器及状态（含配置错误提示）
`claude mcp get <name>`	查看指定服务器详情
`claude mcp add`	交互式向导添加新服务器
`claude mcp add-from-claude-desktop`	从 Claude Desktop 导入配置
`--mcp-debug`	启动时开启 MCP 调试日志
`MCP_TIMEOUT`	环境变量，配置服务器启动超时
`MCP_TOOL_TIMEOUT`	环境变量，配置单次工具调用超时

九、高级特性与最佳实践

1. 非阻塞连接模式

在 -p（headless）模式下，可设置 MCP_CONNECTION_NONBLOCKING=true 完全跳过 MCP 连接等待，适合 CI/CD 场景。 16

2. 大输出截断控制

通过 _meta["anthropic/maxResultSizeChars"] 注解（最大 500K），可让数据库 Schema 等大型结果绕过默认截断限制。 17

3. Hooks 与 MCP 联动

PostToolUse Hook 可拦截并替换 MCP 工具的输出，实现结果后处理（如格式转换、敏感信息脱敏）。Hooks 也可以直接通过 type: "mcp_tool" 调用 MCP 工具。 18

4. 子 Agent 继承

子 Agent 自动继承主 Agent 的 MCP 工具，无需重复配置。Agent frontmatter 中的 mcpServers 字段也会在主线程 Agent 会话中加载。 19

5. claude.ai 连接器

Claude Code 支持直接使用 claude.ai 账户中配置的远程 MCP 连接器，无需本地重复配置。注意：当设置了 ANTHROPIC_API_KEY 时，claude.ai 连接器会被自动禁用。 20

十、常见问题排查

现象	原因	解决方案
服务器卡在 `connecting`	启动超时或配置错误	检查 `MCP_TIMEOUT`，用 `--mcp-debug` 查看详细日志
工具调用返回 401	OAuth Token 过期	`/mcp` → Reconnect 重新授权
工具在第一轮不可用	异步连接未完成	设置 `alwaysLoad: true` 或等待连接完成
stdio 参数被截断	Shell 前缀与特殊字符冲突	升级到 v2.1.127+，已修复此问题
10+ 服务器时静默退出	缓存目录不可写	检查 `~/.claude/` 目录权限

总结

Claude Code 的 MCP Server Integration 是一套设计完善的可扩展工具协议层，其核心设计哲学是：

标准化：统一协议对接任意外部系统，无需内置集成
分层配置：用户/项目/插件三级作用域，灵活适配个人与团队场景
安全优先：权限系统、OAuth 自动刷新、企业管控一体化
性能感知：MCPSearch 动态发现机制，避免大量工具 schema 占用上下文

对于前端架构师而言，MCP 的价值在于它将 AI 能力的扩展边界从"模型能做什么"推向了"任何有 API 的系统都能成为 AI 的工具"，这是构建企业级 AI 工作流的关键基础设施。