logo

MCP

MCP 서버의 도구를 LLM에 연결하고, 호출 요청·서버 실행·결과 기반 답변을 확인한다.

외부 도구를 공통 방식으로 연결하기

  • 모델 컨텍스트 프로토콜(Model Context Protocol, MCP): AI 애플리케이션이 외부 도구·자료에 연결하는 공통 통신 규약.
  • 프로토콜(protocol): 프로그램끼리 정보를 주고받기 위해 정한 메시지 형식과 요청·응답 규칙.
    • MCP는 도구 목록을 요청하는 방법, 도구 이름·입력 인자를 전달하는 방법, 실행 결과를 돌려주는 형식 등을 공통으로 정의.
    • 예: 재고 조회를 제공하는 서버에 애플리케이션이 도구 이름과 상품 이름을 보내면, 서버가 조회 결과를 약속된 형식으로 반환.
  • 도구를 연결해도 모델이 알아서 실행하는 것은 아님. 애플리케이션이 호출 요청을 서버에 보내고 결과를 모델에 전달.

USB-C 비유

  • 외부 서비스마다 다른 연결 코드를 AI 애플리케이션별로 작성하면 같은 기능을 여러 번 연결해야 하는 부담.
  • MCP 서버로 기능을 제공하면, 해당 기능을 MCP를 지원하는 여러 애플리케이션에서 공통 방식으로 발견·호출 가능.
  • USB-C 비유: 장치마다 다른 단자를 만드는 대신 공통 단자로 연결하는 것처럼, 외부 기능에 접근하는 통신 방식을 통일.

MCP를 USB-C 허브에 비유해 AI 호스트와 클라이언트가 메시지·메일·일정 서비스 및 로컬 파일의 MCP 서버에 연결되는 구조를 표현한 그림

  • 그림 위쪽: 외부 기능을 이용하는 AI 애플리케이션과 MCP 클라이언트.
  • 그림 아래쪽: 메시지·메일·일정 같은 원격 서비스와 로컬 파일에 연결하는 MCP 서버.
  • 공통 규격은 MCP 통신에 적용. 각 서비스의 API 차이는 서버 구현에서 처리하며, 계정 인증과 접근 권한도 별도로 필요.

그림 출처: Norah Klintberg Sakal, MCP 구조 설명.

호스트·클라이언트·서버

구성 요소 역할 이번 실습
호스트 모델·대화·외부 연결을 관리하는 애플리케이션 노트북에서 실행하는 애플리케이션 코드
클라이언트 MCP 서버와 통신하는 구성 요소 Client
서버 도구와 자료를 제공하는 프로그램 FastMCP 서버
  • 서버의 위치: 이번 실습에서는 서버도 같은 노트북 안에서 실행. Client(server)가 같은 파이썬 프로그램 안의 서버와 바로 통신.
  • 실제 서비스에서는 서버를 별도 프로그램이나 원격 컴퓨터에서 실행하고, 표준 입출력이나 HTTP로 연결(아래 "다른 애플리케이션에 연결할 때" 참고).

Mermaid 다이어그램 원문

sequenceDiagram
    autonumber
    participant L as LLM
    participant A as 애플리케이션 (MCP 클라이언트)
    participant S as MCP 서버
    A->>S: 도구 목록 요청
    S-->>A: 도구 이름·설명·입력 형식
    A->>L: 작업 요청과 도구 정의
    L-->>A: 도구 호출 요청(이름·인자)
    A->>S: 도구 실행 요청(이름·인자)
    S-->>A: 실행 결과
    A->>L: 호출 기록과 실행 결과
    L-->>A: 최종 답변

대화형 다이어그램을 불러오기 전에는 원문으로 표시됩니다.

  • MCP 클라이언트는 애플리케이션 내부에서 서버와 통신하는 구성 요소. 그림에서는 애플리케이션과 클라이언트를 하나의 참여자로 묶어 표시.
  • LLM이 MCP 서버에 직접 접속하는 것이 아니라, 애플리케이션이 실행 결과를 받아 모델에 다시 전달.

직접 연결과 MCP 연결

  • MCP는 함수 호출을 대신하는 방식이 아님. MCP를 써도 LLM은 함수 호출 실습과 똑같이 함수 이름과 인자를 담은 호출 요청을 생성.
  • 달라지는 것은 함수를 어디서 구현하고 실행하는지. 직접 연결은 애플리케이션이, MCP 연결은 MCP 서버가 담당.
구분 직접 연결 (함수 호출 실습) MCP 연결
LLM의 역할 호출 요청 생성 호출 요청 생성 (같음)
기능 구현 애플리케이션 서버
도구 설명 애플리케이션에서 직접 작성 서버에서 받아 사용
실행 담당 애플리케이션 서버
다른 앱에 연결 애플리케이션마다 연결 코드 작성 같은 서버 재사용
  • 핵심: MCP 서버가 함수 구현과 도구 설명을 제공하고, 애플리케이션은 서버에서 도구를 찾아 호출.

MCP 서버 만들기

  • 자료형과 함수 설명을 바탕으로 이름·설명·입력 스키마 생성.
  • Annotated[str, Field(description=...)]: 매개변수의 자료형에 설명을 덧붙이는 표기. 입력 스키마에 매개변수 설명으로 들어감.
!pip install fastmcp
from typing import Annotated

# MCP 구현을 위한 라이브러리
from fastmcp import FastMCP
from pydantic import Field

inventory = {
    "무선 마우스": 7,
    "기계식 키보드": 0,
    "USB 허브": 12,
}

server = FastMCP("Inventory")  # 서버 정의

@server.tool  # 아래 함수를 MCP 도구로 등록
def get_stock(
    product_name: Annotated[
        str,
        Field(description="조회할 상품 이름. 예: 무선 마우스, 기계식 키보드, USB 허브"),
    ],
) -> dict:
    """상품의 현재 재고 조회. stock이 0이면 품절, null이면 미등록 상품."""
    return {
        "product_name": product_name,
        # 재고표에 없는 상품은 None 반환. JSON으로 전달하면 null.
        "stock": inventory.get(product_name),
    }

서버의 도구 목록 확인하기

  • Client(server): 이 서버와 통신하는 클라이언트.
from fastmcp import Client

async with Client(server) as mcp_client:
    tools = await mcp_client.list_tools()  # 서버가 제공하는 도구의 목록 요청.

[tool.name for tool in tools]  # 제공되는 도구의 이름
실행 결과
['get_stock']
tools[0].description  # 첫 번째 도구의 설명
실행 결과
'상품의 현재 재고 조회. stock이 0이면 품절, null이면 미등록 상품.'
tools[0].input_schema  # 서버에서 가져온 입력 형식
실행 결과
{'type': 'object',
 'additionalProperties': False,
 'properties': {
   'product_name': {
     'description': '조회할 상품 이름. 예: 무선 마우스, 기계식 키보드, USB 허브',
     'type': 'string'}},
 'required': ['product_name']}
  • 서버 함수의 product_name과 도구 입력 형식 비교. 상품 이름은 문자열이며 필수 입력. Field로 작성한 설명도 포함.
  • 이 정보를 아래에서 모델 API의 도구 정의로 변환해 전달.

도구 호출하기

async with Client(server) as mcp_client:
    result = await mcp_client.call_tool(
        "get_stock",
        {"product_name": "무선 마우스"},
    )

result.data  # 서버에서 조회해 돌려준 상품 이름과 재고 수량
실행 결과
{'product_name': '무선 마우스', 'stock': 7}
  • 함수 이름·상품 이름을 서버에 전달하고 서버가 반환한 재고를 확인한 단계. 재고 수량을 호출 인자로 보내지는 않음.
  • 이번 호출은 사람이 함수 이름과 인자를 정함. 다음 단계에서는 LLM이 만든 호출 요청을 사용.

서버의 도구를 LLM에 알려 주기

  • LLM 호출: 실습 준비에서 연결한 OpenRouter API 사용.
  • MCP 서버에서 받은 이름·설명·입력 형식을 모델 API의 tools 형식으로 변환.
llm_tools = [
    {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description,
            # MCP의 입력 스키마를 모델 API의 parameters에 전달
            "parameters": tool.input_schema,
        },
    }
    for tool in tools
]

LLM에 호출 요청하기

import json

messages = [
    {"role": "system", 
     "content": "재고는 도구 결과로 답하세요. stock이 null이면 등록되지 않은 상품이라고 안내하세요."},
    {"role": "user", "content": "무선 마우스는 지금 몇 개 남아 있나요?"},
]

# 서버에서 가져온 도구 설명과 질문을 LLM에 전달
response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=llm_tools,
    # 실습에서는 재고 조회 호출을 지정
    tool_choice={"type": "function", "function": {"name": "get_stock"}},
    parallel_tool_calls=False,
)
assistant_message = response.choices[0].message
tool_call = assistant_message.tool_calls[0]
tool_call.function.arguments  # LLM이 작성한 입력 인자
실행 결과
'{"product_name":"무선 마우스"}'

LLM의 요청을 MCP 서버에서 실행하기

# 모델이 반환한 JSON 문자열을 파이썬 사전으로 변환
arguments = json.loads(tool_call.function.arguments)

async with Client(server) as mcp_client:
    # 모델이 요청한 이름과 인자로 서버의 도구 실행
    llm_result = await mcp_client.call_tool(
        tool_call.function.name,
        arguments,
    )

llm_result.data  # 서버에서 실제 조회한 결과
실행 결과
{'product_name': '무선 마우스', 'stock': 7}

실행 결과로 최종 답변 만들기

# 호출 요청과 그에 대응하는 실행 결과를 대화에 추가
messages.append(assistant_message.model_dump(exclude_none=True))
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(llm_result.data, ensure_ascii=False),
})

# MCP 조회 결과를 모델 API로 전달해 답변 생성
final_response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=llm_tools,
    tool_choice="none",  # 추가 호출 없이 조회 결과로 답변
)
final_response.choices[0].message.content
실행 결과
'무선 마우스는 현재 7개 남아 있습니다.'
  • 확인: LLM이 요청한 상품과 서버의 조회 대상이 같은가? 최종 답변의 수량이 llm_result.data와 일치하는가?

다른 애플리케이션에 연결할 때

  • 같은 서버를 별도 프로그램으로 실행하면 MCP를 지원하는 애플리케이션에서 연결 가능.
  • 로컬 프로그램에는 표준 입출력 방식, 원격 서버에는 HTTP 방식 등을 사용.
  • 연결 설정은 호스트 애플리케이션에서 담당. MCP를 사용해도 접근 권한과 어떤 도구를 허용할지 결정하는 일은 필요.

출처: MCP 구조, FastMCP 클라이언트, 도구 호출.

모델 API에 MCP 연결을 맡기는 방식

  • 원격 MCP 연결 기능을 지원하는 모델 API에서는 질문과 함께 MCP 서버 주소·사용할 도구 설정을 전달 가능.
  • 모델 API 서비스가 MCP 클라이언트 역할을 맡아 도구 목록 조회·실행·결과 전달을 처리. 애플리케이션은 요청을 보내고 최종 답변을 받는 구조.
  • 서버는 모델 API 서비스에서 접근 가능한 HTTP 주소로 제공. 이번 실습의 노트북 내부 연결과 달리 외부에서 접속할 서버 준비 필요.

Mermaid 다이어그램 원문

sequenceDiagram
    autonumber
    participant A as 애플리케이션
    participant P as 모델 API 서비스
    participant L as LLM
    participant S as 원격 MCP 서버
    A->>P: 질문과 MCP 서버 주소·도구 설정
    P->>S: 도구 목록 요청
    S-->>P: 도구 이름·설명·입력 형식
    P->>L: 질문과 도구 정의
    L-->>P: 도구 호출 요청
    P->>S: 도구 실행 요청
    S-->>P: 실행 결과
    P->>L: 호출 기록과 실행 결과
    L-->>P: 최종 답변
    P-->>A: 최종 답변 반환

대화형 다이어그램을 불러오기 전에는 원문으로 표시됩니다.

  • 실습 방식: 애플리케이션이 LLM 호출과 MCP 통신을 직접 연결.
  • API에 맡기는 방식: 모델 API 서비스가 두 통신을 연결. 애플리케이션에서 도구 실행과 결과 전달을 처리하는 코드가 줄어듦.
  • 지원 예: Claude API의 MCP connector. 자세한 설정과 사용법은 공식 API 안내 참고.

퀴즈

문제 1 / 4맞음: 0힌트: 0틀림: 0채점중: 0남음: 4

MCP가 해결하려는 문제는?

  • ○외부 도구·자료를 공통 통신 방식으로 연결하는 문제
  • ○모델의 답변을 모두 같은 문체로 만드는 문제
  • ○모든 도구의 계산 결과를 미리 학습하는 문제
  • ○여러 모델의 파라미터를 하나로 합치는 문제

퀴즈를 풀려면 대화형 기능을 불러와야 합니다.

Previous
특정 작업 잘하기