python3 -m venv .venv or python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt .venv\Scripts\python.exe app.py

로컬 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: Enterprise MCP Gateway and Tool Registry

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에서 실행 중이라고 표시되는지 확인하세요.

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

MCP