MCP 서버 구축: Claude와 VSCode를 외부 도구에 연결

발행: 1일 전 (2025년 12월 4일 오전 10:16 GMT+9)

7 min read

Source: Dev.to

소개

모델 컨텍스트 프로토콜(MCP)은 Anthropic이 개발한 오픈 프로토콜로, Claude와 같은 AI 어시스턴트가 외부 데이터 소스와 도구에 연결할 수 있게 해줍니다. 이 글에서는 Claude Desktop, VSCode 및 기타 호환 클라이언트와 함께 사용할 수 있는 자체 MCP 서버를 구축하는 방법을 단계별로 안내합니다.

MCP란?

MCP는 AI 어시스턴트가 외부 시스템과 상호작용할 수 있도록 표준화된 방법을 제공합니다. 이를 일종의 범용 어댑터라고 생각하면 됩니다. MCP를 통해 Claude는 다음을 할 수 있습니다:

데이터베이스 및 API에 접근
파일을 읽고 쓰기
명령 실행
웹 서비스와 상호작용

프로토콜은 JSON‑RPC 2.0을 stdio 또는 HTTP 위에서 사용하는 클라이언트‑서버 아키텍처를 정의합니다.

아키텍처 개요

MCP 서버는 세 가지 주요 구성 요소로 이루어집니다:

리소스

리소스는 서버가 클라이언트에 제공할 수 있는 데이터 소스입니다. 예시:

파일 시스템의 파일
데이터베이스 레코드
API 응답
실시간 데이터 스트림

도구

도구는 클라이언트가 서버를 통해 호출할 수 있는 함수입니다:

시스템 명령 실행
계산 수행
외부 API와 연동
데이터 조작

프롬프트

프롬프트는 상호작용을 구조화하는 미리 정의된 템플릿입니다:

질의 템플릿
명령 패턴
워크플로우 지시문

첫 번째 MCP 서버 만들기

간단한 MCP 서버를 단계별로 만들어 보겠습니다. 여기서는 Python을 사용하지만, MCP 서버는 어떤 언어로든 구현할 수 있습니다.

사전 요구 사항

pip install mcp

서버 기본 구조

from mcp.server import Server
from mcp.types import Resource, Tool
import asyncio

app = Server("my-mcp-server")

@app.list_resources()
async def list_resources() -> list[Resource]:
    return [
        Resource(
            uri="file:///example.txt",
            name="예시 파일",
            mimeType="text/plain"
        )
    ]

@app.read_resource()
async def read_resource(uri: str) -> str:
    if uri == "file:///example.txt":
        return "MCP 서버에서 인사합니다!"
    raise ValueError(f"알 수 없는 리소스: {uri}")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="인사하기",
            description="이름을 받아 인사합니다",
            inputSchema={
                "type": "object",
                "properties": {
                    "이름": {"type": "string"}
                },
                "required": ["이름"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> str:
    if name == "인사하기":
        return f"안녕, {arguments['이름']}!"
    raise ValueError(f"알 수 없는 도구: {name}")

if __name__ == "__main__":
    asyncio.run(app.run())

Claude Desktop에 연결하기

Claude Desktop에서 서버를 사용하려면 Claude 설정의 Developer 섹션에 다음과 같이 입력합니다:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["path/to/your/server.py"]
    }
  }
}

Claude Desktop을 재시작하면 서버의 도구와 리소스가 Claude에 표시됩니다.

VSCode에 연결하기

VSCode와 연동하려면 MCP 확장을 사용합니다:

마켓플레이스에서 MCP 확장을 설치합니다.
.vscode/mcp.json에 서버를 설정합니다:

{
  "servers": [
    {
      "name": "my-server",
      "command": "python",
      "args": ["path/to/your/server.py"]
    }
  ]
}

실제 사용 사례

데이터베이스 접근

Claude가 안전하게 데이터베이스를 조회하도록 서버를 만들 수 있습니다:

@app.list_tools()
async def list_tools():
    return [Tool(name="query_db", description="SQL 쿼리 실행")]

파일 시스템 작업

프로젝트 파일을 관리하는 서버를 구축합니다:

@app.list_resources()
async def list_resources():
    return [Resource(uri=f"file:///{file}") for file in os.listdir()]

API 연동

Claude를 외부 API와 연결합니다:

@app.call_tool()
async def call_tool(name, args):
    if name == "fetch_data":
        response = await http_client.get(args['url'])
        return response.json()

모범 사례

보안 우선: 입력을 검증하고 출력을 정제합니다.
오류 처리: 명확한 오류 메시지를 제공합니다.
문서화: 도구와 리소스를 충분히 문서화합니다.
성능: I/O 작업에 async/await를 활용합니다.
테스트: 다양한 클라이언트와 함께 서버를 테스트합니다.

예제 저장소

전체 예제와 실행 가능한 코드는 제 GitHub 저장소에서 확인할 수 있습니다:

저장소:

이 저장소에는 다음이 포함됩니다:

기본 MCP 서버 구현
Claude와 VSCode용 설정 예시
문서 및 설정 가이드
샘플 사용 사례

결론

MCP 서버를 구축하면 AI 어시스턴트의 기능을 무한히 확장할 수 있습니다. 데이터베이스, 파일 시스템, 외부 API 등 어떤 시스템이든 MCP를 통해 표준화된 방식으로 AI에 제공할 수 있습니다.

모델 컨텍스트 프로토콜은 계속 발전하고 있으며, 생태계도 빠르게 성장하고 있습니다. 직접 MCP 서버를 만들면 Claude 및 기타 호환 클라이언트를 여러분의 구체적인 요구와 워크플로에 맞게 맞춤화할 수 있습니다.