# FastMCP + LangGraph — Webinar Demo

A live-coding demo for the **"AI Agents Are Only As Useful As the Tools They Can Reach"** webinar.  
Builds a real MCP server with six tools, connects it to a LangGraph ReAct agent, and lets you pick exactly which tool to call and what question to ask — all from the terminal.

---

## What's in this repo

| File | Purpose |
|---|---|
| `demo_mcp_server.py` | The MCP server — defines all six tools |
| `demo_agent.py` | The interactive demo runner |
| `requirements.txt` | Python dependencies |
| `.env.example` | Template for your API keys |

---

## Quick start

### 1. Clone / download the files

Make sure `demo_mcp_server.py` and `demo_agent.py` are in the **same folder**.

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

> **Python 3.10+** required.

### 3. Set up your API keys

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

Open `.env` and fill in your keys (see [API keys](#api-keys) below).

### 4. Run the demo

```bash
python demo_agent.py
```

No OpenAI key yet? Run in tools-only mode — you can still test all six tools manually:

```bash
python demo_agent.py --tools-only
```

---

## API keys

### OpenAI (required for the agent — Section 3)

1. Go to [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
2. Click **Create new secret key**
3. Copy the key and paste it as `OPENAI_API_KEY` in your `.env`

The demo uses **gpt-4o-mini** by default — the cheapest model that handles tool-calling well.  
Change it by setting `OPENAI_MODEL=gpt-4o` in `.env` if you want the more powerful version.

> **Cost note:** A full run-through of the demo costs roughly $0.01–0.05 with gpt-4o-mini.

---

### Tavily (required for web_search tool)

1. Go to [https://app.tavily.com](https://app.tavily.com) and sign up (free)
2. Copy your API key from the dashboard
3. Paste it as `TAVILY_API_KEY` in your `.env`

**Free tier:** 1,000 searches/month — more than enough for demos.

> Without this key the `web_search` tool returns an error message, but all other tools work fine.

---

## Demo walkthrough

### Section 1 — Tool Discovery
Automatically connects to the MCP server and lists all available tools with their descriptions.

### Section 2 — Interactive Tool Testing
You choose which tool to call and supply its arguments yourself. No LLM involved — raw tool input/output.

```
Available tools:
  1. web_search
  2. fetch_url
  3. save_note
  4. read_note
  5. list_notes
  6. calculate

Enter tool name or number (or 'done'): 6
  Tool : calculate
  Args : ['expression']
    expression (string): sqrt(144) + pi
```

Type `done` when you're ready to move on.

### Section 3 — LangGraph Agent Demo
The agent picks its own tools based on your question. You can choose from preset questions or type your own.

```
Preset questions:
  1. Single tool — calculator
  2. Multi-tool — search then save
  3. Full workflow — search, fetch, calculate, save
  4. Read back a saved file
  5. Custom question

> 5
   Type your question: What is 2 to the power of 32?
```

- Type `quiet` to toggle the verbose tool-call trace on/off
- Type `done` to end this section

---

## The six tools

| Tool | Description | Requires |
|---|---|---|
| `web_search` | Real web search via Tavily | `TAVILY_API_KEY` |
| `fetch_url` | Fetches and strips HTML from any URL | — |
| `calculate` | Evaluates math expressions safely (`sqrt`, `pi`, `log`, etc.) | — |
| `save_note` | Writes text to `/tmp/mcp_notes/<filename>` | — |
| `read_note` | Reads a previously saved note | — |
| `list_notes` | Lists all saved notes with sizes | — |

---

## Troubleshooting

**`ModuleNotFoundError`**  
Run `pip install -r requirements.txt` again. If you're in a virtual environment, make sure it's activated.

**`OPENAI_API_KEY not set`**  
Make sure you copied `.env.example` to `.env` (not `.env.example`) and filled in the key.

**`Server file not found`**  
`demo_agent.py` and `demo_mcp_server.py` must be in the same directory.

**`web_search` returns an error**  
Add your `TAVILY_API_KEY` to `.env`. All other tools still work without it.

**Agent gives a wrong answer / tool call fails**  
Try adding more detail to your question. The agent uses tool descriptions to decide what to call — more specific questions get better results.

---

## Resources

- [FastMCP docs](https://gofastmcp.com)
- [LangGraph docs](https://langchain-ai.github.io/langgraph/)
- [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters)
- [Model Context Protocol spec](https://modelcontextprotocol.io)
- [Tavily API](https://app.tavily.com)
- [OpenAI API keys](https://platform.openai.com/api-keys)