MCP

Local MCP + Groq + OpenAI Agents SDK

이 수업 예제에는 다음이 포함됩니다:

• app.py: 여러 도구가 있는 지속적인 로컬 Streamable HTTP MCP 서버입니다.

• mcp_groq_agent.ipynb: 해당 도구를 발견하고 호출하는 에이전트입니다.

설정

Python 3.10 이상을 사용하세요. 터미널에서 이 프로젝트 폴더로 들어가 가상환경을 만들고 서버와 노트북 모두에 필요한 모든 것을 설치하세요(필요하면 python3.11을 최신 Python 명령어로 대체하세요):

cd /Users/somenathmandal/Documents/transfer/grok-playground/MCP
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

예제 파일에서 .env를 만들고 그 안에 Groq API 키를 넣으세요:

cp .env.example .env

GROQ_API_KEY=replace_with_your_groq_key
GROQ_MODEL=openai/gpt-oss-20b

.env는 절대 커밋하거나 공유하지 마세요. .gitignore에 의해 제외됩니다.

Related MCP server: MCP Python Server - Streamable HTTP

MCP 서버 실행

한 터미널에서 MCP 서버를 시작하고 실행 상태로 두세요:

source .venv/bin/activate
.venv/bin/python app.py

Streamable HTTP 엔드포인트는 이제 다음 주소에서 사용할 수 있습니다:

http://127.0.0.1:8000/mcp

그 터미널을 열어 두세요. 서버를 중지하려면 Ctrl+C를 누르세요.

에이전트 노트북 실행

두 번째 터미널에서:

cd /Users/somenathmandal/Documents/transfer/grok-playground/MCP
source .venv/bin/activate
jupyter lab mcp_groq_agent.ipynb

Jupyter가 요청하면 .venv Python 커널을 선택한 다음 셀을 위에서 아래로 실행하세요. 노트북은 http://127.0.0.1:8000/mcp에 직접 연결되며 app.py를 시작하거나 임포트하지 않습니다. Groq API 키는 .env에서 로드되며 노트북에 저장되지 않습니다.

구성 요소 연결 방식

Notebook agent
    -> Groq OpenAI-compatible API (model reasoning and tool selection)
    -> http://127.0.0.1:8000/mcp (tool discovery and execution)
    -> app.py MCP tools

MCP 연결 셀을 실행하기 전에 서버가 실행 중이어야 합니다. 노트북에서 연결 오류가 보고되면 먼저 서버 터미널에 Uvicorn이 http://127.0.0.1:8000에서 실행 중이라는 메시지가 표시되는지 확인하세요.

노트북은 또한 노트북 실행기에서 간혹 상속되는 오래된 인증서 파일 환경 변수를 방어합니다. 참조된 경로가 존재하지 않을 때만 인증서 변수를 제거하며, 유효한 사용자 정의 인증서 설정은 유지됩니다.