⚡

MCP集成Skill mcp-integration

这个技能用于将Model Context Protocol (MCP) 集成到Claude Code插件中，实现与外部服务和API的连接，提供结构化工具访问和自动化功能。关键词包括MCP、Claude Code、插件开发、外部服务集成、API访问、工具管理、认证配置、服务器类型、SSE、stdio、HTTP、WebSocket。

后端开发 0 次安装 0 次浏览 更新于 3/16/2026

名称: mcp-integration 描述: 此技能应在用户询问"添加MCP服务器"、“集成MCP”、“在插件中配置MCP”、“使用.mcp.json”、“设置Model Context Protocol”、“连接外部服务”、提及"${CLAUDE_PLUGIN_ROOT}与MCP"或讨论MCP服务器类型（SSE、stdio、HTTP、WebSocket）时使用。为将Model Context Protocol服务器集成到Claude Code插件以进行外部工具和服务集成提供全面指导。

Claude Code插件的MCP集成

概述

Model Context Protocol (MCP) 使Claude Code插件能够通过提供结构化工具访问来与外部服务和API集成。使用MCP集成将外部服务功能暴露为Claude Code中的工具。

关键功能：

  • 连接到外部服务（数据库、API、文件系统）
  • 从一个服务提供10多个相关工具
  • 处理OAuth和复杂认证流程
  • 将MCP服务器捆绑到插件中以实现自动设置

MCP服务器配置方法

插件可以通过两种方式捆绑MCP服务器：

方法1：专用的.mcp.json（推荐）

在插件根目录创建.mcp.json：

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

优点：

  • 关注点清晰分离
  • 更易于维护
  • 更适合多个服务器

方法2：内联在plugin.json中

在plugin.json中添加mcpServers字段：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

优点：

  • 单个配置文件
  • 适合简单的单服务器插件

MCP服务器类型

stdio（本地进程）

将本地MCP服务器作为子进程执行。最适合本地工具和自定义服务器。

配置：

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

用例：

  • 文件系统访问
  • 本地数据库连接
  • 自定义MCP服务器
  • NPM打包的MCP服务器

进程管理：

  • Claude Code生成和管理进程
  • 通过stdin/stdout通信
  • 当Claude Code退出时终止

SSE（服务器发送事件）

连接到具有OAuth支持的托管MCP服务器。最适合云服务。

配置：

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

用例：

  • 官方托管的MCP服务器（Asana、GitHub等）
  • 具有MCP端点的云服务
  • 基于OAuth的认证
  • 无需本地安装

认证：

  • OAuth流程自动处理
  • 首次使用时提示用户
  • 令牌由Claude Code管理

HTTP（REST API）

连接到具有令牌认证的RESTful MCP服务器。

配置：

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

用例：

  • 基于REST API的MCP服务器
  • 基于令牌的认证
  • 自定义API后端
  • 无状态交互

WebSocket（实时）

连接到WebSocket MCP服务器以进行实时双向通信。

配置：

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

用例：

  • 实时数据流
  • 持久连接
  • 服务器推送通知
  • 低延迟要求

环境变量扩展

所有MCP配置都支持环境变量替换：

${CLAUDE_PLUGIN_ROOT} - 插件目录（始终使用以确保可移植性）：

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

用户环境变量 - 来自用户shell：

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

最佳实践： 在插件README中记录所有必需的环境变量。

MCP工具命名

当MCP服务器提供工具时，它们会自动添加前缀：

格式： mcp__plugin_<插件名称>_<服务器名称>__<工具名称>

示例：

  • 插件：asana
  • 服务器：asana
  • 工具：create_task
  • 全名： mcp__plugin_asana_asana__asana_create_task

在命令中使用MCP工具

在命令frontmatter中预先允许特定的MCP工具：

---
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

通配符（谨慎使用）：

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

最佳实践： 出于安全考虑，预先允许特定工具，而不是通配符。

生命周期管理

自动启动：

  • MCP服务器在插件启用时启动
  • 在首次使用工具前建立连接
  • 配置更改需要重启

生命周期：

  1. 插件加载
  2. 解析MCP配置
  3. 启动服务器进程（stdio）或建立连接（SSE/HTTP/WS）
  4. 发现并注册工具
  5. 工具可用为mcp__plugin_...__...

查看服务器： 使用/mcp命令查看所有服务器，包括插件提供的服务器。

认证模式

OAuth（SSE/HTTP）

OAuth由Claude Code自动处理：

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

用户首次使用时在浏览器中认证。无需额外配置。

基于令牌（头部）

静态或环境变量令牌：

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

在README中记录所需的环境变量。

环境变量（stdio）

将配置传递给MCP服务器：

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

集成模式

模式1：简单工具包装器

命令使用MCP工具与用户交互：

# 命令: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

步骤:
1. 从用户收集项目详情
2. 使用mcp__plugin_name_server__create_item
3. 确认创建

用于： 在MCP调用前添加验证或预处理。

模式2：自主代理

代理自主使用MCP工具：

# 代理: data-analyzer.md

分析过程:
1. 通过mcp__plugin_db_server__query查询数据
2. 处理和分析结果
3. 生成洞察报告

用于： 无需用户交互的多步骤MCP工作流。

模式3：多服务器插件

集成多个MCP服务器：

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "jira": {
    "type": "sse",
    "url": "https://mcp.jira.com/sse"
  }
}

用于： 跨越多个服务的工作流。

安全最佳实践

使用HTTPS/WSS

始终使用安全连接：

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

令牌管理

做：

  • ✅ 使用环境变量存储令牌
  • ✅ 在README中记录所需环境变量
  • ✅ 让OAuth流程处理认证

不做：

  • ❌ 在配置中硬编码令牌
  • ❌ 将令牌提交到git
  • ❌ 在文档中共享令牌

权限范围

预先允许仅必要的MCP工具：

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

错误处理

连接失败

处理MCP服务器不可用：

  • 在命令中提供回退行为
  • 通知用户连接问题
  • 检查服务器URL和配置

工具调用错误

处理失败的MCP操作：

  • 在调用MCP工具前验证输入
  • 提供清晰的错误消息
  • 检查速率限制和配额

配置错误

验证MCP配置：

  • 在开发期间测试服务器连接性
  • 验证JSON语法
  • 检查必需的环境变量

性能考虑

延迟加载

MCP服务器按需连接：

  • 并非所有服务器在启动时连接
  • 首次使用工具触发连接
  • 连接池自动管理

批处理

尽可能批量类似请求：

# 好： 带过滤器的单个查询
tasks = search_tasks(project="X", assignee="me", limit=50)

# 避免： 许多单独查询
for id in task_ids:
    task = get_task(id)

测试MCP集成

本地测试

  1. 在.mcp.json中配置MCP服务器
  2. 本地安装插件（.claude-plugin/）
  3. 运行/mcp以验证服务器出现
  4. 在命令中测试工具调用
  5. 检查claude --debug日志以查看连接问题

验证检查清单

  • [ ] MCP配置是有效的JSON
  • [ ] 服务器URL正确且可访问
  • [ ] 所需环境变量已记录
  • [ ] 工具出现在/mcp输出中
  • [ ] 认证工作（OAuth或令牌）
  • [ ] 工具调用从命令中成功
  • [ ] 错误情况得到优雅处理

调试

启用调试日志

claude --debug

查看：

  • MCP服务器连接尝试
  • 工具发现日志
  • 认证流程
  • 工具调用错误

常见问题

服务器未连接：

  • 检查URL是否正确
  • 验证服务器正在运行（stdio）
  • 检查网络连接性
  • 审查认证配置

工具不可用：

  • 验证服务器连接成功
  • 检查工具名称是否完全匹配
  • 运行/mcp以查看可用工具
  • 配置更改后重启Claude Code

认证失败：

  • 清除缓存的认证令牌
  • 重新认证
  • 检查令牌范围和权限
  • 验证环境变量已设置

快速参考

MCP服务器类型

类型 传输 最适合 认证
stdio 进程 本地工具，自定义服务器 环境变量
SSE HTTP 托管服务，云API OAuth
HTTP REST API后端，令牌认证 令牌
ws WebSocket 实时，流式传输 令牌

配置检查清单

  • [ ] 指定服务器类型（stdio/SSE/HTTP/ws）
  • [ ] 类型特定字段完整（命令或URL）
  • [ ] 认证已配置
  • [ ] 环境变量已记录
  • [ ] 使用HTTPS/WSS（不是HTTP/WS）
  • [ ] 使用${CLAUDE_PLUGIN_ROOT}表示路径

最佳实践

做：

  • ✅ 使用${CLAUDE_PLUGIN_ROOT}以确保可移植路径
  • ✅ 记录所需的环境变量
  • ✅ 使用安全连接（HTTPS/WSS）
  • ✅ 在命令中预先允许特定的MCP工具
  • ✅ 在发布前测试MCP集成
  • ✅ 优雅处理连接和工具错误

不做：

  • ❌ 硬编码绝对路径
  • ❌ 将凭据提交到git
  • ❌ 使用HTTP而不是HTTPS
  • ❌ 使用通配符预先允许所有工具
  • ❌ 跳过错误处理
  • ❌ 忘记记录设置

额外资源

参考文件

有关详细信息，请参阅：

  • references/server-types.md - 每种服务器类型的深入探讨
  • references/authentication.md - 认证模式和OAuth
  • references/tool-usage.md - 在命令和代理中使用MCP工具

示例配置

在examples/中的工作示例：

  • stdio-server.json - 本地stdio MCP服务器
  • sse-server.json - 带有OAuth的托管SSE服务器
  • http-server.json - 带有令牌认证的REST API

外部资源

实施工作流

要向插件添加MCP集成：

  1. 选择MCP服务器类型（stdio、SSE、HTTP、ws）
  2. 在插件根目录创建.mcp.json并进行配置
  3. 对所有文件引用使用${CLAUDE_PLUGIN_ROOT}
  4. 在README中记录所需的环境变量
  5. 使用/mcp命令本地测试
  6. 在相关命令中预先允许MCP工具
  7. 处理认证（OAuth或令牌）
  8. 测试错误情况（连接失败、认证错误）
  9. 在插件README中记录MCP集成

专注于stdio用于自定义/本地服务器，SSE用于带有OAuth的托管服务。