{"meta":{"title":"GitHub Copilot SDK에서 MCP 서버 사용","intro":"Copilot SDK는 MCP 서버(모델 컨텍스트 프로토콜)와 통합되어 외부 도구로 도우미의 기능을 확장할 수 있습니다. MCP 서버는 별도의 프로세스로 실행되며 Copilot 대화 중에 호출할 수 있는 도구(함수)를 노출합니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos","title":"방법"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"코필로트 SDK"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"기능"},{"href":"/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp","title":"MCP"}],"documentType":"article"},"body":"# GitHub Copilot SDK에서 MCP 서버 사용\n\nCopilot SDK는 MCP 서버(모델 컨텍스트 프로토콜)와 통합되어 외부 도구로 도우미의 기능을 확장할 수 있습니다. MCP 서버는 별도의 프로세스로 실행되며 Copilot 대화 중에 호출할 수 있는 도구(함수)를 노출합니다.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n> \\[!NOTE]\n> 이는 진화하는 기능입니다. 진행 중인 토론은 [문제 #36](https://github.com/github/copilot-sdk/issues/36) 을 참조하세요.\n\n## MCP란?\n\n[MCP(모델 컨텍스트 프로토콜)](https://modelcontextprotocol.io/) 는 AI 도우미를 외부 도구 및 데이터 원본에 연결하기 위한 개방형 표준입니다. MCP 서버는 다음을 수행할 수 있습니다.\n\n* 코드 또는 스크립트 실행\n* 데이터베이스 쿼리\n* 파일 시스템에 액세스\n* 외부 API 호출\n* 그리고 훨씬 더\n\n## 서버 유형\n\nSDK는 두 가지 유형의 MCP 서버를 지원합니다.\n\n| Type            | Description                           | 사용 사례                      |\n| --------------- | ------------------------------------- | -------------------------- |\n| **Local/Stdio** | 하위 프로세스로 실행되며 stdin/stdout을 통해 통신합니다. | 로컬 도구, 파일 액세스, 사용자 지정 스크립트 |\n| **HTTP/SSE**    | HTTP를 통해 액세스된 원격 서버                   | 공유 서비스, 클라우드 호스팅 도구        |\n\n## Configuration\n\n### Node.js/ TypeScript\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nconst session = await client.createSession({\n    model: \"gpt-5\",\n    mcpServers: {\n        // Local MCP server (stdio)\n        \"my-local-server\": {\n            type: \"local\",\n            command: \"node\",\n            args: [\"./mcp-server.js\"],\n            env: { DEBUG: \"true\" },\n            cwd: \"./servers\",\n            tools: [\"*\"],  // \"*\" = all tools, [] = none, or list specific tools\n            timeout: 30000,\n        },\n        // Remote MCP server (HTTP)\n        \"github\": {\n            type: \"http\",\n            url: \"https://api.githubcopilot.com/mcp/\",\n            headers: { \"Authorization\": \"Bearer ${TOKEN}\" },\n            tools: [\"*\"],\n        },\n    },\n});\n```\n\n### Python\n\n```python\nimport asyncio\nfrom copilot import CopilotClient\nfrom copilot.session import PermissionHandler\n\nasync def main():\n    client = CopilotClient()\n    await client.start()\n\n    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5\", mcp_servers={\n        # Local MCP server (stdio)\n        \"my-local-server\": {\n            \"type\": \"local\",\n            \"command\": \"python\",\n            \"args\": [\"./mcp_server.py\"],\n            \"env\": {\"DEBUG\": \"true\"},\n            \"cwd\": \"./servers\",\n            \"tools\": [\"*\"],\n            \"timeout\": 30000,\n        },\n        # Remote MCP server (HTTP)\n        \"github\": {\n            \"type\": \"http\",\n            \"url\": \"https://api.githubcopilot.com/mcp/\",\n            \"headers\": {\"Authorization\": \"Bearer ${TOKEN}\"},\n            \"tools\": [\"*\"],\n        },\n    })\n\n    response = await session.send_and_wait(\"List my recent GitHub notifications\")\n    print(response.data.content)\n\n    await client.stop()\n\nasyncio.run(main())\n```\n\n### Go\n\n```golang\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    copilot \"github.com/github/copilot-sdk/go\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    client := copilot.NewClient(nil)\n    if err := client.Start(ctx); err != nil {\n        log.Fatal(err)\n    }\n    defer client.Stop()\n\n    session, err := client.CreateSession(ctx, &copilot.SessionConfig{\n        Model: \"gpt-5\",\n        MCPServers: map[string]copilot.MCPServerConfig{\n            \"my-local-server\": copilot.MCPStdioServerConfig{\n                Command: \"node\",\n                Args:    []string{\"./mcp-server.js\"},\n                Tools:   []string{\"*\"},\n            },\n        },\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer session.Disconnect()\n\n    // Use the session...\n}\n```\n\n### .NET\n\n```csharp\nusing GitHub.Copilot;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    Model = \"gpt-5\",\n    McpServers = new Dictionary<string, McpServerConfig>\n    {\n        [\"my-local-server\"] = new McpStdioServerConfig\n        {\n            Command = \"node\",\n            Args = new List<string> { \"./mcp-server.js\" },\n            Tools = new List<string> { \"*\" },\n        },\n    },\n});\n```\n\n## 세션당 구성된 서버 사용 안 함\n\n세션에서 실행해서는 안 되는 정확한 MCP 서버 이름으로 설정합니다 `disabledMcpServers` .\n설정은 개별 만들기 또는 다시 시작 요청으로 범위가 지정됩니다. 전역 MCP 설정 또는 서버 구성을 수정하지 않습니다.\n\n```typescript\nconst session = await client.createSession({\n    mcpServers: {\n        filesystem: { type: \"local\", command: \"npx\", args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"] },\n        github: { type: \"http\", url: \"https://api.githubcopilot.com/mcp/\" },\n    },\n    disabledMcpServers: [\"github\"],\n});\n```\n\n| SDK     | 구성 속성                            |\n| ------- | -------------------------------- |\n| Node.js | `disabledMcpServers`             |\n| Python  | `disabled_mcp_servers`           |\n| Go      | `DisabledMCPServers`             |\n| .NET    | `DisabledMcpServers`             |\n| Java    | `setDisabledMcpServers(...)`     |\n| 러스트     | `with_disabled_mcp_servers(...)` |\n\n세션 생성 시 및 **콜드** 재개 시에는 비활성화된 서버가 시작되지 않으며 런타임은 해당 서버의 인증을 시작하지 않습니다. 상주 이력서는 런타임이 이미 생성된 서버를 실행 취소할 수 없습니다. 이름은 정확히 일치합니다.\n\n## 도구 구성\n\n`tools` 필드를 사용하여 MCP 서버에서 사용할 수 있는 도구를 제어할 수 있습니다.\n\n### 모든 도구 허용\n\nMCP 서버에서 제공하는 모든 도구를 사용하도록 설정하는 데 사용합니다 `\"*\"` .\n\n```typescript\ntools: [\"*\"]\n```\n\n### 특정 도구 허용\n\n액세스를 제한하는 도구 이름 목록을 제공합니다.\n\n```typescript\ntools: [\"bash\", \"edit\"]\n```\n\n나열된 도구만 에이전트에서 사용할 수 있습니다.\n\n### 모든 도구 사용 안 함\n\n빈 배열을 사용하여 모든 도구를 사용하지 않도록 설정합니다.\n\n```typescript\ntools: []\n```\n\n### Notes\n\n* `tools` 필드는 허용되는 도구를 정의합니다.\n* 별도의 `allow` 구성이나 `disallow` 구성이 없습니다. 도구 액세스는 이 목록을 통해 직접 제어됩니다.\n\n## 빠른 시작: 파일 시스템 MCP 서버\n\n공식 [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) MCP 서버를 사용하는 전체 작업 예제는 다음과 같습니다.\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nasync function main() {\n    const client = new CopilotClient();\n\n    // Create session with filesystem MCP server\n    const session = await client.createSession({\n        mcpServers: {\n            filesystem: {\n                type: \"local\",\n                command: \"npx\",\n                args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"],\n                tools: [\"*\"],\n            },\n        },\n    });\n\n    console.log(\"Session created:\", session.sessionId);\n\n    // The model can now use filesystem tools\n    const result = await session.sendAndWait({\n        prompt: \"List the files in the allowed directory\",\n    });\n\n    console.log(\"Response:\", result?.data?.content);\n\n    await session.disconnect();\n    await client.stop();\n}\n\nmain();\n```\n\n**Output:**\n\n```text\nSession created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a\nResponse: The allowed directory is `/tmp`, which contains various files\nand subdirectories including temporary system files, log files, and\ndirectories for different applications.\n```\n\n> \\[!TIP]\n> [MCP 서버 디렉터리에서 MCP 서버를](https://github.com/modelcontextprotocol/servers) 사용할 수 있습니다. 인기 있는 옵션에는 `@modelcontextprotocol/server-github`, `@modelcontextprotocol/server-sqlite`및 `@modelcontextprotocol/server-puppeteer`.\n\n## 구성 옵션\n\n### 로컬/stdio 서버\n\n| 재산                     | Type       | 필수             | Description                                        |\n| ---------------------- | ---------- | -------------- | -------------------------------------------------- |\n| `type`                 |            |                |                                                    |\n| `\"local\"` 또는 `\"stdio\"` | No         | 서버 유형(기본값: 로컬) |                                                    |\n| `command`              | `string`   | Yes            | 실행할 명령                                             |\n| `args`                 | `string[]` | Yes            | 명령 인수                                              |\n| `env`                  | `object`   | No             | 환경 변수                                              |\n| `cwd`                  | `string`   | No             | 작업 디렉터리                                            |\n| `tools`                | `string[]` | No             | 모든 사용자에게 허용할 도구(`[\"*\"]` 또는, `[]` 아무에게도 허용하지 않을 도구) |\n| `timeout`              | `number`   | No             | 시간 제한(밀리초)                                         |\n\n### 원격 서버(HTTP/SSE)\n\n| 재산                  | Type       | 필수    | Description     |\n| ------------------- | ---------- | ----- | --------------- |\n| `type`              |            |       |                 |\n| `\"http\"` 또는 `\"sse\"` | Yes        | 서버 유형 |                 |\n| `url`               | `string`   | Yes   | 서버 URL          |\n| `headers`           | `object`   | No    | HTTP 헤더(예: 인증용) |\n| `tools`             | `string[]` | No    | 사용을 가능하게 하는 도구  |\n| `timeout`           | `number`   | No    | 시간 제한(밀리초)      |\n\n## Troubleshooting\n\n### 도구가 표시되지 않거나 호출되지 않음\n\n1. **MCP 서버가 올바르게 시작되는지 확인**\n   * 명령 및 인수가 올바른지 확인합니다.\n   * 시작 시 서버 프로세스가 충돌하지 않는지 확인\n   * stderr에서 오류 출력 찾기\n\n2. **도구 구성 확인**\n   * `tools`이(가) `[\"*\"]`로 설정되어 있거나 필요한 특정 도구가 나열되어 있는지 확인하세요.\n   * 빈 배열 `[]` 은 도구가 활성화되지 않음을 의미합니다.\n\n3. **원격 서버에 대한 연결 확인**\n   * URL에 액세스할 수 있는지 확인\n   * 인증 헤더가 올바른지 확인\n\n### 일반적인 문제\n\n| Issue                | 해결 방법                              |\n| -------------------- | ---------------------------------- |\n| \"MCP 서버를 찾을 수 없습니다.\" | 명령 경로가 올바르고 실행 가능한지 확인합니다.         |\n| \"연결 거부됨\"(HTTP)       | URL을 확인하고 서버가 실행 중인지 확인합니다.        |\n| \"시간 제한\" 오류           | 값을 증가시키거나 `timeout` 서버 성능을 확인하십시오. |\n| 도구가 작동하지만 호출되지 않음    | 프롬프트에 도구의 기능이 명확하게 필요한지 확인합니다.     |\n\n자세한 디버깅 지침은 **[MCP 서버 디버깅 가이드](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)** 을 참조하세요.\n\n## 관련 리소스\n\n* [모델 컨텍스트 프로토콜 사양](https://modelcontextprotocol.io/)\n* [MCP 서버 디렉터리](https://github.com/modelcontextprotocol/servers) - 커뮤니티 MCP 서버\n* [GitHub MCP 서버](https://github.com/github/github-mcp-server) - 공식 GitHub MCP 서버\n* [첫 번째 Copilot 기반 앱 빌드](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started) - SDK 기본 사항 및 사용자 지정 도구\n* [디버깅 가이드](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - SDK 전체 디버깅\n\n## 참고하십시오\n\n* [MCP 서버 디버깅 가이드](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - 자세한 MCP 문제 해결\n* [문제 #9](https://github.com/github/copilot-sdk/issues/9) - 원래 MCP 도구 사용 질문\n* [문제 #36](https://github.com/github/copilot-sdk/issues/36) - MCP 설명서 추적 문제"}