Copilot SDK 通过 MCP 协议接入外部工具服务器，分本地（Stdio 子进程）和远程（HTTP/SSE）两种方式。配置时指定 type、command/url、arguments、环境变量和允许的工具列表。本地 MCP 服务器在应用启动时作为子进程运行，通过 stdin/stdout 通信。

GitHub Copilot SDK 接入 MCP 服务器：扩展 AI 工具能力

什么是 MCP

MCP（Model Context Protocol）是一个开放协议，定义了 AI 模型与外部工具/数据源之间的通信标准。通过 MCP，Copilot SDK 中的 Agent 可以：

• 执行脚本或命令
• 查询数据库
• 读写文件系统
• 调用外部 API
• 访问知识库

MCP 服务器独立运行，SDK 通过协议调用，工具逻辑与 AI 逻辑解耦。

本地 MCP 服务器（Stdio）

本地 MCP 服务器作为子进程运行，通过 stdin/stdout 通信：

import { createSession } from '@github/copilot-sdk'

const session = await createSession({
  mcpServers: [
    {
      name: 'filesystem',
      type: 'local',            // 本地 Stdio 模式
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
      env: {
        // 可以传递环境变量给 MCP 服务器进程
        MAX_FILE_SIZE: '10mb'
      },
      tools: ['read_file', 'write_file', 'list_directory']  // 只允许这些工具
    }
  ]
})

常用的本地 MCP 服务器：

• @modelcontextprotocol/server-filesystem：文件系统操作
• @modelcontextprotocol/server-git：Git 操作
• @modelcontextprotocol/server-sqlite：SQLite 数据库查询

远程 MCP 服务器（HTTP/SSE）

通过 HTTP 访问远程 MCP 服务：

const session = await createSession({
  mcpServers: [
    {
      name: 'github-api',
      type: 'remote',           // 远程 HTTP/SSE 模式
      url: 'https://your-mcp-server.com/sse',
      headers: {
        'Authorization': `Bearer ${process.env.MCP_TOKEN}`
      },
      tools: ['search_issues', 'create_pr', 'list_repos']
    }
  ]
})

限制允许的工具

tools 数组控制 Agent 可以调用哪些工具，不在列表中的工具不会暴露给 AI。这是关键的安全机制：

mcpServers: [
  {
    name: 'filesystem',
    type: 'local',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
    // 只读：允许读取和列目录，不允许写入和删除
    tools: ['read_file', 'list_directory', 'search_files']
  }
]

同时使用多个 MCP 服务器

const session = await createSession({
  mcpServers: [
    {
      name: 'filesystem',
      type: 'local',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace'],
    },
    {
      name: 'database',
      type: 'local',
      command: 'node',
      args: ['./mcp-servers/db-server.js'],
      env: { DATABASE_URL: process.env.DATABASE_URL }
    },
    {
      name: 'external-api',
      type: 'remote',
      url: 'https://api.company.com/mcp/sse',
      headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
    }
  ]
})

排查 MCP 连接问题

本地 MCP 服务器无响应：

# 手动测试命令是否能运行
npx -y @modelcontextprotocol/server-filesystem /workspace

# 检查是否有权限访问指定目录
ls -la /workspace

远程 MCP 服务器连接失败：

# 测试 SSE 端点连通性
curl -N -H "Authorization: Bearer your-token" https://your-mcp-server.com/sse

工具调用失败：

• 确认工具名称在 tools 数组中（大小写敏感）
• 检查 MCP 服务器的工具列表与 SDK 配置是否匹配

常见问题

Q: 如何开发自己的 MCP 服务器？

A: 参考 Model Context Protocol 规范，有 TypeScript 和 Python 的官方 SDK。本地 Stdio 服务器是最简单的起点：实现 ListTools 和 CallTool 两个 RPC 方法即可。

Q: MCP 服务器能访问 Session 的上下文吗？

A: 不能直接访问。MCP 服务器是独立进程，通过工具调用接收参数，不共享 Session 的对话历史。如果需要传递上下文，通过工具参数显式传入。

Q: 远程 MCP 服务器的安全注意事项？

A: 远程服务器 URL 不要硬编码在代码中；敏感 headers（如 Authorization）从环境变量读取；对 MCP 服务器返回的数据做必要的验证，避免注入风险。