{"meta":{"title":"Using MCP servers with the GitHub Copilot SDK","intro":"The Copilot SDK can integrate with MCP servers (Model Context Protocol) to extend the assistant's capabilities with external tools. MCP servers run as separate processes and expose tools (functions) that Copilot can invoke during conversations.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos","title":"How-tos"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp","title":"MCP"}],"documentType":"article"},"body":"# Using MCP servers with the GitHub Copilot SDK\n\nThe Copilot SDK can integrate with MCP servers (Model Context Protocol) to extend the assistant's capabilities with external tools. MCP servers run as separate processes and expose tools (functions) that Copilot can invoke during conversations.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n> \\[!NOTE]\n> This is an evolving feature. See [issue #36](https://github.com/github/copilot-sdk/issues/36) for ongoing discussion.\n\n## What is MCP?\n\n[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external tools and data sources. MCP servers can:\n\n* Execute code or scripts\n* Query databases\n* Access file systems\n* Call external APIs\n* And much more\n\n## Server types\n\nThe SDK supports two types of MCP servers:\n\n| Type            | Description                                         | Use Case                                 |\n| --------------- | --------------------------------------------------- | ---------------------------------------- |\n| **Local/Stdio** | Runs as a subprocess, communicates via stdin/stdout | Local tools, file access, custom scripts |\n| **HTTP/SSE**    | Remote server accessed via HTTP                     | Shared services, cloud-hosted tools      |\n\n## Configuration\n\n### Node.js / TypeScript\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nconst session = await client.createSession({\n    model: \"gpt-5\",\n    mcpServers: {\n        // Local MCP server (stdio)\n        \"my-local-server\": {\n            type: \"local\",\n            command: \"node\",\n            args: [\"./mcp-server.js\"],\n            env: { DEBUG: \"true\" },\n            cwd: \"./servers\",\n            tools: [\"*\"],  // \"*\" = all tools, [] = none, or list specific tools\n            timeout: 30000,\n        },\n        // Remote MCP server (HTTP)\n        \"github\": {\n            type: \"http\",\n            url: \"https://api.githubcopilot.com/mcp/\",\n            headers: { \"Authorization\": \"Bearer ${TOKEN}\" },\n            tools: [\"*\"],\n        },\n    },\n});\n```\n\n### Python\n\n```python\nimport asyncio\nfrom copilot import CopilotClient\nfrom copilot.session import PermissionHandler\n\nasync def main():\n    client = CopilotClient()\n    await client.start()\n\n    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5\", mcp_servers={\n        # Local MCP server (stdio)\n        \"my-local-server\": {\n            \"type\": \"local\",\n            \"command\": \"python\",\n            \"args\": [\"./mcp_server.py\"],\n            \"env\": {\"DEBUG\": \"true\"},\n            \"cwd\": \"./servers\",\n            \"tools\": [\"*\"],\n            \"timeout\": 30000,\n        },\n        # Remote MCP server (HTTP)\n        \"github\": {\n            \"type\": \"http\",\n            \"url\": \"https://api.githubcopilot.com/mcp/\",\n            \"headers\": {\"Authorization\": \"Bearer ${TOKEN}\"},\n            \"tools\": [\"*\"],\n        },\n    })\n\n    response = await session.send_and_wait(\"List my recent GitHub notifications\")\n    print(response.data.content)\n\n    await client.stop()\n\nasyncio.run(main())\n```\n\n### Go\n\n```golang\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    copilot \"github.com/github/copilot-sdk/go\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    client := copilot.NewClient(nil)\n    if err := client.Start(ctx); err != nil {\n        log.Fatal(err)\n    }\n    defer client.Stop()\n\n    session, err := client.CreateSession(ctx, &copilot.SessionConfig{\n        Model: \"gpt-5\",\n        MCPServers: map[string]copilot.MCPServerConfig{\n            \"my-local-server\": copilot.MCPStdioServerConfig{\n                Command: \"node\",\n                Args:    []string{\"./mcp-server.js\"},\n                Tools:   []string{\"*\"},\n            },\n        },\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer session.Disconnect()\n\n    // Use the session...\n}\n```\n\n### .NET\n\n```csharp\nusing GitHub.Copilot;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    Model = \"gpt-5\",\n    McpServers = new Dictionary<string, McpServerConfig>\n    {\n        [\"my-local-server\"] = new McpStdioServerConfig\n        {\n            Command = \"node\",\n            Args = new List<string> { \"./mcp-server.js\" },\n            Tools = new List<string> { \"*\" },\n        },\n    },\n});\n```\n\n## Disabling configured servers per session\n\nSet `disabledMcpServers` to exact MCP server names that must not run in a session.\nThe setting is scoped to the individual create or resume request; it does not\nmodify global MCP settings or the server configuration.\n\n```typescript\nconst session = await client.createSession({\n    mcpServers: {\n        filesystem: { type: \"local\", command: \"npx\", args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"] },\n        github: { type: \"http\", url: \"https://api.githubcopilot.com/mcp/\" },\n    },\n    disabledMcpServers: [\"github\"],\n});\n```\n\n| SDK     | Configuration property           |\n| ------- | -------------------------------- |\n| Node.js | `disabledMcpServers`             |\n| Python  | `disabled_mcp_servers`           |\n| Go      | `DisabledMCPServers`             |\n| .NET    | `DisabledMcpServers`             |\n| Java    | `setDisabledMcpServers(...)`     |\n| Rust    | `with_disabled_mcp_servers(...)` |\n\nOn session creation and a **cold** resume, disabled servers are not started and\nthe runtime does not initiate their authentication. A resident resume cannot\nundo a server that the runtime has already spawned. Names are matched exactly.\n\n## Tool configuration\n\nYou can control which tools are available to an MCP server using the `tools` field.\n\n### Allow all tools\n\nUse `\"*\"` to enable all tools provided by the MCP server:\n\n```typescript\ntools: [\"*\"]\n```\n\n### Allow specific tools\n\nProvide a list of tool names to restrict access:\n\n```typescript\ntools: [\"bash\", \"edit\"]\n```\n\nOnly the listed tools will be available to the agent.\n\n### Disable all tools\n\nUse an empty array to disable all tools:\n\n```typescript\ntools: []\n```\n\n### Notes\n\n* The `tools` field defines which tools are allowed.\n* There is no separate `allow` or `disallow` configuration—tool access is controlled directly through this list.\n\n## Quick start: filesystem MCP server\n\nHere's a complete working example using the official [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP server:\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nasync function main() {\n    const client = new CopilotClient();\n\n    // Create session with filesystem MCP server\n    const session = await client.createSession({\n        mcpServers: {\n            filesystem: {\n                type: \"local\",\n                command: \"npx\",\n                args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"],\n                tools: [\"*\"],\n            },\n        },\n    });\n\n    console.log(\"Session created:\", session.sessionId);\n\n    // The model can now use filesystem tools\n    const result = await session.sendAndWait({\n        prompt: \"List the files in the allowed directory\",\n    });\n\n    console.log(\"Response:\", result?.data?.content);\n\n    await session.disconnect();\n    await client.stop();\n}\n\nmain();\n```\n\n**Output:**\n\n```text\nSession created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a\nResponse: The allowed directory is `/tmp`, which contains various files\nand subdirectories including temporary system files, log files, and\ndirectories for different applications.\n```\n\n> \\[!TIP]\n> You can use any MCP server from the [MCP Servers Directory](https://github.com/modelcontextprotocol/servers). Popular options include `@modelcontextprotocol/server-github`, `@modelcontextprotocol/server-sqlite`, and `@modelcontextprotocol/server-puppeteer`.\n\n## Configuration options\n\n### Local/stdio server\n\n| Property  | Type                   | Required | Description                                      |\n| --------- | ---------------------- | -------- | ------------------------------------------------ |\n| `type`    | `\"local\"` or `\"stdio\"` | No       | Server type (defaults to local)                  |\n| `command` | `string`               | Yes      | Command to execute                               |\n| `args`    | `string[]`             | Yes      | Command arguments                                |\n| `env`     | `object`               | No       | Environment variables                            |\n| `cwd`     | `string`               | No       | Working directory                                |\n| `tools`   | `string[]`             | No       | Tools to enable (`[\"*\"]` for all, `[]` for none) |\n| `timeout` | `number`               | No       | Timeout in milliseconds                          |\n\n### Remote server (HTTP/SSE)\n\n| Property  | Type                | Required | Description                   |\n| --------- | ------------------- | -------- | ----------------------------- |\n| `type`    | `\"http\"` or `\"sse\"` | Yes      | Server type                   |\n| `url`     | `string`            | Yes      | Server URL                    |\n| `headers` | `object`            | No       | HTTP headers (e.g., for auth) |\n| `tools`   | `string[]`          | No       | Tools to enable               |\n| `timeout` | `number`            | No       | Timeout in milliseconds       |\n\n## Troubleshooting\n\n### Tools not showing up or not being invoked\n\n1. **Verify the MCP server starts correctly**\n   * Check that the command and args are correct\n   * Ensure the server process doesn't crash on startup\n   * Look for error output in stderr\n\n2. **Check tool configuration**\n   * Make sure `tools` is set to `[\"*\"]` or lists the specific tools you need\n   * An empty array `[]` means no tools are enabled\n\n3. **Verify connectivity for remote servers**\n   * Ensure the URL is accessible\n   * Check that authentication headers are correct\n\n### Common issues\n\n| Issue                        | Solution                                                     |\n| ---------------------------- | ------------------------------------------------------------ |\n| \"MCP server not found\"       | Verify the command path is correct and executable            |\n| \"Connection refused\" (HTTP)  | Check the URL and ensure the server is running               |\n| \"Timeout\" errors             | Increase the `timeout` value or check server performance     |\n| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |\n\nFor detailed debugging guidance, see the **[MCP server debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)**.\n\n## Related resources\n\n* [Model Context Protocol Specification](https://modelcontextprotocol.io/)\n* [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers\n* [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server\n* [Build your first Copilot-powered app](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started) - SDK basics and custom tools\n* [Debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - SDK-wide debugging\n\n## See also\n\n* [MCP server debugging guide](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - Detailed MCP troubleshooting\n* [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question\n* [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue"}