docs: add MCP server usage documentation

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)

docs/mcp.md

@@ -0,0 +1,274 @@
+# 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-5",
+    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-5",
+        "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-5",
+        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-5",
+    McpServers = new Dictionary<string, object>
+    {
+        ["my-local-server"] = new McpLocalServerConfig
+        {
+            Type = "local",
+            Command = "node",
+            Args = new[] { "./mcp-server.js" },
+            Tools = new[] { "*" },
+        },
+    },
+});
+```
+
+## 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
+
+| 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