Skip to content

Commit 4e11a0e

Browse files
JailiorJailior
committed
docs: add MCP usage documentation and language specific examples
1 parent f28a23e commit 4e11a0e

6 files changed

Lines changed: 407 additions & 0 deletions

File tree

‎docs/getting-started.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -830,10 +830,13 @@ const session = await client.createSession({
830830
github: {
831831
type: "http",
832832
url: "https://api.githubcopilot.com/mcp/",
833+
tools: ["*"]
833834
},
834835
},
835836
});
836837
```
838+
Learn more about MCP server usage: [Using MCP servers with the Copilot SDK](./mcp-usage.md)
839+
837840

838841
### Create Custom Agents
839842

‎docs/mcp-usage.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# Using MCP servers with the Copilot SDK
2+
3+
This document shows how to configure MCP (Model Context Protocol) servers for sessions in each client SDK supported by this repository.
4+
5+
### What is MCP?
6+
- MCP servers expose pre-built tools and resources (for example, GitHub MCP Server provides tools for issues, PRs, and repositories).
7+
- You can configure local (stdio/local) or remote (HTTP/SSE) MCP servers and make them available to sessions.
8+
9+
### Common concepts
10+
- `mcpServers` is the session-level configuration that maps server name to server configuration.
11+
- Server config has two broad shapes:
12+
- **Local/stdio servers**: `type: "local" | "stdio"`, `command`, `args`, `env`, `cwd`
13+
- `type`: Defaults to `"local"` if not specified
14+
- `command`: The executable to run (e.g., `"node"`, `"python"`)
15+
- `args`: Arguments to pass to the command
16+
- `env`: Optional environment variables for the process
17+
- `cwd`: Optional working directory for the process
18+
- **Remote servers**: `type: "http" | "sse"`, `url`, `headers`
19+
- `type`: Either `"http"` or `"sse"` (Server-Sent Events)
20+
- `url`: The endpoint URL of the MCP server
21+
- `headers`: Optional HTTP headers for authentication
22+
- `tools`: Array of tool names to expose from the server (use `["*"]` for all tools, `[]` for none)
23+
24+
### Examples
25+
26+
Below are examples for configuring both local and remote MCP servers:
27+
28+
<details>
29+
<summary><strong>Node.js / TypeScript</strong></summary>
30+
31+
```ts
32+
import { CopilotClient, type MCPLocalServerConfig, type MCPRemoteServerConfig } from "@github/copilot-sdk";
33+
34+
const client = new CopilotClient();
35+
await client.start();
36+
37+
const session = await client.createSession({
38+
mcpServers: {
39+
"github": {
40+
type: "http",
41+
url: "https://api.githubcopilot.com/mcp/",
42+
tools: ["github-repos", "github-pull-requests"],
43+
headers: { Authorization: "Bearer <token>" },
44+
} as MCPRemoteServerConfig,
45+
"local-tools": {
46+
type: "local",
47+
command: "node",
48+
args: ["./local-mcp-server.js"],
49+
tools: ["my-tool"],
50+
env: { "DEBUG": "1" },
51+
} as MCPLocalServerConfig,
52+
},
53+
});
54+
55+
// Wait for response using session.idle event
56+
const done = new Promise<void>((resolve) => {
57+
session.on((event) => {
58+
if (event.type === "assistant.message") {
59+
console.log(event.data.content);
60+
} else if (event.type === "session.idle") {
61+
resolve();
62+
}
63+
});
64+
});
65+
66+
// Send a message and wait for completion
67+
await session.send({ prompt: "Use the GitHub MCP Server tools to fetch PR data" });
68+
await done;
69+
70+
await session.destroy();
71+
await client.stop();
72+
```
73+
74+
</details>
75+
76+
<details>
77+
<summary><strong>Python</strong></summary>
78+
79+
```python
80+
import asyncio
81+
from copilot import CopilotClient
82+
83+
async def main():
84+
client = CopilotClient()
85+
await client.start()
86+
87+
session = await client.create_session({
88+
"mcp_servers": {
89+
"github": {
90+
"type": "http",
91+
"url": "https://api.githubcopilot.com/mcp/",
92+
"tools": ["github-repos", "github-pull-requests"],
93+
"headers": {"Authorization": "Bearer <token>"},
94+
},
95+
"local-tools": {
96+
"type": "local",
97+
"command": "echo",
98+
"args": ["hello"],
99+
"tools": ["*"],
100+
"env": {"DEBUG": "1"},
101+
}
102+
}
103+
})
104+
105+
done = asyncio.Event()
106+
107+
await session.send({"prompt": "Use the GitHub MCP Server tools to fetch PR data"})
108+
await done.wait()
109+
110+
await session.destroy()
111+
await client.stop()
112+
113+
asyncio.run(main())
114+
```
115+
116+
</details>
117+
118+
119+
<details>
120+
<summary><strong>Go</strong></summary>
121+
122+
```go
123+
package main
124+
125+
import (
126+
"fmt"
127+
"log"
128+
129+
copilot "github.com/github/copilot-sdk/go"
130+
)
131+
132+
func main() {
133+
client := copilot.NewClient(nil)
134+
135+
if err := client.Start(); err != nil {
136+
log.Fatal(err)
137+
}
138+
defer client.Stop()
139+
140+
mcpServers := map[string]copilot.MCPServerConfig{
141+
"github": {
142+
"type": "http",
143+
"url": "https://api.githubcopilot.com/mcp/",
144+
"tools": []string{"github-repos", "github-pull-requests"},
145+
"headers": map[string]string{
146+
"Authorization": "Bearer <token>",
147+
},
148+
},
149+
"local-tools": {
150+
"type": "local",
151+
"command": "echo",
152+
"args": []string{"hello"},
153+
"tools": []string{"*"},
154+
"env": map[string]string{"DEBUG": "1"},
155+
},
156+
}
157+
158+
session, err := client.CreateSession(&copilot.SessionConfig{
159+
MCPServers: mcpServers,
160+
})
161+
if err != nil {
162+
log.Fatalf("Failed to create session: %v", err)
163+
}
164+
defer session.Destroy()
165+
166+
_, err = session.Send(copilot.MessageOptions{
167+
Prompt: "Use the GitHub MCP Server tools to fetch PR data",
168+
})
169+
if err != nil {
170+
log.Fatal(err)
171+
}
172+
}
173+
```
174+
175+
</details>
176+
177+
<details>
178+
<summary><strong>.NET</strong></summary>
179+
180+
```csharp
181+
using GitHub.Copilot.SDK;
182+
183+
await using var client = new CopilotClient();
184+
await client.StartAsync();
185+
186+
var mcpServers = new Dictionary<string, object>
187+
{
188+
["github"] = new McpRemoteServerConfig
189+
{
190+
Type = "http",
191+
Url = "https://api.githubcopilot.com/mcp/",
192+
Tools = new[] { "github-repos", "github-pull-requests" },
193+
Headers = new Dictionary<string, string>
194+
{
195+
["Authorization"] = "Bearer <token>"
196+
}
197+
},
198+
["local-tools"] = new McpLocalServerConfig
199+
{
200+
Type = "local",
201+
Command = "echo",
202+
Args = new[] { "hello" },
203+
Tools = new[] { "*" },
204+
Env = new Dictionary<string, string> { ["DEBUG"] = "1" }
205+
}
206+
};
207+
208+
await using var session = await client.CreateSessionAsync(new SessionConfig
209+
{
210+
McpServers = mcpServers
211+
});
212+
213+
var done = new TaskCompletionSource();
214+
215+
await session.SendAsync(new MessageOptions { Prompt = "What is 2+2?" });
216+
await done.Task;
217+
218+
await session.DisposeAsync();
219+
```
220+
221+
</details>
222+
223+
<br>
224+
225+
> Note that the **GitHub MCP server** is **already configured** as part of Copilot CLI and the SDK,
226+
so configuring it explicitly is not necessary.
227+
228+
229+
### Notes and tips
230+
231+
#### Configuration best practices:
232+
- When adding remote MCP servers, prefer using service tokens or environment-based secrets rather than hard-coding tokens in samples.
233+
- For local servers, document any required dependencies and how to run them (e.g., `npm install` then `node server.js`).
234+
- Always call `session.destroy()` or `await session.DisposeAsync()` when finished with a session to clean up resources.
235+
236+
237+
#### Session resumption with MCP servers:
238+
- You can also configure or add MCP servers when resuming a session:
239+
240+
241+
<details>
242+
<summary><strong>Node.js / TypeScript</strong></summary>
243+
244+
```ts
245+
const session = await client.resumeSession(sessionId, {
246+
mcpServers: { /* server configs */ }
247+
});
248+
```
249+
</details>
250+
251+
<details>
252+
<summary><strong>Python</strong></summary>
253+
254+
```py
255+
session = await client.resume_session(session_id, {"mcp_servers": { """ <configs> """ }})
256+
```
257+
</details>
258+
259+
<details>
260+
<summary><strong>Go</strong></summary>
261+
262+
```go
263+
session, err := client.ResumeSessionWithOptions(sessionID, &copilot.ResumeSessionConfig{
264+
MCPServers: mcpServers,
265+
})
266+
```
267+
</details>
268+
269+
<details>
270+
<summary><strong>.NET</strong></summary>
271+
272+
```csharp
273+
var session = await client.ResumeSessionAsync(sessionId, new ResumeSessionConfig
274+
{
275+
McpServers = mcpServers
276+
});
277+
```
278+
</details>
279+
280+
281+
#### Additional resources:
282+
- For more information on available MCP servers:
283+
- [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server)
284+
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Explore more MCP servers
285+
- For troubleshooting local MCP servers, check that:
286+
- The command exists and is in the PATH
287+
- The process has appropriate permissions and environment variables
288+
- Arguments are correctly formatted for the command line
289+

‎dotnet/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,41 @@ When `Streaming = true`:
256256

257257
Note: `AssistantMessageEvent` and `AssistantReasoningEvent` (final events) are always sent regardless of streaming setting.
258258

259+
## MCP Servers
260+
261+
Configure local and remote MCP server usage:
262+
263+
```csharp
264+
var mcpServers = new Dictionary<string, object>
265+
{
266+
["github"] = new McpRemoteServerConfig
267+
{
268+
Type = "http",
269+
Url = "https://api.githubcopilot.com/mcp/",
270+
Tools = new[] { "github-repos", "github-pull-requests" },
271+
Headers = new Dictionary<string, string>
272+
{
273+
["Authorization"] = "Bearer <token>"
274+
}
275+
},
276+
["local-tools"] = new McpLocalServerConfig
277+
{
278+
Type = "local",
279+
Command = "echo",
280+
Args = new[] { "hello" },
281+
Tools = new[] { "*" },
282+
Env = new Dictionary<string, string> { ["DEBUG"] = "1" }
283+
}
284+
};
285+
286+
var session = await client.CreateSessionAsync(new SessionConfig
287+
{
288+
McpServers = mcpServers
289+
});
290+
```
291+
292+
Futher MCP server usage details: [Using MCP servers with the Copilot SDK](../docs/mcp-usage.md)
293+
259294
## Advanced Usage
260295

261296
### Manual Server Control

‎go/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,36 @@ When `Streaming: true`:
263263

264264
Note: `assistant.message` and `assistant.reasoning` (final events) are always sent regardless of streaming setting.
265265

266+
## MCP Servers
267+
268+
Configure local and remote MCP server usage:
269+
270+
```go
271+
mcpServers := map[string]copilot.MCPServerConfig{
272+
"github": {
273+
"type": "http",
274+
"url": "https://api.githubcopilot.com/mcp/",
275+
"tools": []string{"github-repos", "github-pull-requests"},
276+
"headers": map[string]string{
277+
"Authorization": "Bearer <token>",
278+
},
279+
},
280+
"local-tools": {
281+
"type": "local",
282+
"command": "echo",
283+
"args": []string{"hello"},
284+
"tools": []string{"*"},
285+
"env": map[string]string{"DEBUG": "1"},
286+
},
287+
}
288+
289+
session, err := client.CreateSession(&copilot.SessionConfig{
290+
MCPServers: mcpServers,
291+
})
292+
```
293+
294+
Futher MCP server usage details: [Using MCP servers with the Copilot SDK](../docs/mcp-usage.md)
295+
266296
## Transport Modes
267297

268298
### stdio (Default)

0 commit comments

Comments
 (0)