Skip to content

Commit bd0bd16

Browse files
AnassKartitclaude
AnassKartit
and
claude
committed
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 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 1f06cf5 commit bd0bd16

2 files changed

Lines changed: 228 additions & 0 deletions

File tree

‎docs/getting-started.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -835,6 +835,8 @@ const session = await client.createSession({
835835
});
836836
```
837837

838+
📖 **[Full MCP documentation →](./mcp.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
839+
838840
### Create Custom Agents
839841

840842
Define specialized AI personas for specific tasks:
@@ -866,6 +868,7 @@ const session = await client.createSession({
866868

867869
## Learn More
868870

871+
- [Using MCP Servers](./mcp.md) - Integrate external tools via Model Context Protocol
869872
- [Node.js SDK Reference](../nodejs/README.md)
870873
- [Python SDK Reference](../python/README.md)
871874
- [Go SDK Reference](../go/README.md)

‎docs/mcp.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Using MCP Servers with the GitHub Copilot SDK
2+
3+
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.
4+
5+
> **Note:** This is an evolving feature. See [issue #36](https://github.com/github/copilot-sdk/issues/36) for ongoing discussion.
6+
7+
## What is MCP?
8+
9+
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external tools and data sources. MCP servers can:
10+
11+
- Execute code or scripts
12+
- Query databases
13+
- Access file systems
14+
- Call external APIs
15+
- And much more
16+
17+
## Server Types
18+
19+
The SDK supports two types of MCP servers:
20+
21+
| Type | Description | Use Case |
22+
|------|-------------|----------|
23+
| **Local/Stdio** | Runs as a subprocess, communicates via stdin/stdout | Local tools, file access, custom scripts |
24+
| **HTTP/SSE** | Remote server accessed via HTTP | Shared services, cloud-hosted tools |
25+
26+
## Configuration
27+
28+
### Node.js / TypeScript
29+
30+
```typescript
31+
import { CopilotClient } from "@github/copilot-sdk";
32+
33+
const client = new CopilotClient();
34+
const session = await client.createSession({
35+
model: "gpt-4.1",
36+
mcpServers: {
37+
// Local MCP server (stdio)
38+
"my-local-server": {
39+
type: "local",
40+
command: "node",
41+
args: ["./mcp-server.js"],
42+
env: { DEBUG: "true" },
43+
cwd: "./servers",
44+
tools: ["*"], // "*" = all tools, [] = none, or list specific tools
45+
timeout: 30000,
46+
},
47+
// Remote MCP server (HTTP)
48+
"github": {
49+
type: "http",
50+
url: "https://api.githubcopilot.com/mcp/",
51+
headers: { "Authorization": "Bearer ${TOKEN}" },
52+
tools: ["*"],
53+
},
54+
},
55+
});
56+
```
57+
58+
### Python
59+
60+
```python
61+
import asyncio
62+
from copilot import CopilotClient
63+
64+
async def main():
65+
client = CopilotClient()
66+
await client.start()
67+
68+
session = await client.create_session({
69+
"model": "gpt-4.1",
70+
"mcp_servers": {
71+
# Local MCP server (stdio)
72+
"my-local-server": {
73+
"type": "local",
74+
"command": "python",
75+
"args": ["./mcp_server.py"],
76+
"env": {"DEBUG": "true"},
77+
"cwd": "./servers",
78+
"tools": ["*"],
79+
"timeout": 30000,
80+
},
81+
# Remote MCP server (HTTP)
82+
"github": {
83+
"type": "http",
84+
"url": "https://api.githubcopilot.com/mcp/",
85+
"headers": {"Authorization": "Bearer ${TOKEN}"},
86+
"tools": ["*"],
87+
},
88+
},
89+
})
90+
91+
response = await session.send_and_wait({
92+
"prompt": "List my recent GitHub notifications"
93+
})
94+
print(response.data.content)
95+
96+
await client.stop()
97+
98+
asyncio.run(main())
99+
```
100+
101+
### Go
102+
103+
```go
104+
package main
105+
106+
import (
107+
"log"
108+
copilot "github.com/github/copilot-sdk/go"
109+
)
110+
111+
func main() {
112+
client := copilot.NewClient(nil)
113+
if err := client.Start(); err != nil {
114+
log.Fatal(err)
115+
}
116+
defer client.Stop()
117+
118+
session, err := client.CreateSession(&copilot.SessionConfig{
119+
Model: "gpt-4.1",
120+
MCPServers: map[string]copilot.MCPServerConfig{
121+
"my-local-server": {
122+
Type: "local",
123+
Command: "node",
124+
Args: []string{"./mcp-server.js"},
125+
Tools: []string{"*"},
126+
},
127+
},
128+
})
129+
if err != nil {
130+
log.Fatal(err)
131+
}
132+
133+
// Use the session...
134+
}
135+
```
136+
137+
### .NET
138+
139+
```csharp
140+
using GitHub.Copilot.SDK;
141+
142+
await using var client = new CopilotClient();
143+
await using var session = await client.CreateSessionAsync(new SessionConfig
144+
{
145+
Model = "gpt-4.1",
146+
McpServers = new Dictionary<string, McpServerConfig>
147+
{
148+
["my-local-server"] = new McpLocalServerConfig
149+
{
150+
Type = "local",
151+
Command = "node",
152+
Args = new[] { "./mcp-server.js" },
153+
Tools = new[] { "*" },
154+
},
155+
},
156+
});
157+
```
158+
159+
## Configuration Options
160+
161+
### Local/Stdio Server
162+
163+
| Property | Type | Required | Description |
164+
|----------|------|----------|-------------|
165+
| `type` | `"local"` or `"stdio"` | No | Server type (defaults to local) |
166+
| `command` | `string` | Yes | Command to execute |
167+
| `args` | `string[]` | Yes | Command arguments |
168+
| `env` | `object` | No | Environment variables |
169+
| `cwd` | `string` | No | Working directory |
170+
| `tools` | `string[]` | No | Tools to enable (`["*"]` for all, `[]` for none) |
171+
| `timeout` | `number` | No | Timeout in milliseconds |
172+
173+
### Remote Server (HTTP/SSE)
174+
175+
| Property | Type | Required | Description |
176+
|----------|------|----------|-------------|
177+
| `type` | `"http"` or `"sse"` | Yes | Server type |
178+
| `url` | `string` | Yes | Server URL |
179+
| `headers` | `object` | No | HTTP headers (e.g., for auth) |
180+
| `tools` | `string[]` | No | Tools to enable |
181+
| `timeout` | `number` | No | Timeout in milliseconds |
182+
183+
## Troubleshooting
184+
185+
### Tools not showing up or not being invoked
186+
187+
1. **Verify the MCP server starts correctly**
188+
- Check that the command and args are correct
189+
- Ensure the server process doesn't crash on startup
190+
- Look for error output in stderr
191+
192+
2. **Check tool configuration**
193+
- Make sure `tools` is set to `["*"]` or lists the specific tools you need
194+
- An empty array `[]` means no tools are enabled
195+
196+
3. **Verify connectivity for remote servers**
197+
- Ensure the URL is accessible
198+
- Check that authentication headers are correct
199+
200+
### Common issues
201+
202+
| Issue | Solution |
203+
|-------|----------|
204+
| "MCP server not found" | Verify the command path is correct and executable |
205+
| "Connection refused" (HTTP) | Check the URL and ensure the server is running |
206+
| "Timeout" errors | Increase the `timeout` value or check server performance |
207+
| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |
208+
209+
### Debugging tips
210+
211+
1. **Enable verbose logging** in your MCP server to see incoming requests
212+
2. **Test your MCP server independently** before integrating with the SDK
213+
3. **Start with a simple tool** to verify the integration works
214+
215+
## Related Resources
216+
217+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
218+
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers
219+
- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
220+
- [Getting Started Guide](./getting-started.md) - SDK basics and custom tools
221+
222+
## See Also
223+
224+
- [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question
225+
- [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue

0 commit comments

Comments
 (0)