⚡

MCP集成Skill MCPIntegration

这个技能用于指导如何将Model Context Protocol (MCP) 服务器集成到Claude Code插件中，以实现外部工具和服务的高效访问。它涵盖配置方法、服务器类型、认证模式、安全实践等，帮助开发者扩展插件功能。关键词：MCP, Model Context Protocol, 插件开发, 工具集成, 外部服务, Claude Code, 开发工具, DevOps, 软件集成。

DevOps 0 次安装 0 次浏览 更新于 3/13/2026

名称: MCP集成 描述: 这个技能应用于当用户请求“添加MCP服务器”、“集成MCP”、“在插件中配置MCP”、“使用.mcp.json”、“设置Model Context Protocol”、“连接外部服务”，提到“${CLAUDE_PLUGIN_ROOT}与MCP”，或讨论MCP服务器类型（SSE、stdio、HTTP、WebSocket）时。提供将Model Context Protocol服务器集成到Claude Code插件中用于外部工具和服务集成的全面指导。 版本: 0.1.0

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工具

在命令前置中预先允许特定的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中记录必需的env变量
  • ✅ 让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）
  • [ ] 类型特定字段完整（command或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 - 托管SSE服务器与OAuth
  • 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，对于支持OAuth的托管服务专注于SSE。