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

Local MCP + Groq + OpenAI Agents SDK

This classroom example contains:

• app.py: a persistent local Streamable HTTP MCP server with several tools.

• mcp_groq_agent.ipynb: an agent that discovers and calls those tools.

Setup

Use Python 3.10 or newer. In a terminal, enter this project folder, create a virtual environment, and install everything needed by both the server and notebook (replace python3.11 with your modern Python command if necessary):

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

Create .env from the example and put your Groq API key in it:

cp .env.example .env

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

Never commit or share .env; it is excluded by .gitignore.

Related MCP server: Codex Harness MCP

Run the MCP server

Start the MCP server in one terminal and leave it running:

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

The Streamable HTTP endpoint is now available at:

http://127.0.0.1:8000/mcp

Keep that terminal open. Press Ctrl+C when you want to stop the server.

Run the agent notebook

In a second terminal:

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

Select the .venv Python kernel if Jupyter asks, then run the cells from top to bottom. The notebook connects directly to http://127.0.0.1:8000/mcp; it never starts or imports app.py. The Groq API key is loaded from .env and is never stored in the notebook.

How the pieces connect

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

The server must be running before executing the MCP connection cells. If the notebook reports a connection error, first confirm that the server terminal says Uvicorn is running on http://127.0.0.1:8000.

The notebook also guards against stale certificate-file environment variables occasionally inherited from notebook launchers. It removes a certificate variable only when the referenced path does not exist; valid custom certificate settings are preserved.

MCP