Skip to content

Commit 505b6b5

Browse files
AnassKartitpatniko
AnassKartit
and
patniko
authored
docs: add MCP server usage documentation (#98)
* 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: 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: fix model name and .NET type annotation - Changed 'gpt-4.1' to 'gpt-5' for consistency with codebase - Fixed .NET McpServers type to Dictionary<string, object> * Reorder MCP link --------- Co-authored-by: Patrick Nikoletich <patniko@github.com>
1 parent 6db2abf commit 505b6b5

2 files changed

Lines changed: 277 additions & 0 deletions

File tree

‎docs/getting-started.md‎

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

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

849851
Define specialized AI personas for specific tasks:
@@ -980,6 +982,7 @@ await using var session = await client.CreateSessionAsync();
980982
- [Python SDK Reference](../python/README.md)
981983
- [Go SDK Reference](../go/README.md)
982984
- [.NET SDK Reference](../dotnet/README.md)
985+
- [Using MCP Servers](./mcp.md) - Integrate external tools via Model Context Protocol
983986
- [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server)
984987
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Explore more MCP servers
985988

‎docs/mcp.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
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-5",
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-5",
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-5",
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-5",
146+
McpServers = new Dictionary<string, object>
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+
## Quick Start: Filesystem MCP Server
160+
161+
Here's a complete working example using the official [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP server:
162+
163+
```typescript
164+
import { CopilotClient } from "@github/copilot-sdk";
165+
166+
async function main() {
167+
const client = new CopilotClient();
168+
await client.start();
169+
170+
// Create session with filesystem MCP server
171+
const session = await client.createSession({
172+
mcpServers: {
173+
filesystem: {
174+
type: "local",
175+
command: "npx",
176+
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
177+
tools: ["*"],
178+
},
179+
},
180+
});
181+
182+
console.log("Session created:", session.sessionId);
183+
184+
// The model can now use filesystem tools
185+
const result = await session.sendAndWait({
186+
prompt: "List the files in the allowed directory",
187+
});
188+
189+
console.log("Response:", result?.data?.content);
190+
191+
await session.destroy();
192+
await client.stop();
193+
}
194+
195+
main();
196+
```
197+
198+
**Output:**
199+
```
200+
Session created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a
201+
Response: The allowed directory is `/tmp`, which contains various files
202+
and subdirectories including temporary system files, log files, and
203+
directories for different applications.
204+
```
205+
206+
> **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`.
207+
208+
## Configuration Options
209+
210+
### Local/Stdio Server
211+
212+
| Property | Type | Required | Description |
213+
|----------|------|----------|-------------|
214+
| `type` | `"local"` or `"stdio"` | No | Server type (defaults to local) |
215+
| `command` | `string` | Yes | Command to execute |
216+
| `args` | `string[]` | Yes | Command arguments |
217+
| `env` | `object` | No | Environment variables |
218+
| `cwd` | `string` | No | Working directory |
219+
| `tools` | `string[]` | No | Tools to enable (`["*"]` for all, `[]` for none) |
220+
| `timeout` | `number` | No | Timeout in milliseconds |
221+
222+
### Remote Server (HTTP/SSE)
223+
224+
| Property | Type | Required | Description |
225+
|----------|------|----------|-------------|
226+
| `type` | `"http"` or `"sse"` | Yes | Server type |
227+
| `url` | `string` | Yes | Server URL |
228+
| `headers` | `object` | No | HTTP headers (e.g., for auth) |
229+
| `tools` | `string[]` | No | Tools to enable |
230+
| `timeout` | `number` | No | Timeout in milliseconds |
231+
232+
## Troubleshooting
233+
234+
### Tools not showing up or not being invoked
235+
236+
1. **Verify the MCP server starts correctly**
237+
- Check that the command and args are correct
238+
- Ensure the server process doesn't crash on startup
239+
- Look for error output in stderr
240+
241+
2. **Check tool configuration**
242+
- Make sure `tools` is set to `["*"]` or lists the specific tools you need
243+
- An empty array `[]` means no tools are enabled
244+
245+
3. **Verify connectivity for remote servers**
246+
- Ensure the URL is accessible
247+
- Check that authentication headers are correct
248+
249+
### Common issues
250+
251+
| Issue | Solution |
252+
|-------|----------|
253+
| "MCP server not found" | Verify the command path is correct and executable |
254+
| "Connection refused" (HTTP) | Check the URL and ensure the server is running |
255+
| "Timeout" errors | Increase the `timeout` value or check server performance |
256+
| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |
257+
258+
### Debugging tips
259+
260+
1. **Enable verbose logging** in your MCP server to see incoming requests
261+
2. **Test your MCP server independently** before integrating with the SDK
262+
3. **Start with a simple tool** to verify the integration works
263+
264+
## Related Resources
265+
266+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
267+
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers
268+
- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
269+
- [Getting Started Guide](./getting-started.md) - SDK basics and custom tools
270+
271+
## See Also
272+
273+
- [Issue #9](https://github.com/github/copilot-sdk/issues/9) - Original MCP tools usage question
274+
- [Issue #36](https://github.com/github/copilot-sdk/issues/36) - MCP documentation tracking issue

0 commit comments

Comments
 (0)