Skip to content

Commit b48c25d

Browse files
brunoborgesbrunoborges
committed
fix: add MCP Servers documentation and integration examples
1 parent caf4d0d commit b48c25d

2 files changed

Lines changed: 210 additions & 0 deletions

File tree

‎src/site/markdown/documentation.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ This document provides detailed API reference and usage examples for the Copilot
2121
- [Bring Your Own Key (BYOK)](#Bring_Your_Own_Key_.28BYOK.29)
2222
- [Permission Handling](#Permission_Handling)
2323
- [Infinite Sessions](#Infinite_Sessions)
24+
- [MCP Servers](#MCP_Servers)
2425
- [Error Handling](#Error_Handling)
2526

2627
## API Reference
@@ -488,6 +489,27 @@ var session = client.createSession(
488489
// session.getWorkspacePath() will return null
489490
```
490491

492+
### MCP Servers
493+
494+
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 that Copilot can invoke during conversations.
495+
496+
📖 **[Full MCP documentation →](mcp.md)** - Learn about local vs remote servers, all configuration options, and troubleshooting.
497+
498+
Quick example:
499+
500+
```java
501+
Map<String, Object> filesystemServer = new HashMap<>();
502+
filesystemServer.put("type", "local");
503+
filesystemServer.put("command", "npx");
504+
filesystemServer.put("args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"));
505+
filesystemServer.put("tools", List.of("*"));
506+
507+
var session = client.createSession(
508+
new SessionConfig()
509+
.setMcpServers(Map.of("filesystem", filesystemServer))
510+
).get();
511+
```
512+
491513
## Error Handling
492514

493515
```java

‎src/site/markdown/mcp.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Using MCP Servers with the Copilot SDK for Java
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+
## What is MCP?
6+
7+
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external tools and data sources. MCP servers can:
8+
9+
- Execute code or scripts
10+
- Query databases
11+
- Access file systems
12+
- Call external APIs
13+
- And much more
14+
15+
## Server Types
16+
17+
The SDK supports two types of MCP servers:
18+
19+
| Type | Description | Use Case |
20+
|------|-------------|----------|
21+
| **Local/Stdio** | Runs as a subprocess, communicates via stdin/stdout | Local tools, file access, custom scripts |
22+
| **HTTP/SSE** | Remote server accessed via HTTP | Shared services, cloud-hosted tools |
23+
24+
## Configuration
25+
26+
MCP servers are configured using `Map<String, Object>` where keys are server names and values are configuration maps.
27+
28+
### Java
29+
30+
```java
31+
import com.github.copilot.sdk.*;
32+
import com.github.copilot.sdk.json.*;
33+
import java.util.HashMap;
34+
import java.util.List;
35+
import java.util.Map;
36+
37+
try (var client = new CopilotClient()) {
38+
client.start().get();
39+
40+
// Create MCP server configurations
41+
Map<String, Object> mcpServers = new HashMap<>();
42+
43+
// Local MCP server (stdio)
44+
Map<String, Object> localServer = new HashMap<>();
45+
localServer.put("type", "local");
46+
localServer.put("command", "node");
47+
localServer.put("args", List.of("./mcp-server.js"));
48+
localServer.put("env", Map.of("DEBUG", "true"));
49+
localServer.put("cwd", "./servers");
50+
localServer.put("tools", List.of("*")); // "*" = all tools, empty = none
51+
mcpServers.put("my-local-server", localServer);
52+
53+
// Remote MCP server (HTTP)
54+
Map<String, Object> remoteServer = new HashMap<>();
55+
remoteServer.put("type", "http");
56+
remoteServer.put("url", "https://api.githubcopilot.com/mcp/");
57+
remoteServer.put("headers", Map.of("Authorization", "Bearer ${TOKEN}"));
58+
remoteServer.put("tools", List.of("*"));
59+
mcpServers.put("github", remoteServer);
60+
61+
var session = client.createSession(
62+
new SessionConfig()
63+
.setModel("gpt-5")
64+
.setMcpServers(mcpServers)
65+
).get();
66+
67+
// Use the session with MCP tools available
68+
var response = session.sendAndWait("List my recent GitHub notifications").get();
69+
System.out.println(response.getData().getContent());
70+
}
71+
```
72+
73+
## Quick Start: Filesystem MCP Server
74+
75+
Here's a complete working example using the official [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP server:
76+
77+
```java
78+
import com.github.copilot.sdk.*;
79+
import com.github.copilot.sdk.json.*;
80+
import java.util.HashMap;
81+
import java.util.List;
82+
import java.util.Map;
83+
84+
public class McpExample {
85+
public static void main(String[] args) throws Exception {
86+
try (var client = new CopilotClient()) {
87+
client.start().get();
88+
89+
// Create filesystem MCP server configuration
90+
Map<String, Object> filesystemServer = new HashMap<>();
91+
filesystemServer.put("type", "local");
92+
filesystemServer.put("command", "npx");
93+
filesystemServer.put("args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"));
94+
filesystemServer.put("tools", List.of("*"));
95+
96+
Map<String, Object> mcpServers = new HashMap<>();
97+
mcpServers.put("filesystem", filesystemServer);
98+
99+
// Create session with filesystem MCP server
100+
var session = client.createSession(
101+
new SessionConfig()
102+
.setMcpServers(mcpServers)
103+
).get();
104+
105+
System.out.println("Session created: " + session.getSessionId());
106+
107+
// The model can now use filesystem tools
108+
var result = session.sendAndWait("List the files in the allowed directory").get();
109+
System.out.println("Response: " + result.getData().getContent());
110+
111+
session.close();
112+
}
113+
}
114+
}
115+
```
116+
117+
**Output:**
118+
```
119+
Session created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a
120+
Response: The allowed directory is `/tmp`, which contains various files
121+
and subdirectories including temporary system files, log files, and
122+
directories for different applications.
123+
```
124+
125+
> **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`.
126+
127+
## Configuration Options
128+
129+
### Local/Stdio Server
130+
131+
| Property | Type | Required | Description |
132+
|----------|------|----------|-------------|
133+
| `type` | `"local"` or `"stdio"` | No | Server type (defaults to local) |
134+
| `command` | `String` | Yes | Command to execute |
135+
| `args` | `List<String>` | Yes | Command arguments |
136+
| `env` | `Map<String, String>` | No | Environment variables |
137+
| `cwd` | `String` | No | Working directory |
138+
| `tools` | `List<String>` | No | Tools to enable (`["*"]` for all, `[]` for none) |
139+
| `timeout` | `Integer` | No | Timeout in milliseconds |
140+
141+
### Remote Server (HTTP/SSE)
142+
143+
| Property | Type | Required | Description |
144+
|----------|------|----------|-------------|
145+
| `type` | `"http"` or `"sse"` | Yes | Server type |
146+
| `url` | `String` | Yes | Server URL |
147+
| `headers` | `Map<String, String>` | No | HTTP headers (e.g., for auth) |
148+
| `tools` | `List<String>` | No | Tools to enable |
149+
| `timeout` | `Integer` | No | Timeout in milliseconds |
150+
151+
## Troubleshooting
152+
153+
### Tools not showing up or not being invoked
154+
155+
1. **Verify the MCP server starts correctly**
156+
- Check that the command and args are correct
157+
- Ensure the server process doesn't crash on startup
158+
- Look for error output in stderr
159+
160+
2. **Check tool configuration**
161+
- Make sure `tools` is set to `["*"]` or lists the specific tools you need
162+
- An empty list `[]` means no tools are enabled
163+
164+
3. **Verify connectivity for remote servers**
165+
- Ensure the URL is accessible
166+
- Check that authentication headers are correct
167+
168+
### Common issues
169+
170+
| Issue | Solution |
171+
|-------|----------|
172+
| "MCP server not found" | Verify the command path is correct and executable |
173+
| "Connection refused" (HTTP) | Check the URL and ensure the server is running |
174+
| "Timeout" errors | Increase the `timeout` value or check server performance |
175+
| Tools work but aren't called | Ensure your prompt clearly requires the tool's functionality |
176+
177+
### Debugging tips
178+
179+
1. **Enable verbose logging** in your MCP server to see incoming requests
180+
2. **Test your MCP server independently** before integrating with the SDK
181+
3. **Start with a simple tool** to verify the integration works
182+
183+
## Related Resources
184+
185+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
186+
- [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Community MCP servers
187+
- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP server
188+
- [Copilot SDK for Java Documentation](documentation.md) - SDK basics and custom tools

0 commit comments

Comments
 (0)