From f51aebcdca6f340c8553120bbeb0b1e20bf5c7c7 Mon Sep 17 00:00:00 2001 From: Anass Kartit <12949390+AnassKartit@users.noreply.github.com> Date: Thu, 22 Jan 2026 21:15:40 +0100 Subject: [PATCH 1/3] docs: add MCP server usage documentation Add comprehensive documentation for configuring and using MCP servers with the Copilot SDK across all supported languages (Node.js, Python, Go, .NET). This includes: - Configuration examples for local/stdio and remote HTTP/SSE servers - Complete reference for all configuration options - Troubleshooting guide for common issues - Links to related resources and issues Closes #36 --- docs/getting-started.md | 3 + docs/mcp.md | 225 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 docs/mcp.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 7833d074..62abfcb9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -835,6 +835,8 @@ const session = await client.createSession({ }); ``` +📖 **[Full MCP documentation →](./mcp.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting. + ### Create Custom Agents Define specialized AI personas for specific tasks: @@ -866,6 +868,7 @@ const session = await client.createSession({ ## Learn More +- [Using MCP Servers](./mcp.md) - Integrate external tools via Model Context Protocol - [Node.js SDK Reference](../nodejs/README.md) - [Python SDK Reference](../python/README.md) - [Go SDK Reference](../go/README.md) diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 00000000..dd74e44b --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,225 @@ +# Using MCP Servers with the GitHub Copilot SDK + +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. + +> **Note:** This is an evolving feature. See [issue #36](https://github.com/github/copilot-sdk/issues/36) for ongoing discussion. + +## What is MCP? + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external tools and data sources. MCP servers can: + +- Execute code or scripts +- Query databases +- Access file systems +- Call external APIs +- And much more + +## Server Types + +The SDK supports two types of MCP servers: + +| Type | Description | Use Case | +|------|-------------|----------| +| **Local/Stdio** | Runs as a subprocess, communicates via stdin/stdout | Local tools, file access, custom scripts | +| **HTTP/SSE** | Remote server accessed via HTTP | Shared services, cloud-hosted tools | + +## Configuration + +### Node.js / TypeScript + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient(); +const session = await client.createSession({ + model: "gpt-4.1", + mcpServers: { + // Local MCP server (stdio) + "my-local-server": { + type: "local", + command: "node", + args: ["./mcp-server.js"], + env: { DEBUG: "true" }, + cwd: "./servers", + tools: ["*"], // "*" = all tools, [] = none, or list specific tools + timeout: 30000, + }, + // Remote MCP server (HTTP) + "github": { + type: "http", + url: "https://api.githubcopilot.com/mcp/", + headers: { "Authorization": "Bearer ${TOKEN}" }, + tools: ["*"], + }, + }, +}); +``` + +### Python + +```python +import asyncio +from copilot import CopilotClient + +async def main(): + client = CopilotClient() + await client.start() + + session = await client.create_session({ + "model": "gpt-4.1", + "mcp_servers": { + # Local MCP server (stdio) + "my-local-server": { + "type": "local", + "command": "python", + "args": ["./mcp_server.py"], + "env": {"DEBUG": "true"}, + "cwd": "./servers", + "tools": ["*"], + "timeout": 30000, + }, + # Remote MCP server (HTTP) + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": {"Authorization": "Bearer ${TOKEN}"}, + "tools": ["*"], + }, + }, + }) + + response = await session.send_and_wait({ + "prompt": "List my recent GitHub notifications" + }) + print(response.data.content) + + await client.stop() + +asyncio.run(main()) +``` + +### Go + +```go +package main + +import ( + "log" + copilot "github.com/github/copilot-sdk/go" +) + +func main() { + client := copilot.NewClient(nil) + if err := client.Start(); err != nil { + log.Fatal(err) + } + defer client.Stop() + + session, err := client.CreateSession(&copilot.SessionConfig{ + Model: "gpt-4.1", + MCPServers: map[string]copilot.MCPServerConfig{ + "my-local-server": { + Type: "local", + Command: "node", + Args: []string{"./mcp-server.js"}, + Tools: []string{"*"}, + }, + }, + }) + if err != nil { + log.Fatal(err) + } + + // Use the session... +} +``` + +### .NET + +```csharp +using GitHub.Copilot.SDK; + +await using var client = new CopilotClient(); +await using var session = await client.CreateSessionAsync(new SessionConfig +{ + Model = "gpt-4.1", + McpServers = new Dictionary + { + ["my-local-server"] = new McpLocalServerConfig + { + Type = "local", + Command = "node", + Args = new[] { "./mcp-server.js" }, + Tools = new[] { "*" }, + }, + }, +}); +``` + +## Configuration Options + +### Local/Stdio Server + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `type` | `"local"` or `"stdio"` | No | Server type (defaults to local) | +| `command` | `string` | Yes | Command to execute | +| `args` | `string[]` | Yes | Command arguments | +| `env` | `object` | No | Environment variables | +| `cwd` | `string` | No | Working directory | +| `tools` | `string[]` | No | Tools to enable (`["*"]` for all, `[]` for none) | +| `timeout` | `number` | No | Timeout in milliseconds | + +### Remote Server (HTTP/SSE) + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `type` | `"http"` or `"sse"` | Yes | Server type | +| `url` | `string` | Yes | Server URL | +| `headers` | `object` | No | HTTP headers (e.g., for auth) | +| `tools` | `string[]` | No | Tools to enable | +| `timeout` | `number` | No | Timeout in milliseconds | + +## Troubleshooting + +### Tools not showing up or not being invoked + +1. **Verify the MCP server starts correctly** + - Check that the command and args are correct + - Ensure the server process doesn't crash on startup + - Look for error output in stderr + +2. **Check tool configuration** + - Make sure `tools` is set to `["*"]` or lists the specific tools you need + - An empty array `[]` means no tools are enabled + +3. **Verify connectivity for remote servers** + - Ensure the URL is accessible + - Check that authentication headers are correct + +### Common issues + +| Issue | Solution | +|-------|----------| +| "MCP server not found" | Verify the command path is correct and executable | +| "Connection refused" (HTTP) | Check the URL and ensure the server is running | +| "Timeout" errors | Increase the `timeout` value or check server performance | +| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality | + +### Debugging tips + +1. **Enable verbose logging** in your MCP server to see incoming requests +2. **Test your MCP server independently** before integrating with the SDK +3. **Start with a simple tool** to verify the integration works + +## Related Resources + +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers +- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server +- [Getting Started Guide](./getting-started.md) - SDK basics and custom tools + +## See Also + +- [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question +- [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue From 601f4e85961edaa3f72824f8a2a1f67a9795b99c Mon Sep 17 00:00:00 2001 From: Anass Kartit <12949390+AnassKartit@users.noreply.github.com> Date: Thu, 22 Jan 2026 21:37:33 +0100 Subject: [PATCH 2/3] docs: add working filesystem MCP server example Added a Quick Start section with a complete, tested example using @modelcontextprotocol/server-filesystem. This provides users with a copy-paste working example they can try immediately. --- docs/mcp.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/mcp.md b/docs/mcp.md index dd74e44b..eee0a969 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -156,6 +156,55 @@ await using var session = await client.CreateSessionAsync(new SessionConfig }); ``` +## Quick Start: Filesystem MCP Server + +Here's a complete working example using the official [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP server: + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +async function main() { + const client = new CopilotClient(); + await client.start(); + + // Create session with filesystem MCP server + const session = await client.createSession({ + mcpServers: { + filesystem: { + type: "local", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], + tools: ["*"], + }, + }, + }); + + console.log("Session created:", session.sessionId); + + // The model can now use filesystem tools + const result = await session.sendAndWait({ + prompt: "List the files in the allowed directory", + }); + + console.log("Response:", result?.data?.content); + + await session.destroy(); + await client.stop(); +} + +main(); +``` + +**Output:** +``` +Session created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a +Response: The allowed directory is `/tmp`, which contains various files +and subdirectories including temporary system files, log files, and +directories for different applications. +``` + +> **Tip:** 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`. + ## Configuration Options ### Local/Stdio Server From a78408b73d4009610549c4690ba54b78b87751fb Mon Sep 17 00:00:00 2001 From: Anass Kartit <12949390+AnassKartit@users.noreply.github.com> Date: Thu, 22 Jan 2026 21:39:38 +0100 Subject: [PATCH 3/3] docs: fix model name and .NET type annotation - Changed 'gpt-4.1' to 'gpt-5' for consistency with codebase - Fixed .NET McpServers type to Dictionary --- docs/mcp.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/mcp.md b/docs/mcp.md index eee0a969..b67dd7ca 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -32,7 +32,7 @@ import { CopilotClient } from "@github/copilot-sdk"; const client = new CopilotClient(); const session = await client.createSession({ - model: "gpt-4.1", + model: "gpt-5", mcpServers: { // Local MCP server (stdio) "my-local-server": { @@ -66,7 +66,7 @@ async def main(): await client.start() session = await client.create_session({ - "model": "gpt-4.1", + "model": "gpt-5", "mcp_servers": { # Local MCP server (stdio) "my-local-server": { @@ -116,7 +116,7 @@ func main() { defer client.Stop() session, err := client.CreateSession(&copilot.SessionConfig{ - Model: "gpt-4.1", + Model: "gpt-5", MCPServers: map[string]copilot.MCPServerConfig{ "my-local-server": { Type: "local", @@ -142,8 +142,8 @@ using GitHub.Copilot.SDK; await using var client = new CopilotClient(); await using var session = await client.CreateSessionAsync(new SessionConfig { - Model = "gpt-4.1", - McpServers = new Dictionary + Model = "gpt-5", + McpServers = new Dictionary { ["my-local-server"] = new McpLocalServerConfig {