MCP 개발자 가이드

모델 컨텍스트 프로토콜(MCP)은 AI 모델이 통합 인터페이스를 통해 외부 도구 및 서비스와 상호 작용할 수 있도록 하는 개방형 표준입니다. Visual Studio Code는 전체 MCP 사양을 구현하여 VS Code에서 AI 에이전트의 기능을 확장하기 위한 도구, 프롬프트 및 리소스를 제공하는 MCP 서버를 만들 수 있습니다.

MCP 서버는 빌트인 도구 및 확장 프로그램에서 제공하는 도구와 함께 VS Code에서 사용할 수 있는 세 가지 유형의 도구 중 하나를 제공합니다. 도구 유형에 대해 자세히 알아보세요.

이 가이드에서는 VS Code 및 기타 MCP 클라이언트와 원활하게 작동하는 MCP 서버를 구축하는 데 필요한 모든 것을 다룹니다.

MCP 서버를 사용하는 이유는?

언어 모델 도구를 사용하여 VS Code의 채팅을 확장하기 위해 MCP 서버를 구현하면 다음과 같은 이점이 있습니다.

• 에이전트 모드 확장: 사용자의 프롬프트에 응답하는 부분으로 자동으로 호출되는 전문화된 도메인별 도구를 사용합니다. 예를 들어, 데이터베이스 스캐폴딩 및 쿼링을 사용하여 LLM에 동적으로 관련 컨텍스트를 제공합니다.
• 유연한 배포 옵션: 로컬 및 원격 시나리오에 적합합니다.
• 다양한 도구 및 플랫폼에서 MCP 서버 재사용

다음과 같은 시나리오에서 Language Model API를 사용하여 언어 모델 도구를 구현하는 것을 고려해 볼 수 있습니다.

• 확장 API를 사용하여 VS Code와 깊이 통합하고 싶습니다.
• Visual Studio Marketplace를 사용하여 도구 및 업데이트를 배포하고 싶습니다.

VS Code에서 지원하는 MCP 기능

VS Code는 다음과 같은 MCP 기능을 지원합니다.

• 전송:

  • 로컬 표준 입출력 (stdio)
  • 스트리밍 가능한 HTTP (http)
  • 서버 전송 이벤트 (sse) - 레거시 지원.

• 기능:

  • 도구: 추가 도구로 에이전트 모드 확장
  • 프롬프트: 채팅에 슬래시 명령으로 재사용 가능한 프롬프트 추가
  • 리소스: 사용자가 채팅 컨텍스트로 추가하거나 VS Code에서 직접 상호 작용할 수 있는 데이터 및 콘텐츠 제공
  • 유도: 사용자로부터 입력 요청
  • 샘플링: 사용자가 구성한 모델 및 구독을 사용하여 언어 모델 요청
  • 인증: OAuth를 사용하여 MCP 서버에 대한 액세스 권한 부여
  • 서버 지침
  • 루트: 사용자 작업 영역 루트 폴더에 대한 정보 제공

도구

도구 정의

VS Code는 에이전트 모드에서 MCP 도구를 지원하며, 작업에 따라 필요에 따라 호출됩니다. 사용자는 도구 선택기를 통해 도구를 활성화하고 구성할 수 있습니다. 도구 설명은 도구 이름과 함께 도구 선택기에 표시되며, 도구를 실행하기 전에 확인을 요청하는 대화 상자에도 표시됩니다.

사용자는 도구 확인 대화 상자에서 모델 생성 입력 매개변수를 편집할 수 있습니다. readOnlyHint 주석으로 표시되지 않은 모든 도구에는 확인 대화 상자가 표시됩니다.

동적 도구 검색

VS Code는 동적 도구 검색도 지원하여 서버가 런타임에 도구를 등록할 수 있도록 합니다. 예를 들어, 서버는 작업 영역에서 감지된 프레임워크 또는 언어에 따라 다른 도구를 제공하거나 사용자의 채팅 프롬프트에 응답하여 도구를 제공할 수 있습니다.

도구 주석

도구 동작에 대한 추가 메타데이터를 제공하려면 도구 주석을 사용할 수 있습니다.

• title: 사람이 읽을 수 있는 도구 제목으로, 도구가 호출될 때 채팅 보기에 표시됩니다.
• readOnlyHint: 도구가 읽기 전용임을 나타내는 선택적 힌트입니다. VS Code는 읽기 전용 도구를 실행하기 위해 확인을 요청하지 않습니다.

리소스

리소스는 구조화된 방식으로 사용자에게 데이터와 콘텐츠를 제공할 수 있도록 합니다. 사용자는 VS Code에서 리소스에 직접 액세스하거나 채팅 프롬프트에서 컨텍스트로 사용할 수 있습니다. 예를 들어, MCP 서버는 스크린샷을 생성하여 리소스로 제공하거나 로그 파일에 대한 액세스를 제공할 수 있으며, 이는 실시간으로 업데이트됩니다.

MCP 리소스를 정의할 때 리소스 이름이 MCP 리소스 빠른 선택에 표시됩니다. 리소스는 MCP: 리소스 찾아보기 명령을 통해 열거나 컨텍스트 추가를 선택한 다음 MCP 리소스를 선택하여 채팅 요청에 첨부할 수 있습니다. 리소스에는 텍스트 또는 이진 콘텐츠가 포함될 수 있습니다.

VS Code는 리소스 업데이트를 지원하여 사용자가 편집기에서 리소스 콘텐츠의 변경 사항을 실시간으로 볼 수 있도록 합니다.

리소스 템플릿

VS Code는 리소스 템플릿도 지원하여 사용자가 리소스를 참조할 때 입력 매개변수를 제공할 수 있도록 합니다. 예를 들어, 데이터베이스 쿼 도구는 데이터베이스 테이블 이름을 요청할 수 있습니다.

템플릿으로 리소스에 액세스할 때 사용자는 빠른 선택에서 필요한 매개변수를 입력하라는 메시지를 받습니다. 매개변수 값을 제안하는 완료 기능을 제공할 수 있습니다.

프롬프트

프롬프트는 사용자가 슬래시 명령(mcp.servername.promptname)을 사용하여 채팅에서 호출할 수 있는 재사용 가능한 채팅 프롬프트 템플릿입니다. 프롬프트는 다양한 도구를 강조 표시하거나 사용자의 로컬 컨텍스트 및 서비스에 적응하는 내장된 복잡한 워크플로를 제공하여 서버에 대한 사용자 온보딩에 유용할 수 있습니다.

프롬프트 입력 인수에 대한 값을 제안하는 완료 기능을 정의하는 경우 VS Code는 사용자로부터 입력을 수집하는 대화 상자를 표시합니다.

server.prompt(
  'teamGreeting',
  'Generate a greeting for team members',
  {
    name: completable(z.string(), value => {
      return ['Alice', 'Bob', 'Charlie'].filter(n => n.startsWith(value));
    })
  },
  async ({ name }) => ({
    messages: [
      {
        role: 'assistant',
        content: { type: 'text', text: `Hello ${name}, welcome to the team!` }
      }
    ]
  })
);

프롬프트 응답에 리소스 유형을 포함하면 VS Code가 해당 리소스를 채팅 프롬프트에 컨텍스트로 첨부합니다.

권한 부여

VS Code는 인증이 필요한 MCP 서버를 지원하여 사용자가 해당 서비스에 대한 사용자 계정을 대신하여 작동하는 MCP 서버와 상호 작용할 수 있도록 합니다.

권한 부여 사양은 MCP 서버를 리소스 서버와 권한 부여 서버로 깔끔하게 분리하여 개발자가 자체 OAuth 구현을 처음부터 구축하는 대신 기존 ID 공급자(IdP)에 권한 부여를 위임할 수 있도록 합니다.

VS Code에는 GitHub 및 Microsoft Entra에 대한 내장 인증 지원이 있습니다. MCP 서버가 최신 사양을 구현하고 GitHub 또는 Microsoft Entra를 권한 부여 서버로 사용하는 경우, 사용자는 해당 계정에 대한 계정 메뉴 > 신뢰할 수 있는 MCP 서버 관리 작업을 통해 어떤 MCP 서버가 계정에 액세스할 수 있는지 관리할 수 있습니다.

VS Code는 GitHub 및 Microsoft Entra 이외의 다른 IdP에 대한 OAuth 2.1 표준 및 2.0 표준을 사용한 권한 부여를 지원합니다. VS Code는 먼저 동적 클라이언트 등록(DCR) 핸드셰이크로 시작한 다음, IdP가 DCR을 지원하지 않으면 클라이언트 자격 증명 워크플로로 대체됩니다. 이렇게 하면 다양한 IdP가 각 MCP 서버에 대해 정적 클라이언트 ID 또는 특정 클라이언트 ID-비밀 쌍을 적절하게 생성할 수 있습니다.

사용자는 계정 메뉴를 통해 인증 상태를 확인할 수도 있습니다. 동적 클라이언트 등록을 제거하려면 명령 팔레트에서 인증: 동적 인증 공급자 제거 명령을 사용할 수 있습니다.

MCP 서버와 VS Code의 OAuth 워크플로가 작동하도록 보장하기 위한 체크리스트는 다음과 같습니다.

1. MCP 서버가 MCP 권한 부여 사양을 정의합니다.
2. IdP는 DCR 또는 클라이언트 자격 증명을 지원해야 합니다.
3. 리디렉션 URL 목록에는 다음 URL이 포함되어야 합니다. http://127.0.0.1:33418 및 https://vscode.dev/redirect

MCP 서버에서 DCR을 지원하지 않는 경우 사용자는 대체 클라이언트 자격 증명 흐름을 거칩니다.

샘플링

VS Code는 MCP 서버에 대한 샘플링에 대한 액세스를 제공합니다. 이를 통해 MCP 서버는 사용자가 구성한 모델 및 구독을 사용하여 언어 모델 요청을 수행할 수 있습니다. 예를 들어, 샘플링을 사용하여 대규모 데이터 세트를 요약하거나, 클라이언트로 보내기 전에 정보를 추출하거나, 도구에서 에이전트 의사 결정 로직을 구현합니다.

MCP 서버가 처음으로 샘플링 요청을 수행할 때 사용자는 서버가 모델에 액세스하도록 승인하라는 메시지를 받습니다.

특정 모델로 샘플링 요청을 할 때, 사용자는 명령 팔레트의 MCP: 서버 목록 > 모델 액세스 구성 명령을 사용하여 MCP 서버가 사용할 수 있는 모델을 제한할 수 있습니다. MCP 서버에 modelPreferences를 지정하여 샘플링에 사용할 모델에 대한 힌트를 제공하면 VS Code가 허용된 모델 중에서 선택합니다.

사용자는 명령 팔레트의 MCP: 서버 목록 > 샘플링 요청 표시 명령을 사용하여 MCP 서버가 수행한 샘플링 요청을 볼 수 있습니다.

작업 영역 루트

VS Code는 MCP 서버에 사용자의 작업 영역 루트 폴더 정보를 제공합니다.

아이콘

VS Code는 MCP 서버, 리소스 및 도구에서 제공하는 icons를 지원합니다. MCP 아이콘에는 이미지에 대한 URI인 src 속성이 있습니다.

• HTTP 또는 SSE 전송을 사용하는 MCP 서버는 MCP 서버가 호스팅되는 것과 동일한 기관에서 이미지를 제공할 수 있습니다. 예를 들어, https://example.com/mcp에 구성된 서버는 example.com에서 이미지를 제공할 수 있습니다.
• stdio 전송을 사용하는 MCP 서버는 file:/// URI를 사용하여 파일 시스템에서 이미지를 제공할 수 있습니다.
• 모든 MCP 서버는 data:로 시작하는 데이터 URI로 이미지를 포함할 수 있습니다.

VS Code에 MCP 서버 추가

사용자는 VS Code에서 여러 가지 방법으로 MCP 서버를 추가할 수 있습니다.

• 웹에서 직접 설치: 웹사이트에서 특수 MCP 설치 URL(vscode:mcp/install)을 사용합니다.
• 작업 영역 구성: 작업 영역의 .vscode/mcp.json 파일에 서버 구성을 지정합니다.
• 전역 구성: 사용자 프로필에 서버를 전역적으로 정의합니다.
• 자동 검색: VS Code는 Claude Desktop과 같은 다른 도구에서 서버를 검색할 수 있습니다.
• 확장: VS Code 확장은 프로그래밍 방식으로 MCP 서버를 등록할 수 있습니다.
• 명령줄: --add-mcp VS Code 명령줄 옵션을 사용하여 명령줄에서 MCP 서버를 설치합니다.

VS Code에 MCP 서버를 추가하는 다양한 방법에 대해 자세히 알아보세요.

MCP 서버 관리

VS Code의 확장 보기(⇧⌘X (Windows, Linux Ctrl+Shift+X))에서 설치된 MCP 서버 목록을 관리할 수 있습니다.

MCP 서버를 마우스 오른쪽 버튼으로 클릭하거나 톱니바퀴 아이콘을 선택하여 서버에서 다양한 관리 작업을 수행합니다. 또는 명령 팔레트에서 MCP: 서버 목록 명령을 실행하여 구성된 MCP 서버 목록을 확인합니다. 그런 다음 서버를 선택하고 작업을 수행할 수 있습니다.

MCP 설치 URL 만들기

VS Code는 링크에서 MCP 서버를 설치하기 위한 URL 처리기(vscode:mcp/install?{json-configuration})를 제공합니다(Insider: vscode-insiders:mcp/install?{json-configuration}).

JSON 서버 구성을 {\"name\":\"server-name\",\"command\":...} 형식으로 제공한 다음 JSON 문자열화 및 URL 인코딩을 수행합니다. 예를 들어, 다음 논리를 사용하여 설치 URL을 만듭니다.

// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

이 링크는 브라우저에서 사용하거나 명령줄에서 열 수 있습니다. 예를 들어 Linux에서는 xdg-open $LINK를 통해 열 수 있습니다.

확장에 MCP 서버 등록

확장에 MCP 서버를 등록하려면 다음 단계를 수행해야 합니다.

1. 확장의 package.json 파일에 MCP 서버 정의 공급자를 정의합니다.
2. vscode.lm.registerMcpServerDefinitionProvider API를 사용하여 확장 코드에서 MCP 서버 정의 공급자를 구현합니다.

VS Code 확장 프로그램에 MCP 서버를 등록하는 방법에 대한 기본 예제로 시작할 수 있습니다.

1. package.json의 정적 구성

MCP 서버를 등록하려는 확장은 package.json에서 contributes.mcpServerDefinitionProviders 확장 지점에 공급자의 id를 포함하여 기여해야 합니다. 이 id는 구현에서 사용된 것과 일치해야 합니다.

{
    ...
    "contributes": {
        "mcpServerDefinitionProviders": [
            {
                "id": "exampleProvider",
                "label": "Example MCP Server Provider"
            }
        ]
    }
    ...
}

2. 공급자 구현

vscode.lm.registerMcpServerDefinitionProvider API를 사용하여 확장에 MCP 서버를 등록하고 MCP 구성을 제공합니다. 이 API는 providerId 문자열과 McpServerDefinitionProvider 객체를 받습니다.

McpServerDefinitionProvider 객체는 세 가지 속성을 가집니다.

• onDidChangeMcpServerDefinitions: MCP 서버 구성이 변경될 때 트리거되는 이벤트입니다.
• provideMcpServerDefinitions: MCP 서버 구성 배열(vscode.McpServerDefinition[])을 반환하는 함수입니다.
• resolveMcpServerDefinition: MCP 서버를 시작해야 할 때 편집기에서 호출하는 함수입니다. 이 함수를 사용하여 인증과 같이 사용자 상호 작용이 필요할 수 있는 추가 작업을 수행합니다.

McpServerDefinition 객체는 다음 유형 중 하나가 될 수 있습니다.

• vscode.McpStdioServerDefinition: 로컬 프로세스를 실행하고 해당 stdin 및 stdout 스트림에서 작동하여 사용할 수 있는 MCP 서버를 나타냅니다.
• vscode.McpHttpServerDefinition: 스트리밍 가능한 HTTP 전송을 사용하여 사용할 수 있는 MCP 서버를 나타냅니다.

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    const didChangeEmitter = new vscode.EventEmitter<void>();

    context.subscriptions.push(vscode.lm.registerMcpServerDefinitionProvider('exampleProvider', {
        onDidChangeMcpServerDefinitions: didChangeEmitter.event,
        provideMcpServerDefinitions: async () => {
            let servers: vscode.McpServerDefinition[] = [];

            // Example of a simple stdio server definition
            servers.push(new vscode.McpStdioServerDefinition(
            {
                label: 'myServer',
                command: 'node',
                args: ['server.js'],
                cwd: vscode.Uri.file('/path/to/server'),
                env: {
                    API_KEY: ''
                },
                version: '1.0.0'
            });

            // Example of an HTTP server definition
            servers.push(new vscode.McpHttpServerDefinition(
            {
                label: 'myRemoteServer',
                uri: 'https://:3000',
                headers: {
                    'API_VERSION': '1.0.0'
                },
                version: '1.0.0'
            }));

            return servers;
        },
        resolveMcpServerDefinition: async (server: vscode.McpServerDefinition) => {

            if (server.label === 'myServer') {
                // Get the API key from the user, e.g. using vscode.window.showInputBox
                // Update the server definition with the API key
            }

            // Return undefined to indicate that the server should not be started or throw an error
            // If there is a pending tool call, the editor will cancel it and return an error message
            // to the language model.
            return server;
        }
    }));
}

MCP 서버 문제 해결 및 디버깅

VS Code의 MCP 개발 모드

MCP 서버를 개발할 때 MCP 서버 구성에 dev 키를 추가하여 MCP 서버에 대한 *개발 모드*를 활성화할 수 있습니다. 이것은 두 가지 속성을 가진 객체입니다.

• watch: MCP 서버를 다시 시작할 파일 변경을 감시하는 파일 glob 패턴입니다.

• debug: MCP 서버와 디버거를 설정할 수 있도록 합니다. 현재 VS Code는 Node.js 및 Python MCP 서버 디버깅을 지원합니다.

  Node.js MCP 서버

  Node.js MCP 서버를 디버그하려면 debug.type 속성을 node로 설정합니다.

  {
    "servers": {
      "my-mcp-server": {
        "type": "stdio",
        "command": "node",
        "cwd": "${workspaceFolder}",
        "args": ["./build/index.js"],
        "dev": {
          "watch": "src/**/*.ts",
          "debug": { "type": "node" }
        }
      }
    }
  }
  

  Python MCP 서버

  Python MCP 서버를 디버그하려면 debug.type 속성을 debugpy로 설정하고, debugpy 모듈이 기본 Python 환경에 설치되어 있지 않은 경우 debug.debugpyPath 속성을 해당 모듈의 경로로 설정할 수 있습니다.

  {
    "servers": {
      "my-python-mcp-server": {
        "type": "stdio",
        "command": "python",
        "cwd": "${workspaceFolder}",
        "args": ["./server.py"],
        "dev": {
          "watch": "**/*.py",
          "debug": {
            "type": "debugpy",
            "debugpyPath": "/path/to/debugpy"
          }
        }
      }
    }
  }
  

MCP 출력 로그

VS Code가 MCP 서버에서 문제를 감지하면 채팅 보기에 오류 표시기가 표시됩니다.

채팅 보기에서 오류 알림을 선택한 다음 출력 보기 옵션을 선택하여 서버 로그를 봅니다. 또는 명령 팔레트에서 MCP: 서버 목록을 실행하고 서버를 선택한 다음 출력 보기를 선택합니다.

모범 사례

• 명명 규칙: 고유하고 설명적인 이름을 보장합니다.
• 적절한 오류 처리 및 유효성 검사 구현: 설명적인 오류 메시지를 제공합니다.
• 진행률 보고 사용: 장기 실행 작업에 대해 사용자에게 알립니다.
• 도구 작업은 집중적이고 원자적으로 유지: 복잡한 상호 작용을 피합니다.
• 도구 명확하게 문서화: 사용 시기를 이해하는 데 도움이 되는 설명을 제공합니다.
• 누락된 입력 매개변수 처리: 기본값 또는 명확한 오류 메시지를 제공하여 처리합니다.
• 리소스에 대한 MIME 유형 설정: VS Code에서 다양한 콘텐츠 유형을 올바르게 처리하도록 보장합니다.
• 리소스 템플릿 사용: 사용자가 리소스에 액세스할 때 입력 매개변수를 제공할 수 있도록 합니다.
• 리소스 콘텐츠 캐싱: 성능을 개선하고 불필요한 네트워크 요청을 줄입니다.
• 샘플링 요청에 대한 적절한 토큰 제한 설정: 과도한 리소스 사용을 방지합니다.
• 샘플링 응답 유효성 검사: 사용하기 전에 유효성을 검사합니다.

명명 규칙

MCP 서버 및 해당 구성 요소에 권장되는 명명 규칙은 다음과 같습니다.

MCP 서버 생성 시작하기

VS Code에는 자체 MCP 서버를 개발하는 데 필요한 모든 도구가 있습니다. MCP 서버는 stdout을 처리할 수 있는 모든 언어로 작성할 수 있지만, MCP의 공식 SDK가 시작하기 좋은 곳입니다.

• TypeScript SDK
• Python SDK
• Java SDK
• Kotlin SDK
• C# SDK

MCP for Beginners 커리큘럼도 첫 MCP 서버 구축을 시작하는 데 도움이 될 것입니다.

관련 콘텐츠

• 언어 모델 도구 기여
• 에이전트 모드에서 MCP 도구 사용
• VS Code에서 엄선한 MCP 서버 목록
• 모델 컨텍스트 프로토콜 문서