https://discuss.pytorch.kr/t/deep-research-model-context-protocol-mcp/6594
[Deep Research] Model Context Protocol(MCP) 개념 및 이해를 위한 학습 자료
MCP(Model Context Protocol) 개념 및 이해를 위한 학습 자료 MCP의 기본 개념 및 역할 MCP(Model Context Protocol)는 AI 모델과 외부 데이터 소스 또는 도구를 연결해주는 개방형 표준 프로토콜입니다. 쉽게 말해
discuss.pytorch.kr
1. MCP의 기본 개념 및 역할
MCP(Model Context Protocol)는 AI 모델과 외부 데이터 소스 또는 도구를 연결해주는 개방형 표준 프로토콜입니다.
쉽게 말해 AI 모델이 필요한 맥락(Context) 이나 정보를 외부에서 가져올 수 있도록 해주는 통로 역할을 합니다.
기존에는 언어 모델(LLM)이 자신에게 주어진 텍스트 외에 별도의 지식이나 데이터에 접근하기 어려워, 새로운 데이터 원본마다 별도 커스텀 통합이 필요했습니다 (Introducing the Model Context Protocol \ Anthropic).
MCP는 이러한 문제를 해결하고자 등장했으며, AI 분야의 USB-C 포트와 같은 표준화된 연결 방식으로 비유됩니다 (Introduction - Model Context Protocol).
즉, MCP를 지원하는 어떤 AI 애플리케이션도 MCP를 지원하는 어떤 데이터 소스와도 쉽게 연결될 수 있어 보안적이고 양방향적인 데이터 연동이 가능해집니다 (Introducing the Model Context Protocol \ Anthropic).
MCP의 핵심 목표는 AI 모델을 고립된 상태에서 꺼내 현실 세계의 데이터와 도구에 직접 접근하게 함으로써, 보다 관련성 높고 유용한 응답을 생성하도록 돕는 것입니다 (Introducing the Model Context Protocol \ Anthropic) (Introducing the Model Context Protocol \ Anthropic).
예를 들어, MCP 없이 AI 앱을 개발하면 특정 데이터베이스나 파일 시스템에 접근하기 위해 각각 다른 API나 라이브러리를 사용해 개별 통합을 만들어야 했습니다.
하지만 MCP를 도입하면 한 번 MCP 표준을 구현해두는 것으로, 다양한 데이터 소스에 대한 접근을 한꺼번에 표준화할 수 있습니다 (Model Context Protocol (MCP) - NSHipster) (Model Context Protocol (MCP) - NSHipster).
이런 표준화를 통해 개발자는 통합에 소모되는 시간을 줄이고, 확장성과 상호운용성을 갖춘 AI 솔루션을 구축할 수 있습니다.
요약하면 MCP의 역할은:
- AI 모델(예: 챗봇, 코딩 도우미 등)이 외부 지식/데이터(컨텍스트) 를 얻도록 도와주고 (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub) (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub),
- 표준 프로토콜을 통해 다양한 도구(웹 API, 데이터베이스, 파일 등)를 안전하게 사용할 수 있게 하며,
- 이를 통해 AI 응용 프로그램의 한계를 확장하고 맥락 인지 능력을 높여주는 것입니다 (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub) (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub).
2. MCP의 주요 구성 요소 (Context, Model, Protocol 등)
MCP는 클라이언트-서버 구조를 따르며 몇 가지 핵심 구성 요소로 이루어집니다 (What is Model Context Protocol (MCP): Explained in detail - DEV Community).
각 구성 요소는 다음과 같습니다:
- MCP 호스트(Host) : AI 모델을 운용하는 주체 애플리케이션입니다. 예를 들어 Claude Desktop, IDE의 AI 어시스턴트, 채팅 애플리케이션 등이 호스트에 해당합니다 (What is Model Context Protocol (MCP): Explained - Composio) (What is Model Context Protocol (MCP): Explained - Composio). 호스트는 사용자로부터 질문이나 명령을 받아 모델에게 전달하고, 모델의 응답을 사용자에게 보여주는 전체 흐름을 조율합니다. 또한 내부에 MCP 클라이언트를 구동하여 MCP 서버들과 연결을 유지합니다.
- MCP 클라이언트(Client) : 호스트 애플리케이션 내부에서 동작하며, 하나의 MCP 서버와 1:1 연결을 담당하는 컴포넌트입니다 (Model Context Protocol (MCP) - NSHipster) (What is Model Context Protocol (MCP): Explained - Composio). 호스트는 여러 종류의 데이터를 쓰기 위해 여러 서버에 연결할 수 있는데, 이때 각 서버마다 전담 클라이언트가 필요합니다. MCP 클라이언트는 AI 모델 측(호스트 측) 에서 MCP 프로토콜을 구현하며, 서버로 요청을 보내고 응답을 받아 모델에 전달하는 역할을 합니다.
- MCP 서버(Server) : 외부 데이터나 기능을 제공하는 측입니다. MCP 서버는 하나의 특정 서비스나 데이터 소스를 감싸서 모델이 이해할 수 있는 형태로 맥락(Context)을 제공합니다 (What is Model Context Protocol (MCP): Explained - Composio) (What is Model Context Protocol (MCP): Explained in detail - DEV Community). 예를 들어 파일 시스템 MCP 서버는 파일 읽기 기능을, 날씨 MCP 서버는 날씨 정보 제공 기능을, 데이터베이스 MCP 서버는 쿼리 실행 기능을 노출할 수 있습니다. MCP 서버는 자신이 제공하는 기능을 표준화된 인터페이스로 정의하여 MCP 클라이언트 요청에 응답합니다. 하나의 호스트(예: AI IDE)는 여러 MCP 서버(파일, Git, 데이터베이스 등)에 동시에 연결해 다양한 맥락을 얻을 수 있습니다.
- 맥락(Context) 요소: MCP 서버가 제공하는 실제 데이터와 도구들을 통칭합니다. MCP에서는 맥락 요소를 세 가지 범주로 나누어 정의합니다 (Model Context Protocol (MCP) - NSHipster):
- Resources(리소스) : 모델이 참고할 읽기 전용 데이터입니다. 파일의 내용, 데이터베이스 레코드, 문서 등 구조화된 정보를 포함하며, 모델의 지식 기반을 확장합니다 (Model Context Protocol (MCP) - NSHipster). 예를 들어 파일 시스템 서버는 file://경로 형태의 리소스를 통해 파일 내용을, DB 서버는 query://... 형태로 쿼리 결과를 제공할 수 있습니다.
- Tools(도구) : 모델이 호출할 수 있는 기능 또는 함수입니다. 계산, 웹 API 요청, 외부 시스템 동작 등 모델이 단순 문장 생성만으로 수행할 수 없는 작업을 대행합니다 (Model Context Protocol (MCP) - NSHipster). 예를 들어 날씨 서버의 "현재날씨 조회", Slack 서버의 "메시지 보내기" 등이 도구로 구현됩니다. 도구는 실행이 일회성이며 입력 파라미터와 출력 형식을 정의합니다.
- Prompts(프롬프트) : 모델에게 특정 지시나 템플릿을 제공하는 문구입니다. 반복적으로 쓰이는 지침이나 형식화된 요청을 미리 정의해 두고 필요할 때 불러서 모델의 응답 형태를 조절합니다 (Model Context Protocol (MCP) - NSHipster). 예를 들어 “다음 메시지를 요약하라”와 같은 템플릿을 프롬프트로 등록해둘 수 있습니다. 프롬프트는 일종의 미리 작성된 시스템/사용자 메시지라고 볼 수 있습니다.
이러한 리소스, 도구, 프롬프트는 모두 모델의 컨텍스트 윈도우에 포함될 수 있는 내용으로, MCP 서버는 이들을 모델이 활용할 수 있게 규격화하여 제공합니다 (python-sdk/README.md at main · modelcontextprotocol/python-sdk · GitHub).
실제로 내부 구현을 보면, MCP 서버는 Resources를 통해 데이터를 노출하고(GET 요청 유사), Tools를 통해 동작을 노출하며(POST 요청 유사), Prompts를 통해 상호작용 패턴까지 정의할 수 있습니다 (python-sdk/README.md at main · modelcontextprotocol/python-sdk · GitHub).
모든 MCP 서버는 이 중 필요한 기능만 구현할 수도 있고, 모두 구현할 수도 있습니다.
- 프로토콜(Protocol) : MCP의 핵심인 통신 규약입니다. MCP는 통신에 JSON-RPC 2.0을 기반으로 한 표준 메시지 형식을 사용합니다 (Model Context Protocol (MCP) - NSHipster) (Model Context Protocol (MCP) - NSHipster). 클라이언트와 서버는 JSON 구조의 요청(request)과 응답(response)을 주고받으며, 각 메시지에는 id, method(또는 result), params 등이 포함됩니다. 통신 경로는 표준 입출력(stdin/stdout) 이나 HTTP(SSE) 등을 활용하며, 상황에 따라 스트림 형태의 전송(Server-Sent Events)도 지원합니다 (Model Context Protocol (MCP) - NSHipster). 프로토콜 레벨에서는 메시지의 프레이밍, 요청-응답 매칭, 에러 처리 등이 표준화되어 있어, 서로 다른 구현체라도 일관된 방식으로 대화할 수 있습니다. 요약하면, MCP 프로토콜은 클라이언트와 서버가 어떻게 대화하고 상호작용하는지를 정의한 약속이며 (What is Model Context Protocol (MCP): Explained in detail - DEV Community) (What is Model Context Protocol (MCP): Explained in detail - DEV Community), 이를 따르는 한 어떤 클라이언트와 서버든 서로 호환됩니다.
MCP 클라이언트-서버 아키텍처: MCP 클라이언트(예: Cursor와 같은 AI 호스트 애플리케이션)는 MCP 서버와 MCP 프로토콜을 통해 통신합니다.
MCP 서버는 내부적으로 여러 고유한 API를 호출하여(예: GitHub API, Slack API, 로컬 파일 시스템 등) 필요한 데이터를 모읍니다.
클라이언트는 이러한 세부 사항을 몰라도 MCP 프로토콜로 서버에 요청을 보내고 응답을 받음으로써 다양한 소스의 데이터를 투명하게 활용할 수 있습니다.
3. 구성 요소별 Python 예시
위에서 설명한 MCP의 구성 요소들이 실제 코드에서는 어떻게 정의되는지 간단히 살펴보겠습니다.
MCP Python SDK를 사용하면, 서버 측에서 리소스나 도구를 쉽게 노출할 수 있도록 데코레이터를 제공합니다.
Tool 정의 예시: 두 수를 더하는 간단한 도구 함수를 MCP 서버에 추가한다고 가정해보겠습니다. Python SDK에서는 @mcp.tool() 데코레이터를 사용하여 함수를 도구로 등록합니다. 예를 들어:
!pip install mcp
from mcp.server.fastmcp import FastMCP
mcp = FastMCP('Demo')
@mcp.tool()
def add(a: int, b:int) -> int:
return a+b
위 코드에서 add 함수는 MCP 도구로 노출되며, 나중에 클라이언트가 "add"라는 도구를 호출하면 이 함수가 실행되어 결과를 반환합니다 (python-sdk/README.md at main · modelcontextprotocol/python-sdk · GitHub).
함수의 시그니처(인자 타입과 반환 타입)와 docstring을 토대로 SDK가 자동으로 도구의 스펙(입력 스키마 등)을 생성해줍니다 (For Server Developers - Model Context Protocol) (For Server Developers - Model Context Protocol).
Resource 정의 예시: MCP 리소스는 고유한 URI 형식으로 식별되는 읽기 전용 데이터입니다. 예를 들어 사용자 이름을 받아 환영 인사를 제공하는 리소스를 정의해보겠습니다. Python SDK에서는 @mcp.resource("<URI패턴>") 데코레이터를 사용합니다.
@mcp.resource('greeting://{name}')
def get_greeting(name:str) -> str:
"""개인화된 환영 인사 반환"""
return f'Hello, {name}!'
위 리소스는 "greeting://Alice"와 같이 이름을 URI에 넣어 요청하면 함수 get_greeting이 실행되어 "Hello, Alice!"를 반환합니다 (python-sdk/README.md at main · modelcontextprotocol/python-sdk · GitHub).
리소스는 보통 고유한 스키마(예:greeting://)를 사용하여 식별하며, {}로 감싼 부분은 동적으로 받는 파라미터입니다.
Prompt 정의 예시: 프롬프트는 주로 복잡한 상호작용 패턴을 템플릿화하는데 사용됩니다. Python SDK에서도 프롬프트를 관리할 수 있지만, 간단한 예에서는 직접 보여주기보다는 개념적으로 이해하면 충분합니다. (프롬프트는 서버에서 제공하는 미리 정의된 지침으로, 필요 시 클라이언트가 모델에게 제공하여 일정한 형식의 응답을 유도하는 데 쓰입니다.)
정리하면, MCP 서버 코드에서는 위와 같이 리소스, 도구, 프롬프트를 함수로 구현하고 각각 데코레이터로 노출함으로써, MCP 프로토콜을 통해 사용할 수 있는 컨텍스트 자원들을 정의하게 됩니다.
4. MCP의 동작 방식 및 흐름
이제 MCP 클라이언트와 서버가 실제로 어떻게 상호작용하여 동작하는지 흐름을 살펴보겠습니다. 전반적인 과정은 다음과 같습니다:
1. 초기화(Initialize) : MCP 클라이언트가 서버에 연결을 시작하면, 가장 먼저 초기화 메시지를 서버에 보냅니다.
이 메시지에는 사용 가능한 MCP 프로토콜 버전 등 클라이언트의 정보가 담겨 있습니다 (Model Context Protocol (MCP) - NSHipster).
서버는 이를 받고 자신이 지원하는 기능과 버전을 응답하여 호환성 교섭을 합니다. 이 단계가 성공하면 클라이언트-서버 세션이 열립니다.
2. 기능 협상 및 발견: 세션이 열리면, 클라이언트는 서버가 어떤 맥락 기능들(리소스/도구/프롬프트 등)을 제공하는지 알아봅니다.
예를 들어 서버의 도구 목록을 알고 싶다면 클라이언트는 "tools/list" 메서드의 JSON-RPC 요청을 서버에 보냅니다.
그러면 서버는 자신이 보유한 도구들의 이름, 설명, 입력 스키마 등을 나열하여 응답합니다 (Model Context Protocol (MCP) - NSHipster) (Model Context Protocol (MCP) - NSHipster).
아래는 도구 목록 응답의 예시입니다:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "get_weather",
"description": "Returns current weather conditions for the specified coordinates.",
"inputSchema": {
"type": "object",
"properties": {
"latitude": { "type": "number" },
"longitude": { "type": "number" }
},
"required": ["latitude", "longitude"]
}
}
]
}
}
이 예에서 서버는 "get_weather"라는 하나의 도구를 노출했고, 해당 도구의 기능과 입력 형식을 JSON 스키마로 제공하고 있습니다 (Model Context Protocol (MCP) - NSHipster) (Model Context Protocol (MCP) - NSHipster).
마찬가지로 리소스에 대해서도 클라이언트는 "resources/index" 같은 요청으로 사용 가능한 리소스 URI들을 받을 수 있고, 프롬프트도 목록을 가져올 수 있습니다.
클라이언트는 이렇게 획득한 기능 목록을 AI 모델에게 알려주거나(예: 시스템 프롬프트로 전달) 사용자 인터페이스에 표시하여 사용자가 선택하게 할 수도 있습니다.
3. 모델의 요청 처리: 이제 사용자가 AI 호스트 애플리케이션에 질문을 하면, 호스트는 우선 AI 모델에게 질문을 전달합니다 (For Server Developers - Model Context Protocol).
모델(예: GPT나 Claude)은 자신이 사용할 수 있는 도구와 리소스 목록을 컨텍스트로 알고 있으므로, 질문에 답하기 위해 외부 도구를 사용해야 할 필요를 판단할 수 있습니다 (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub) (For Server Developers - Model Context Protocol).
예를 들어 사용자의 질문이 “지금 서울의 날씨가 어때?”라면, 모델은 “날씨를 알려면 get_weather 도구를 써야겠군”이라고 결론내릴 수 있습니다.
이때 모델은 일차적으로는 도구를 어떻게 호출할지 결과만 만들어내며, 실제 호출은 하지 않습니다.
모델의 출력은 (명시적이든 암묵적이든) 어떤 도구를 어떤 인자로 써달라는 요청 형태로 표현됩니다.
4. 도구 호출 요청: 모델이 특정 MCP 도구를 사용하고자 하면, 호스트의 MCP 클라이언트가 개입해 해당 도구 호출을 실제 수행합니다 (Model Context Protocol (MCP) - NSHipster) (For Server Developers - Model Context Protocol).
클라이언트는 모델의 지시에 따라 MCP 서버로 "tools/call" 요청을 보내며, 호출할 도구 이름과 인자들을 JSON으로 전달합니다.
예를 들어 위의 날씨 질문에서 모델이 get_weather를 쓰고 싶어 했다면, 클라이언트는 다음과 같은 요청을 날립니다:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"latitude": 37.5665,
"longitude": 126.9780
}
}
}
서버는 이 요청을 받아 get_weather 함수(도구)를 실행하고, 결과를 JSON 형태로 반환합니다. 만약 성공이라면 "result" 필드에, 실패 시 "error" 필드에 응답이 오게 됩니다. 예를 들어 날씨 정보를 성공적으로 가져왔다면:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\"temperature\": 12, \"conditions\": \"cloudy\", \"humidity\": 85}",
"annotations": { "audience": ["assistant"] }
}
]
}
}
위와 같이 서버는 날씨 API로부터 얻은 데이터를 텍스트(JSON 문자열) 형태로 응답하고 있습니다 (Model Context Protocol (MCP) - NSHipster).
MCP 응답 포맷에서 content 필드는 모델에게 삽입될 정보이며, "audience": ["assistant"]라는 주석은 이 결과가 모델(assistant)에게만 보이는 컨텍스트임을 나타냅니다 (Model Context Protocol (MCP) - NSHipster).
즉 사용자에게 직접 노출되지 않고 모델의 답변 생성에만 사용됩니다.
5. 모델 응답 생성: MCP 서버로부터 필요한 외부 데이터나 실행 결과를 받은 AI 모델은 이제 사용자에게 줄 최종 답변을 생성합니다 (For Server Developers - Model Context Protocol).
앞의 예에서 모델은 get_weather의 결과(JSON 문자열로 인코딩된 날씨 정보)를 보고 “현재 서울의 기온은 12도이고, 날씨는 흐림입니다.”와 같은 자연어 문장을 만들어낼 것입니다.
이 응답 생성에는 모델 고유의 언어 생성 능력이 활용되며, MCP로부터 얻은 맥락 정보가 답변 내용에 반영됩니다.
6. 사용자에게 응답 전달: 마지막으로 호스트 애플리케이션은 모델이 생성한 답변을 사용자에게 출력합니다.
이렇게 해서 사용자의 질문에 대해 외부 정보를 활용한 답변이 완료됩니다.
위 과정에서 중요한 것은, MCP를 통해 모델이 외부 도구를 사용할 때 항상 사용자의 승인이나 사전 정의된 정책에 따라 이뤄진다는 점입니다 (Model Context Protocol (MCP) - NSHipster).
예컨대 어떤 MCP 클라이언트 구현은 모델이 도구를 쓰려 할 때 사용자에게 “모델이 현재날씨 도구를 사용하려 합니다. 허용할까요?”라고 확인을 구한 후 진행하기도 합니다.
이를 통해 보안과 통제를 유지하면서도 모델의 자율성을 부여할 수 있습니다.
요약하면, MCP 동작 흐름은 (1) 연결 및 기능 교환 → (2) 모델 질의 처리 → (3) 필요한 경우 MCP 서버 호출 → (4) 결과를 모델에 제공 → (5) 모델이 최종 응답 생산의 단계로 진행됩니다 (For Server Developers - Model Context Protocol).
이러한 통신은 모두 JSON-RPC 기반의 표준화된 메시지로 교환되므로, 서로 다른 언어나 플랫폼으로 구현된 MCP 클라이언트/서버라도 원활히 협력할 수 있습니다 (Model Context Protocol (MCP) - NSHipster) (What is Model Context Protocol (MCP): Explained in detail - DEV Community).
5. Python을 활용한 예제 코드
이번에는 실제 Python 코드를 통해 MCP를 사용하는 예제를 단계별로 알아보겠습니다.
간단한 예제부터 시작하여 점차 복잡한 구조로 발전시키면서 MCP의 적용 방법을 익혀보겠습니다.
각 단계의 코드에는 주석과 설명을 함께 제공하여 이해를 도울 것입니다.
예제 1: 간단한 덧셈 MCP 서버
가장 기본적인 MCP 서버를 만들어보겠습니다. 이 서버의 목적은 매우 단순하게, 두 수를 더하는 기능을 MCP 도구로 제공하는 것입니다. 이를 통해 MCP 서버를 정의하고 실행하며, 도구를 노출하는 방법을 익힐 수 있습니다.
# demo_server.py
from mcp.server.fastmcp import FastMCP
# 1. MCP 서버 초기화
mcp = FastMCP("Demo") # "Demo"라는 이름의 MCP 서버 생성
# 2. Tool 정의: 두 수의 합을 반환하는 도구
@mcp.tool()
def add(a: int, b: int) -> int:
"""두 숫자를 입력 받아 합계를 반환"""
return a + b
# 3. 서버 실행 엔트리포인트
if __name__ == "__main__":
mcp.run() # MCP 서버 실행 (기본 transport=stdio)
먼저 FastMCP("Demo")를 통해 이름이 "Demo"인 MCP 서버 인스턴스를 생성했습니다.
그런 다음 @mcp.tool() 데코레이터를 이용하여 add 함수를 MCP 도구로 등록했습니다.
이 함수는 두 정수를 입력 받아 그 합을 돌려주는 간단한 로직입니다.
마지막으로 mcp.run()을 호출하여 서버를 실행합니다.
mcp.run()을 실행하면 이 서버는 MCP 프로토콜을 따르는 서버 프로세스로 동작하며, 클라이언트의 요청을 대기하게 됩니다.
위 코드를 demo_server.py라는 파일에 저장하고, 터미널에서 python demo_server.py를 실행하면 MCP 서버가 시작됩니다.
이 상태에서 MCP 클라이언트가 이 서버에 연결하면, add 도구를 호출하여 기능을 활용할 수 있습니다.
예를 들어 (의사 코드이지만) 클라이언트 측에서 JSON-RPC로 {"method": "tools/call", "params": {"name": "add", "arguments": {"a": 3, "b": 5}}}를 보내면, 서버는 add(3,5)를 실행하고 결과 8을 응답하게 됩니다.
이러한 간단한 MCP 서버는 실제로 Claude Desktop과 같은 호스트 애플리케이션에 연결하여 사용할 수도 있습니다 (python-sdk/README.md at main · modelcontextprotocol/python-sdk · GitHub). mcp install server.py 명령이나 Claude Desktop 설정에 서버 경로를 등록하면, Claude와 같은 AI 비서가 대화 중 이 add 도구를 필요에 따라 활용할 수 있습니다.
하필 지금 서버 에러라 못해보네
예제 2: 리소스와 도구를 활용한 확장된 MCP 서버
이제 조금 더 복잡한 MCP 서버를 만들어 보겠습니다. 이번 서버는 나라별 정보를 제공한다고 가정하겠습니다. 내부적으로 간단한 데이터베이스(파이썬 딕셔너리)를 가지고 국가 이름과 수도를 저장해두고, 두 가지 기능을 MCP로 노출합니다:
- Resource: 모든 국가 이름의 목록을 제공 (읽기 전용 데이터)
- Tool: 주어진 국가의 수도를 반환 (동적 기능)
# country_server.py
from mcp.server.fastmcp import FastMCP
# 간단한 "국가-수도" 데이터베이스 (딕셔너리)
capitals = {
"대한민국": "서울",
"United States": "Washington, D.C.",
"France": "Paris",
"Japan": "Tokyo"
}
# MCP 서버 생성
mcp = FastMCP("CountryInfo")
# 1. Resource 정의: 모든 국가 리스트 제공
@mcp.resource("country://list")
def list_countries() -> list[str]:
"""사용 가능한 모든 국가 이름 리스트 반환"""
return list(capitals.keys())
# 2. Tool 정의: 특정 국가의 수도 조회
@mcp.tool()
def get_capital(country: str) -> str:
"""주어진 국가의 수도 이름을 반환"""
return capitals.get(country, "Unknown")
# 서버 실행
if __name__ == "__main__":
mcp.run()
capitals 딕셔너리에 몇 개 국가의 수도 정보를 저장했습니다.
FastMCP("CountryInfo")로 MCP 서버를 생성하고, 두 가지 기능을 추가했습니다.
@mcp.resource("country://list") 데코레이터는 list_countries 함수를 MCP 리소스로 노출하는데, 여기서는 URI를 "country://list"로 정의했습니다.
이 리소스를 조회하면 capitals의 모든 키(국가 이름)를 리스트로 반환합니다.
다음으로 @mcp.tool()을 사용해 get_capital 함수를 도구로 등록했습니다.
이 도구는 country라는 이름의 문자열 인자를 받아 해당 국가의 수도를 딕셔너리에서 찾아 반환합니다. 만약 딕셔너리에 없으면 "Unknown"을 반환하도록 했습니다.
이 서버가 실행되고 MCP 클라이언트가 연결되면, 클라이언트는 우선 "country://list" 리소스를 통해 어떤 국가들이 지원되는지 얻을 수 있습니다.
그런 다음 사용자가 질문하기를 “프랑스의 수도는 어디인가요?”라고 했다면, AI 모델은 get_capital 도구를 인식하고 "France"를 인자로 사용하려 할 것입니다.
클라이언트는 서버에 get_capital("France") 호출을 요청하고, 서버는 "Paris"라는 결과를 돌려주겠지요.
그럼 모델이 최종적으로 “프랑스의 수도는 파리입니다.”라고 답변할 수 있을 것입니다.
반대로 사용자가 “어떤 국가 정보를 알 수 있어?”라고 물으면, 모델은 country://list 리소스를 참고하도록 만들어 “대한민국, United States, France, Japan 정보를 제공할 수 있습니다.”라고 답변할 수 있습니다.
이 예제는 리소스와 도구를 함께 활용하는 MCP 서버의 단순 모델입니다.
실제 응용에서는 데이터를 파일이나 DB에서 로드하거나, 도구 내에서 외부 API를 호출하는 등 더 복잡한 일이 일어나지만, MCP를 통해 구조화된 방식으로 데이터 접근(리소스)와 기능 수행(도구)을 모두 노출할 수 있다는 점을 보여줍니다.
예제 3: 외부 API와의 연계 (날씨 정보 MCP 서버)
마지막으로, 실제 외부 웹 API를 연계하여 MCP 서버를 구성하는 예를 간략히 살펴보겠습니다.
Anthropic에서 제공하는 튜토리얼의 날씨 서버 사례를 참고하겠습니다 (For Server Developers - Model Context Protocol).
이 서버는 미국 기상청(National Weather Service)의 공개 API를 사용하여 두 가지 도구를 제공합니다:
- get_forecast(lat, lon): 주어진 위도/경도의 날씨 예보 정보를 가져옴
- get_alerts(state_code): 주어진 미국 주(State)의 기상 경보(alert) 정보를 가져옴
코드 일부를 발췌해 구조를 보면 다음과 같습니다:
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("weather")
NWS_API_BASE = "https://api.weather.gov"
# (도우미 함수) 기상청 API 호출 함수
async def make_nws_request(url: str) -> dict | None:
"""주어진 URL에 대해 NWS API 호출을 수행하여 JSON 결과 반환"""
# ... (헤더 설정 및 httpx AsyncClient로 요청 수행) ...
return response.json() if 성공 else None
# Tool 1: 기상 경보 조회
@mcp.tool()
async def get_alerts(state: str) -> str:
"""주(State) 코드를 입력 받아 해당 지역의 기상 경보를 반환"""
url = f"{NWS_API_BASE}/alerts/active/area/{state}"
data = await make_nws_request(url)
if not data or "features" not in data or not data["features"]:
return "해당 주에 대한 경보 정보를 가져올 수 없습니다."
# 여러 경보 메시지를 포매팅
alerts = [format_alert(f) for f in data["features"]]
return "\n---\n".join(alerts)
# Tool 2: 날씨 예보 조회
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
"""위도, 경도를 입력 받아 날씨 예보를 반환"""
points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
points_data = await make_nws_request(points_url)
if not points_data:
return "해당 위치의 예보 정보를 가져올 수 없습니다."
forecast_url = points_data["properties"]["forecast"]
forecast_data = await make_nws_request(forecast_url)
# ... (데이터가 없을 경우 에러 문자열 반환) ...
# 받아온 예보 데이터에서 주요 부분만 포매팅하여 반환
periods = forecast_data["properties"]["periods"][:5] # 다섯 구간만
forecasts = []
for period in periods:
forecast_text = (
f"{period['name']}: {period['detailedForecast']} "
f"(온도: {period['temperature']}{period['temperatureUnit']}, "
f"풍속: {period['windSpeed']} {period['windDirection']})"
)
forecasts.append(forecast_text)
return "\n---\n".join(forecasts)
if __name__ == "__main__":
mcp.run(transport="stdio")
이 서버 코드는 실제 웹 API 호출이 들어가 있어서 async 비동기 함수로 구현된 점이 눈에 띕니다.
httpx 라이브러리를 이용해 REST API를 호출하고 있으며, 결과를 가공하여 문자열로 반환합니다.
get_alerts 도구는 입력으로 예를 들어 "CA"(캘리포니아 주 코드)를 받으면, {NWS_API_BASE}/alerts/active/area/CA로 API를 호출하고 경보 목록을 가져옵니다 (For Server Developers - Model Context Protocol).
경보가 있다면 format_alert라는 도우미 함수를 통해 사람이 읽기 좋은 형태의 문자열로 만들고, 여러 경보를 하나의 문자열로 합쳐 반환합니다 (For Server Developers - Model Context Protocol).
get_forecast 도구는 위도와 경도를 받아 먼저 해당 지점의 예보 API URL을 얻고, 다시 그 URL로 상세 예보를 가져와 여러 날치 예보를 정리한 문자열을 반환합니다 (For Server Developers - Model Context Protocol).
마지막에 mcp.run(transport="stdio")로 서버를 실행하는데, Claude Desktop 등의 로컬 애플리케이션과 통신할 것을 가정하여 표준 입출력 기반으로 동작시켰습니다 (For Server Developers - Model Context Protocol).
이 서버를 실행하고 Claude Desktop의 설정에 등록하면, Claude 인터페이스 내에서 자동으로 두 개의 도구(get_alerts, get_forecast)가 사용 가능함을 인식합니다 (For Server Developers - Model Context Protocol).
사용자는 Claude에게 “텍사스의 기상 경보 알려줘” 또는 “서울 (위도 경도)에 대한 날씨 예보 알려줘”와 같이 물어볼 수 있고, Claude는 해당 MCP 도구를 호출하여 얻은 최신 정보를 바탕으로 답변하게 됩니다 (For Server Developers - Model Context Protocol).
이처럼 MCP 서버는 실시간 외부 데이터를 AI 모델이 활용할 수 있게 해주므로, 독립적인 AI 모델만으로는 얻을 수 없는 최신 정보나 특정 기능을 통합할 수 있습니다.
6. 실세계 응용 사례와 코드 예제
MCP는 다양한 실세계 시나리오에서 활용될 수 있으며, 이미 여러 오픈 소스 MCP 서버 구현체들이 등장하여 그 가능성을 보여주고 있습니다 (Introducing the Model Context Protocol \ Anthropic).
마지막으로 몇 가지 응용 사례를 소개하고, 해당 맥락에서 MCP 코드가 어떻게 구성될 수 있는지 살펴보겠습니다.
파일 시스템 액세스: 로컬 파일을 읽거나 검색하는 MCP 서버를 구축하면, AI 비서가 사용자 컴퓨터 내의 정보를 직접 조회할 수 있습니다.
예를 들어, 프로젝트 디렉토리의 README나 로그 파일 내용을 읽어와 요약해준다든지, 특정 키워드로 파일을 검색해주는 기능을 생각할 수 있습니다.
실제 사례로, 한 오픈 소스 MCP 서버는 파일을 리소스로 노출하고 파일 검색을 도구로 제공하는 구현을 선보였습니다 (GitHub - punkpeye/mcp-filesystem-python: A MCP Filesystem implementation for Claude, written mostly by Claude).
이 서버는 file:// URI 스킴을 통해 파일 콘텐츠를 안전하게 읽을 수 있는 리소스를 지원하고, search_file(keyword)와 같은 도구를 통해 해당 디렉토리 내 파일들을 검색해주는 식입니다.
내부적으로 경로 접근은 .gitignore를 존중하고 디렉토리 경로 이탈(경로 탐색 공격)을 막는 등 보안에도 신경 쓰고 있습니다 (GitHub - punkpeye/mcp-filesystem-python: A MCP Filesystem implementation for Claude, written mostly by Claude) (GitHub - punkpeye/mcp-filesystem-python: A MCP Filesystem implementation for Claude, written mostly by Claude). 아래는 파일 내용 읽기 리소스와 검색 도구의 코드 개략 예시입니다:
# 파일 시스템 MCP 서버 예시 코드
mcp = FastMCP("FileServer")
BASE_DIR = "/my/project" # 접근 허용 베이스 디렉토리
@mcp.resource("file://{path}")
def read_file(path: str) -> str:
"""주어진 경로의 파일 내용을 반환 (읽기 전용)"""
full_path = os.path.join(BASE_DIR, path)
if not full_path.startswith(BASE_DIR) or not os.path.exists(full_path):
raise FileNotFoundError("파일을 찾을 수 없거나 접근 불가")
with open(full_path, 'r', encoding='utf-8') as f:
return f.read()
@mcp.tool()
def search(keyword: str) -> list[str]:
"""베이스 디렉토리 내에서 키워드가 포함된 파일 목록 반환"""
result_files = []
for root, dirs, files in os.walk(BASE_DIR):
for fname in files:
fpath = os.path.join(root, fname)
# .gitignore 등 무시해야 할 파일 처리 (생략)
with open(fpath, 'r', errors='ignore') as f:
text = f.read()
if keyword in text:
result_files.append(fpath)
return result_files
위 코드에서 read_file 리소스는 file://notes/todo.txt처럼 경로를 받아 해당 파일 내용을 반환합니다.
search 도구는 재귀적으로 디렉토리를 탐색하며 키워드를 찾고, 포함된 파일 경로 리스트를 반환합니다.
이런 MCP 서버가 있으면 모델은 “file://notes/todo.txt 내용을 요약해줘”라는 사용자 요청에 해당 리소스를 불러와 요약하거나, “프로젝트 내 'ERROR' 로그가 있는 파일 찾아줘”라는 요청에 search("ERROR") 도구를 호출하여 결과를 얻은 뒤 응답할 수 있습니다.
업무 도구 통합 (예: Slack, Google Drive 등) : 업무용 채팅이나 문서 도구와 연결된 MCP 서버를 사용하면, AI가 조직 내 커뮤니케이션이나 문서를 직접 다룰 수 있습니다.
Anthropic에서는 이미 Google Drive, Slack, GitHub, Git, Postgres 등에 대한 MCP 서버 예제를 공개하여, 다양한 기업 환경 데이터를 AI와 연계하는 시도를 하고 있습니다 (Introducing the Model Context Protocol \ Anthropic).
예를 들어 Slack MCP 서버는 최근 채널 메시지를 읽어오는 리소스와 메시지 보내기 도구를 제공할 수 있습니다.
코드 측면에서, Slack의 Web API를 호출하는 래퍼 함수들을 만들고 이를 MCP 도구로 노출하면 됩니다. 대략적인 예는 다음과 같습니다:
# Slack MCP 서버 예시 (개념적 코드)
SLACK_TOKEN = "xoxb-... (API 토큰)"
slack_client = SlackWebClient(token=SLACK_TOKEN)
@mcp.resource("slack://channel/{channel_id}")
def get_recent_messages(channel_id: str) -> str:
"""지정한 채널의 최근 N개 메시지를 취합하여 반환"""
messages = slack_client.fetch_messages(channel=channel_id, limit=10)
return "\n".join(f"<{msg['user']}> {msg['text']}" for msg in messages)
@mcp.tool()
def post_message(channel_id: str, text: str) -> str:
"""지정한 채널에 메시지 게시"""
slack_client.post_message(channel=channel_id, text=text)
return "Message posted."
이렇게 하면 모델이 슬랙 채널의 대화 내용을 읽어서 요약하거나, 사용자의 지시에 따라 자동으로 Slack에 공지 글을 올리는 등의 작업을 수행할 수 있습니다.
실제로 초기 MCP 도입 기업들은 이러한 통합을 통해 에이전트형 AI의 업무 생산성을 높이고 있습니다.
예를 들어, 어떤 회사는 사내 Slack MCP 서버를 통해 AI 비서가 필요한 채널의 정보를 찾아 답변에 활용하게 했고, 개발 도구 회사들은 Git MCP 서버로 코드 컨텍스트를 제공하여 AI 코딩 도우미가 더 정확한 코드를 제안하도록 하였습니다 (Introducing the Model Context Protocol \ Anthropic).
데이터베이스 및 질의: 회사의 데이터베이스와 연결된 MCP 서버를 만들면 AI가 직접 DB를 조회해 최신 수치를 답변에 포함시킬 수 있습니다.
예컨대, @mcp.tool()로 구현된 run_query(sql: str) 같은 도구는 입력으로 SQL 쿼리를 받아 DB에서 실행한 결과를 반환할 수 있습니다.
이는 자연어로 들어온 질문을 모델이 SQL로 변환해서 질의하고, 결과를 가져와 답변하는 NL->SQL 케이스를 자동화할 수 있습니다. (물론 SQL 생성에는 주의가 필요하지만, MCP를 통해 사람이 검증하거나 read-only로 제한하는 등 통제가 가능합니다.)
Microsoft Azure OpenAI 팀에서도 MCP를 활용해 외부 데이터 조회와 프롬프트 강화를 결합하는 방안을 소개한 바 있습니다 (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub) (Model Context Protocol (MCP): Integrating Azure OpenAI for Enhanced Tool Integration and Prompting | Microsoft Community Hub).
위의 사례들에서 공통적으로 볼 수 있듯이, MCP를 사용하면 AI 에이전트가 서로 다른 여러 시스템과 표준화된 방식으로 소통할 수 있습니다.
MCP 서버 개발자들은 자신이 전문인 도메인(예: 파일 시스템, Slack, DB)의 접근 방법을 MCP 표준으로 래핑하고 (GitHub - punkpeye/mcp-filesystem-python: A MCP Filesystem implementation for Claude, written mostly by Claude), 호스트(모델) 개발자는 MCP 클라이언트 한 번 구현으로 다양한 서버에 연결해 쓸 수 있는 이점을 얻습니다 (What is Model Context Protocol (MCP): Explained in detail - DEV Community).
결국 MCP는 AI를 고립된 chatbot에서 벗어나 실제 도구와 데이터에 연결된 유용한 비서로 변모시키는 핵심 열쇠 중 하나입니다.
표준의 힘으로 개발자 커뮤니티가 각종 MCP 서버를 늘려가고 있고, 이를 지원하는 AI 클라이언트도 늘어나면서 MCP 에코시스템은 빠르게 확장되고 있습니다.
실제로 여러 AI 플랫폼과 IDE가 MCP를 채택하고 있는데, 예를 들어 IDE인 Cursor, Zed, 오픈소스 코드 비서 Continue, 웹 챗봇 프런트엔드 LibreChat 등이 MCP 클라이언트를 통해 다양한 MCP 서버와 연동하는 기능을 선보이고 있습니다 (Example Clients - Model Context Protocol) (Example Clients - Model Context Protocol).
이는 곧 개발자들이 MCP 서버만 만들어두면 다양한 AI 앱에서 곧바로 활용될 수 있다는 뜻이기도 합니다.
반대로 AI 애플리케이션 입장에서는 MCP 지원을 추가함으로써 손쉽게 새로운 기능을 얻을 수 있습니다.
요약하자면, MCP는 AI 시대의 표준 인터페이스로 부상하고 있으며, Python을 비롯한 여러 언어 SDK를 활용해 서버/클라이언트를 구현함으로써 실용적인 AI 에이전트를 만드는 토대가 되고 있습니다.
https://github.com/modelcontextprotocol/python-sdk
GitHub - modelcontextprotocol/python-sdk: The official Python SDK for Model Context Protocol servers and clients
The official Python SDK for Model Context Protocol servers and clients - modelcontextprotocol/python-sdk
github.com
'AI 논문 > AI trend research' 카테고리의 다른 글
| A Review of DeepSeek Models' Key Innovative Techniques (0) | 2025.03.28 |
|---|---|
| Transformers without Normalization (0) | 2025.03.25 |
| Introducing Instella: New State-of-the-art Fully Open 3B Language Models (0) | 2025.03.08 |
| The FFT Strikes Back: An Efficient Alternative to Self-Attention (0) | 2025.03.07 |
| SFT Memorizes, RL Generalizes: A Comparative Study of Foundation Model Post-training (0) | 2025.02.14 |