# 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):

```bash
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:

```bash
cp .env.example .env
```

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

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

## Run the MCP server

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

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

The Streamable HTTP endpoint is now available at:

```text
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:

```bash
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

```text
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.