12. MCP 서버 처음 연결하기 — AI 에이전트에 도구 달기

AI 에이전트에게 “이 파일 읽어줘”, “저 검색해줘”, “캘린더 확인해줘”라고 말해봤자, 연결이 안 되어 있으면 아무것도 못 한다. 에이전트와 외부 도구 사이를 이어주는 표준 규격이 바로 **MCP(Model Context Protocol)**다. USB-C 케이블이 기기 간 연결을 표준화했듯, MCP는 AI와 외부 시스템의 연결을 하나로 묶는다.

2026년 봄 기준, MCP는 이미 AI 생태계의 기본 인프라다. 공개 MCP 서버 1만 개 이상, 월간 SDK 다운로드 9,700만 건, Anthropic·OpenAI·Microsoft·Google이 모두 채택했다. Linux Foundation 산하 Agentic AI Foundation에서 표준을 관리한다. 이 글에서는 MCP가 뭔지, 왜 필요한지, 그리고 오늘 당장 연결하는 법까지 정리한다.

flowchart LR
    A["사용자 질문<br/>'오늘 일정 알려줘'"] --> B["AI 에이전트<br/>(Claude / ChatGPT)"]
    B --> C["MCP Client<br/>도구 요청"]
    C --> D["MCP Server<br/>구글 캘린더"]
    D --> E["실제 API 호출"]
    E --> D --> C --> B --> A

🧠 치트시트: MCP 한 줄 요약

MCP = AI의 USB-C 포트. 한 번 만들면 여러 AI 앱에서 재사용

세 가지 기능: Resources(읽기), Tools(실행), Prompts(템플릿)

Python 3.10+면 오늘 바로 시작 가능. Claude Desktop에 5분 안에 연결

MCP가 필요한 순간

“그냥 API 직접 쓰면 되지 않나?”라는 질문이 꼭 나온다. 된다. 하지만 도구가 3개만 넘어도 상황이 달라진다.

항목	기존 API 방식	MCP 방식
연결	도구마다 별도 코드 작성	표준 프로토콜 하나로 통일
인증	각각 OAuth, API Key 개별 구현	MCP 프레임워크에서 일괄 관리
재사용	앱마다 새로 구현	한 번 만든 서버를 여러 AI에서 공유
생태계	폐쇄적	오픈소스, 커뮤니티 서버 공유

예를 들어 구글 캘린더, 노션, 날씨 API를 각각 연결하려면 인증 방식·데이터 포맷·에러 처리가 전부 다르다. MCP는 이걸 하나의 규격으로 통일한다. 한 번 만든 캘린더 서버를 Claude, ChatGPT, Cursor, VS Code에서 똑같이 쓸 수 있다.

미니 사례 1: 서버 하나로 네 곳에서 쓰기 A팀은 구글 드라이브 MCP 서버를 하나 만들었다. Claude Desktop에서 문서 검색, VS Code Copilot에서 코드 리뷰 시 참고 자료 조회, Cursor에서 설계서 기반 코드 생성, ChatGPT에서 요약 보고서 작성 — 모두 같은 서버를 공유한다. 각 앱마다 따로 연결 코드를 짤 필요가 없다.

MCP가 할 수 있는 세 가지

공식 문서에 따르면 MCP는 세 가지 기능을 제공한다.

Resources (읽기 전용): 파일, API 응답, 데이터베이스 뷰 같은 읽기 전용 데이터. 에이전트가 참고만 하고 수정은 안 한다.
Tools (실행): LLM이 직접 호출하는 함수. “검색해줘”, “파일 만들어줘”, “이메일 보내줘” 같은 실행형 동작. 사용자 승인이 필요하다.
Prompts (템플릿): 특정 작업을 위한 사전 정의 프롬프트. “이 코드 리뷰해줘” 같은 반복 작업을 템플릿으로 고정한다.

이 중 Tools가 실무에서 가장 많이 쓰인다. 날씨 조회, 검색, 파일 조작, API 호출 — 거의 모든 MCP 서버가 Tools 기반으로 만들어진다.

5분 만에 첫 MCP 서버 만들기

Python 3.10 이상이 설치되어 있다면 오늘 바로 시작할 수 있다.

1단계: 패키지 매니저 설치

# uv 설치 (Python 패키지 매니저)
curl -LsSf https://astral.sh/uv/install.sh | sh

2단계: 프로젝트 생성

mkdir mcp-demo && cd mcp-demo
uv init
uv add "mcp[cli]" httpx

3단계: 서버 코드 작성

server.py에 날씨 정보를 가져오는 간단한 서버를 만든다.

from mcp.server.fastmcp import FastMCP
import httpx
 
mcp = FastMCP("weather-demo")
 
NWS_API = "https://api.weather.gov"
HEADERS = {"User-Agent": "mcp-weather-demo/1.0"}
 
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """위도와 경도로 날씨 예보를 가져옵니다."""
    async with httpx.AsyncClient() as client:
        # 포인트 조회
        points = await client.get(
            f"{NWS_API}/points/{latitude},{longitude}",
            headers=HEADERS
        )
        points.raise_for_status()
        forecast_url = points.json()["properties"]["forecast"]
 
        # 예보 조회
        forecast = await client.get(forecast_url, headers=HEADERS)
        forecast.raise_for_status()
        periods = forecast.json()["properties"]["periods"][:3]
 
        return "\n---\n".join(
            f"{p['name']}: {p['detailedForecast']}" for p in periods
        )
 
mcp.run()

핵심은 @mcp.tool() 데코레이터다. 이것 하나로 FastMCP가 함수의 타입 힌트와 docstring을 읽어 자동으로 도구 스키마를 생성한다.

4단계: Claude Desktop에 연결

Claude Desktop 설정 파일을 연다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

아래 내용을 추가한다.

{
  "mcpServers": {
    "weather-demo": {
      "command": "uv",
      "args": [
        "--directory",
        "/사용자/경로/mcp-demo",
        "run",
        "server.py"
      ]
    }
  }
}

Claude Desktop을 재시작하면 새 도구가 나타난다. 채팅에 “서울 날씨 알려줘”라고 입력하면 MCP 서버를 통해 실시간 날씨를 가져온다.

자주 묻는 문제와 해결

서버가 안 뜰 때

Python 버전 확인: python --version이 3.10 미만이면 업그레이드
경로 확인: 설정 파일의 --directory 경로가 실제 프로젝트 폴더와 일치하는지 확인
재시작: Claude Desktop을 완전히 종료 후 재실행 (설정 새로고침)

도구는 뜨는데 실행이 안 될 때

MCP Inspector로 디버깅: npx @anthropic/mcp-inspector 실행 후 서버 연결 테스트
에러 로그 확인: Claude Desktop 개발자 도구(View → Toggle Developer Tools)에서 콘솔 확인
API 키 확인: 외부 API를 호출하는 서버는 환경변수에 키가 설정되어 있는지 점검

여러 서버를 동시에 쓸 때

설정 파일에 서버를 추가하면 된다. 10개, 20개도 가능하다.

{
  "mcpServers": {
    "weather": { ... },
    "google-calendar": { ... },
    "notion": { ... }
  }
}

미니 사례 2: 3개 서버로 하루 업무 자동화 B팀은 세 개의 MCP 서버를 연결했다. (1) 구글 캘린더 서버로 오전 미팅 일정 확인, (2) 노션 서버로 회의록 작성, (3) 이메일 서버로 요약 전송. 아침에 “오늘 미팅 정리해줘” 한마디면 전체 워크플로우가 자동 실행된다.

어디서 시작해야 할지 모르겠다면

이미 만들어진 공개 MCP 서버가 1만 개 이상이다. 직접 만들기 전에 커뮤니티 서버를 먼저 찾아보자.

공식 서버 목록: https://github.com/modelcontextprotocol/servers
주요 서버: Google Drive, Notion, GitHub, Slack, PostgreSQL, Brave Search
설치 방법: 대부분 설정 파일에 몇 줄 추가하는 것으로 끝

처음에는 Brave Search 서버를 추천한다. 검색 기능이 연결되면 AI가 실시간 정보를 찾아볼 수 있어 활용도가 급격히 올라간다.

flowchart TD
    A["MCP 시작"] --> B{"직접 만들까?<br/>아님 있는 걸 쓸까?"}
    B -->|"있는 서버 먼저"| C["공식 서버 목록에서<br/>필요한 것 찾기"]
    B -->|"직접 만들고 싶다"| D["FastMCP로<br/>첫 서버 작성"]
    C --> E["설정 파일에<br/>몇 줄 추가"]
    D --> E
    E --> F["Claude Desktop<br/>재시작"]
    F --> G["채팅에서<br/>도구 사용 테스트"]
    G --> H{"잘 되나?"}
    H -->|"안 된다"| I["Inspector로<br/>디버깅"]
    H -->|"된다"| J["다음 서버<br/>추가"]
    I --> F

다음 읽기

공식 MCP 문서(modelcontextprotocol.io)와 Anthropic MCP 가이드를 교차 확인해 작성했습니다. 코드 예제는 FastMCP 공식 튜토리얼을 기반으로 합니다.

일하는 ai

탐색기