# GitHub Copilot SDK에서 MCP 서버 사용 Copilot SDK는 MCP 서버(모델 컨텍스트 프로토콜)와 통합되어 외부 도구로 도우미의 기능을 확장할 수 있습니다. MCP 서버는 별도의 프로세스로 실행되며 Copilot 대화 중에 호출할 수 있는 도구(함수)를 노출합니다. > \[!NOTE] > 이는 진화하는 기능입니다. 진행 중인 토론은 [문제 #36](https://github.com/github/copilot-sdk/issues/36) 을 참조하세요. ## MCP란? [MCP(모델 컨텍스트 프로토콜)](https://modelcontextprotocol.io/) 는 AI 도우미를 외부 도구 및 데이터 원본에 연결하기 위한 개방형 표준입니다. MCP 서버는 다음을 수행할 수 있습니다. * 코드 또는 스크립트 실행 * 데이터베이스 쿼리 * 파일 시스템에 액세스 * 외부 API 호출 * 그리고 훨씬 더 ## 서버 유형 SDK는 두 가지 유형의 MCP 서버를 지원합니다. | Type | Description | 사용 사례 | | --------------- | ------------------------------------- | -------------------------- | | **Local/Stdio** | 하위 프로세스로 실행되며 stdin/stdout을 통해 통신합니다. | 로컬 도구, 파일 액세스, 사용자 지정 스크립트 | | **HTTP/SSE** | HTTP를 통해 액세스된 원격 서버 | 공유 서비스, 클라우드 호스팅 도구 | ## 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 from copilot.session import PermissionHandler async def main(): client = CopilotClient() await client.start() session = await client.create_session(on_permission_request=PermissionHandler.approve_all, 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("List my recent GitHub notifications") print(response.data.content) await client.stop() asyncio.run(main()) ``` ### Go ```golang package main import ( "context" "log" copilot "github.com/github/copilot-sdk/go" ) func main() { ctx := context.Background() client := copilot.NewClient(nil) if err := client.Start(ctx); err != nil { log.Fatal(err) } defer client.Stop() session, err := client.CreateSession(ctx, &copilot.SessionConfig{ Model: "gpt-5", MCPServers: map[string]copilot.MCPServerConfig{ "my-local-server": copilot.MCPStdioServerConfig{ Command: "node", Args: []string{"./mcp-server.js"}, Tools: []string{"*"}, }, }, }) if err != nil { log.Fatal(err) } defer session.Disconnect() // Use the session... } ``` ### .NET ```csharp using GitHub.Copilot; await using var client = new CopilotClient(); await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5", McpServers = new Dictionary { ["my-local-server"] = new McpStdioServerConfig { Command = "node", Args = new List { "./mcp-server.js" }, Tools = new List { "*" }, }, }, }); ``` ## 세션당 구성된 서버 사용 안 함 세션에서 실행해서는 안 되는 정확한 MCP 서버 이름으로 설정합니다 `disabledMcpServers` . 설정은 개별 만들기 또는 다시 시작 요청으로 범위가 지정됩니다. 전역 MCP 설정 또는 서버 구성을 수정하지 않습니다. ```typescript const session = await client.createSession({ mcpServers: { filesystem: { type: "local", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."] }, github: { type: "http", url: "https://api.githubcopilot.com/mcp/" }, }, disabledMcpServers: ["github"], }); ``` | SDK | 구성 속성 | | ------- | -------------------------------- | | Node.js | `disabledMcpServers` | | Python | `disabled_mcp_servers` | | Go | `DisabledMCPServers` | | .NET | `DisabledMcpServers` | | Java | `setDisabledMcpServers(...)` | | 러스트 | `with_disabled_mcp_servers(...)` | 세션 생성 시 및 **콜드** 재개 시에는 비활성화된 서버가 시작되지 않으며 런타임은 해당 서버의 인증을 시작하지 않습니다. 상주 이력서는 런타임이 이미 생성된 서버를 실행 취소할 수 없습니다. 이름은 정확히 일치합니다. ## 도구 구성 `tools` 필드를 사용하여 MCP 서버에서 사용할 수 있는 도구를 제어할 수 있습니다. ### 모든 도구 허용 MCP 서버에서 제공하는 모든 도구를 사용하도록 설정하는 데 사용합니다 `"*"` . ```typescript tools: ["*"] ``` ### 특정 도구 허용 액세스를 제한하는 도구 이름 목록을 제공합니다. ```typescript tools: ["bash", "edit"] ``` 나열된 도구만 에이전트에서 사용할 수 있습니다. ### 모든 도구 사용 안 함 빈 배열을 사용하여 모든 도구를 사용하지 않도록 설정합니다. ```typescript tools: [] ``` ### Notes * `tools` 필드는 허용되는 도구를 정의합니다. * 별도의 `allow` 구성이나 `disallow` 구성이 없습니다. 도구 액세스는 이 목록을 통해 직접 제어됩니다. ## 빠른 시작: 파일 시스템 MCP 서버 공식 [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP 서버를 사용하는 전체 작업 예제는 다음과 같습니다. ```typescript import { CopilotClient } from "@github/copilot-sdk"; async function main() { const client = new CopilotClient(); // 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.disconnect(); await client.stop(); } main(); ``` **Output:** ```text 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] > [MCP 서버 디렉터리에서 MCP 서버를](https://github.com/modelcontextprotocol/servers) 사용할 수 있습니다. 인기 있는 옵션에는 `@modelcontextprotocol/server-github`, `@modelcontextprotocol/server-sqlite`및 `@modelcontextprotocol/server-puppeteer`. ## 구성 옵션 ### 로컬/stdio 서버 | 재산 | Type | 필수 | Description | | ---------------------- | ---------- | -------------- | -------------------------------------------------- | | `type` | | | | | `"local"` 또는 `"stdio"` | No | 서버 유형(기본값: 로컬) | | | `command` | `string` | Yes | 실행할 명령 | | `args` | `string[]` | Yes | 명령 인수 | | `env` | `object` | No | 환경 변수 | | `cwd` | `string` | No | 작업 디렉터리 | | `tools` | `string[]` | No | 모든 사용자에게 허용할 도구(`["*"]` 또는, `[]` 아무에게도 허용하지 않을 도구) | | `timeout` | `number` | No | 시간 제한(밀리초) | ### 원격 서버(HTTP/SSE) | 재산 | Type | 필수 | Description | | ------------------- | ---------- | ----- | --------------- | | `type` | | | | | `"http"` 또는 `"sse"` | Yes | 서버 유형 | | | `url` | `string` | Yes | 서버 URL | | `headers` | `object` | No | HTTP 헤더(예: 인증용) | | `tools` | `string[]` | No | 사용을 가능하게 하는 도구 | | `timeout` | `number` | No | 시간 제한(밀리초) | ## Troubleshooting ### 도구가 표시되지 않거나 호출되지 않음 1. **MCP 서버가 올바르게 시작되는지 확인** * 명령 및 인수가 올바른지 확인합니다. * 시작 시 서버 프로세스가 충돌하지 않는지 확인 * stderr에서 오류 출력 찾기 2. **도구 구성 확인** * `tools`이(가) `["*"]`로 설정되어 있거나 필요한 특정 도구가 나열되어 있는지 확인하세요. * 빈 배열 `[]` 은 도구가 활성화되지 않음을 의미합니다. 3. **원격 서버에 대한 연결 확인** * URL에 액세스할 수 있는지 확인 * 인증 헤더가 올바른지 확인 ### 일반적인 문제 | Issue | 해결 방법 | | -------------------- | ---------------------------------- | | "MCP 서버를 찾을 수 없습니다." | 명령 경로가 올바르고 실행 가능한지 확인합니다. | | "연결 거부됨"(HTTP) | URL을 확인하고 서버가 실행 중인지 확인합니다. | | "시간 제한" 오류 | 값을 증가시키거나 `timeout` 서버 성능을 확인하십시오. | | 도구가 작동하지만 호출되지 않음 | 프롬프트에 도구의 기능이 명확하게 필요한지 확인합니다. | 자세한 디버깅 지침은 **[MCP 서버 디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)** 을 참조하세요. ## 관련 리소스 * [모델 컨텍스트 프로토콜 사양](https://modelcontextprotocol.io/) * [MCP 서버 디렉터리](https://github.com/modelcontextprotocol/servers) - 커뮤니티 MCP 서버 * [GitHub MCP 서버](https://github.com/github/github-mcp-server) - 공식 GitHub MCP 서버 * [첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started) - SDK 기본 사항 및 사용자 지정 도구 * [디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - SDK 전체 디버깅 ## 참고하십시오 * [MCP 서버 디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - 자세한 MCP 문제 해결 * [문제 #9](https://github.com/github/copilot-sdk/issues/9) - 원래 MCP 도구 사용 질문 * [문제 #36](https://github.com/github/copilot-sdk/issues/36) - MCP 설명서 추적 문제