GitHub Copilot SDK에서 MCP 서버 사용

참고

이는 진화하는 기능입니다. 진행 중인 토론은 문제 #36 을 참조하세요.

MCP란?

MCP(모델 컨텍스트 프로토콜) 는 AI 도우미를 외부 도구 및 데이터 원본에 연결하기 위한 개방형 표준입니다. MCP 서버는 다음을 수행할 수 있습니다.

코드 또는 스크립트 실행
데이터베이스 쿼리
파일 시스템에 액세스
외부 API 호출
그리고 훨씬 더

서버 유형

SDK는 두 가지 유형의 MCP 서버를 지원합니다.

Type	Description	사용 사례
Local/Stdio	하위 프로세스로 실행되며 stdin/stdout을 통해 통신합니다.	로컬 도구, 파일 액세스, 사용자 지정 스크립트
HTTP/SSE	HTTP를 통해 액세스된 원격 서버	공유 서비스, 클라우드 호스팅 도구

Configuration

Node.js/ 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

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

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

using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5",
    McpServers = new Dictionary<string, McpServerConfig>
    {
        ["my-local-server"] = new McpStdioServerConfig
        {
            Command = "node",
            Args = new List<string> { "./mcp-server.js" },
            Tools = new List<string> { "*" },
        },
    },
});

도구 구성

tools 필드를 사용하여 MCP 서버에서 사용할 수 있는 도구를 제어할 수 있습니다.

모든 도구 허용

MCP 서버에서 제공하는 모든 도구를 사용하도록 설정하는 데 사용합니다 "*" .

tools: ["*"]

특정 도구 허용

액세스를 제한하는 도구 이름 목록을 제공합니다.

tools: ["bash", "edit"]

나열된 도구만 에이전트에서 사용할 수 있습니다.

모든 도구 사용 안 함

빈 배열을 사용하여 모든 도구를 사용하지 않도록 설정합니다.

tools: []

Notes

tools 필드는 허용되는 도구를 정의합니다.
별도의 allow 구성이나 disallow 구성이 없습니다. 도구 액세스는 이 목록을 통해 직접 제어됩니다.

빠른 시작: 파일 시스템 MCP 서버

공식 @modelcontextprotocol/server-filesystem MCP 서버를 사용하는 전체 작업 예제는 다음과 같습니다.

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:

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.

팁

MCP 서버 디렉터리에서 MCP 서버를 사용할 수 있습니다. 인기 있는 옵션에는 @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

도구가 표시되지 않거나 호출되지 않음

MCP 서버가 올바르게 시작되는지 확인
- 명령 및 인수가 올바른지 확인합니다.
- 시작 시 서버 프로세스가 충돌하지 않는지 확인
- stderr에서 오류 출력 찾기
도구 구성 확인
- tools이(가) ["*"]로 설정되어 있거나 필요한 특정 도구가 나열되어 있는지 확인하세요.
- 빈 배열 [] 은 도구가 활성화되지 않음을 의미합니다.
원격 서버에 대한 연결 확인
- URL에 액세스할 수 있는지 확인
- 인증 헤더가 올바른지 확인

일반적인 문제

Issue	해결 방법
"MCP 서버를 찾을 수 없습니다."	명령 경로가 올바르고 실행 가능한지 확인합니다.
"연결 거부됨"(HTTP)	URL을 확인하고 서버가 실행 중인지 확인합니다.
"시간 제한" 오류	값을 증가시키거나 `timeout` 서버 성능을 확인하십시오.
도구가 작동하지만 호출되지 않음	프롬프트에 도구의 기능이 명확하게 필요한지 확인합니다.

자세한 디버깅 지침은 MCP 서버 디버깅 가이드 을 참조하세요.

모델 컨텍스트 프로토콜 사양
MCP 서버 디렉터리 - 커뮤니티 MCP 서버
GitHub MCP 서버 - 공식 GitHub MCP 서버
첫 번째 Copilot 기반 앱 빌드 - SDK 기본 사항 및 사용자 지정 도구
디버깅 가이드 - SDK 전체 디버깅

참고하십시오

MCP 서버 디버깅 가이드 - 자세한 MCP 문제 해결
문제 #9 - 원래 MCP 도구 사용 질문
문제 #36 - MCP 설명서 추적 문제

이 기사에서