MCP
MCP 서버의 도구를 LLM에 연결하고, 호출 요청·서버 실행·결과 기반 답변을 확인한다.
외부 도구를 공통 방식으로 연결하기
- 모델 컨텍스트 프로토콜(Model Context Protocol, MCP): AI 애플리케이션이 외부 도구·자료에 연결하는 공통 통신 규약.
- 프로토콜(protocol): 프로그램끼리 정보를 주고받기 위해 정한 메시지 형식과 요청·응답 규칙.
- MCP는 도구 목록을 요청하는 방법, 도구 이름·입력 인자를 전달하는 방법, 실행 결과를 돌려주는 형식 등을 공통으로 정의.
- 예: 재고 조회를 제공하는 서버에 애플리케이션이 도구 이름과 상품 이름을 보내면, 서버가 조회 결과를 약속된 형식으로 반환.
- 도구를 연결해도 모델이 알아서 실행하는 것은 아님. 애플리케이션이 호출 요청을 서버에 보내고 결과를 모델에 전달.
USB-C 비유
- 외부 서비스마다 다른 연결 코드를 AI 애플리케이션별로 작성하면 같은 기능을 여러 번 연결해야 하는 부담.
- MCP 서버로 기능을 제공하면, 해당 기능을 MCP를 지원하는 여러 애플리케이션에서 공통 방식으로 발견·호출 가능.
- USB-C 비유: 장치마다 다른 단자를 만드는 대신 공통 단자로 연결하는 것처럼, 외부 기능에 접근하는 통신 방식을 통일.

- 그림 위쪽: 외부 기능을 이용하는 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 안내 참고.
퀴즈
MCP가 해결하려는 문제는?
퀴즈를 풀려면 대화형 기능을 불러와야 합니다.