MCP + LangChain 데모

MCP(Model Context Protocol) 서버를 구축하고 LangChain 및 LangGraph를 사용하여 LLM 에이전트에 연결하는 방법을 보여주는 초보자 친화적인 프로젝트입니다.

MCP란 무엇인가요?

**MCP(Model Context Protocol)**는 사용자 정의 도구(함수)를 표준화된 방식으로 LLM에 노출할 수 있는 개방형 프로토콜입니다. AI 모델을 위한 범용 플러그인 시스템이라고 생각하면 됩니다.

핵심 개념:

Related MCP server: Model Context Protocol Multi-Agent Server

프로젝트 구조

MCPLEARNING/
├── mathserver.py      # MCP Server 1 - Math tools (stdio transport)
├── weather.py         # MCP Server 2 - Weather tool (HTTP transport)
├── client.py          # LangChain agent that connects to both servers
├── .env               # API keys (NOT pushed to GitHub)
├── .gitignore
├── requirements.txt
└── pyproject.toml

작동 방식 (단계별)

1단계: MCP 서버 — mathserver.py

이 파일은 **"Math"**라는 MCP 서버를 생성하며, 두 개의 도구를 노출합니다:

• add(a, b) — 두 정수의 합을 반환합니다.

• multiply(a, b) — 두 정수의 곱을 반환합니다.

stdio 전송 방식으로 실행되며, 클라이언트가 이를 하위 프로세스로 생성하고 stdin/stdout을 통해 통신합니다. 포트가 필요하지 않습니다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Addition of two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiplication of two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

2단계: MCP 서버 — weather.py

이 파일은 **"Weather"**라는 MCP 서버를 생성하며, 하나의 도구를 노출합니다:

• get_weather(location) — 주어진 위치에 대한 날씨 정보를 반환합니다.

streamable-http 전송 방식으로 실행되며, http://127.0.0.1:8000/mcp에서 웹 서버를 시작합니다. 클라이언트는 HTTP를 통해 연결합니다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> str:
    """Get the weather"""
    return "It's always raining in California"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

3단계: 클라이언트 에이전트 — client.py

이것은 프로젝트의 두뇌입니다. 다음을 수행합니다:

1. MultiServerMCPClient를 사용하여 두 MCP 서버에 모두 연결합니다.

2. 두 서버에서 모든 도구를 발견합니다(add, multiply, get_weather).

3. Groq LLM(호스팅된 오픈소스 모델)을 생성하고 도구를 바인딩합니다.

4. LangGraph 에이전트를 구축합니다. 이는 LLM이 도구를 호출할지 직접 응답할지 결정하는 상태 머신입니다.

   • 도구가 호출되면 결과가 최종 답변을 위해 LLM으로 다시 전달됩니다.

5. 두 가지 질의를 테스트합니다:

   • "What is 3 + 5?" → add 도구를 사용합니다.

   • "What is the weather in California?" → get_weather 도구를 사용합니다.

사전 요구 사항

• Python 3.13+

• uv 패키지 관리자(권장) 또는 pip

• Groq API 키 — console.groq.com에서 무료로 받으세요.

설정

1. 리포지토리 클론하기

git clone https://github.com/<YOUR_USERNAME>/MCPLEARNING.git
cd MCPLEARNING

2. 가상 환경 생성 및 활성화

# Using uv (recommended)
uv venv
uv pip install -r requirements.txt

# Or using pip
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Mac/Linux
pip install -r requirements.txt

3. API 키 설정

프로젝트 루트에 .env 파일을 생성하세요:

GROQ_API_KEY=your_groq_api_key_here

중요: .env 파일을 절대 커밋하지 마세요. .gitignore를 통해 제외됩니다.

프로젝트 실행하기

두 개의 터미널이 필요합니다:

터미널 1 — Weather MCP 서버 시작

python weather.py

다음과 같은 출력이 표시됩니다:

INFO: Uvicorn running on http://127.0.0.1:8000

참고: weather.py만 수동으로 시작해야 합니다. mathserver.py는 클라이언트에 의해 자동으로 생성됩니다(stdio 전송 방식).

터미널 2 — 클라이언트 실행

python client.py

예상 출력

Available MCP tools:
- add
- multiply
- get_weather

==============================
Testing Math MCP
==============================

Math Response: 3 + 5 = 8.

==============================
Testing Weather MCP
==============================

Weather Response: It's always raining in California.

나만의 MCP 서버를 만드는 방법

1. MCP 라이브러리 설치:

pip install mcp

2. 새 Python 파일 생성 (예: myserver.py):

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool()
def my_tool(param: str) -> str:
    """Description of what this tool does."""
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run(transport="stdio")        # For stdio transport
    # mcp.run(transport="streamable-http")  # For HTTP transport

3. 클라이언트에서 연결 — MultiServerMCPClient 구성에 추가:

client = MultiServerMCPClient({
    "myserver": {
        "command": "python",
        "args": ["myserver.py"],
        "transport": "stdio",
    },
})

전송 방식 비교

사용된 주요 라이브러리

주의해야 할 중요한 사항

1. 클라이언트보다 먼저 Weather 서버가 실행 중이어야 합니다 — HTTP 전송 방식을 사용하므로 서버 프로세스를 먼저 시작해야 합니다. Math 서버(stdio)는 클라이언트가 자동으로 생성합니다.

2. Groq API 키가 필요합니다 — 없으면 LLM 호출이 실패합니다. console.groq.com에서 무료 키를 받으세요.

3. .env를 절대 커밋하지 마세요 — 코드를 푸시하기 전에 항상 .gitignore에 .env를 추가하세요.

4. 포트 충돌 — Weather 서버는 기본적으로 8000번 포트에서 실행됩니다. 다른 프로세스가 해당 포트를 사용 중이면 서버가 시작되지 않습니다.

5. Windows 인코딩 문제 — Windows에서는 콘솔이 LLM이 반환하는 UTF-8 문자를 지원하지 않을 수 있습니다. client.py는 sys.stdout.reconfigure(encoding="utf-8")로 이를 처리합니다.

6. 모델 가용성 — Groq 모델 이름(openai/gpt-oss-120b)은 유효해야 하며 Groq 플랫폼에서 사용 가능해야 합니다. 현재 옵션은 Groq의 모델 목록을 확인하세요.