# Building Multi-Transport MCP Servers

**Author:** Rajkumar Rajagobalan

A runnable Python training project that demonstrates how a LangChain MCP client connects to two `FastMCP` servers through different transports: **stdio** for a local math service and **Streamable HTTP** for a network-style weather service.

The repository is a corrected, documented rewrite of the demonstration scenario in the supplied source repository. It retains the instructional architecture while resolving the reproducibility issues that prevented the original demo from running consistently.

## What you will build

```text
LangChain application / optional LangGraph agent
└── MultiServerMCPClient
    ├── math server: stdio transport
    │   ├── add(a, b)
    │   └── multiply(a, b)
    └── weather server: Streamable HTTP at /mcp
        └── get_weather(location)
```

## What was corrected

| Issue in the original demo | Correction in this repository |
| --- | --- |
| `pyproject.toml` required Python `>=3.13` | Supports Python `>=3.11`, matching current Python 3.12 environments. |
| Relative `mathserver.py` argument depended on the caller’s working directory | Uses the current Python interpreter and an absolute module path. |
| The client had no deterministic fallback when `GROQ_API_KEY` was absent | Adds direct MCP integration mode and keeps the LangGraph agent as an optional layer. |
| Hard-coded server URL and port | Supports an explicit `--weather-url` argument and `MCP_WEATHER_URL` environment variable. |
| No automated validation | Adds unit tests, an end-to-end integration test, and a reproducible launcher. |
| Empty README | Documents architecture, setup, execution, troubleshooting, and security constraints. |
| Spelling and naming drift in the original tool | Uses `multiply`, documents the name change, and provides clear tool descriptions. |
| GPL-3.0 origin was not carried forward in a derived repository | Retains GPL-3.0-only and documents provenance in `NOTICE.md`. |

## Prerequisites

- Python **3.11 or newer**
- [uv](https://docs.astral.sh/uv/) installed
- A Groq API key only if you want to run the optional `--mode agent` example

## Quick start

```bash
git clone https://github.com/nuvear/Build_MCP_Server.git
cd Build_MCP_Server
uv sync --extra dev
```

### Run the complete integration in one command

```bash
./scripts/run_demo.sh
```

Expected result:

```text
MCP direct integration passed
Discovered tools: add, get_weather, multiply
Math: (3 + 5) × 12 = 96
Weather: Training forecast for California: mild, clear, and 22°C.
```

### Run the two terminals manually

Terminal 1 — start the Streamable HTTP server:

```bash
uv run mcp-weather-server --host 127.0.0.1 --port 8000
```

Terminal 2 — run the client:

```bash
uv run mcp-training --mode direct --weather-url http://127.0.0.1:8000/mcp
```

The direct mode invokes the real MCP tools without requiring an LLM provider key. It is the primary reproducibility check for this training project.

### Optional LangGraph agent mode

1. Copy the environment template:

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

2. Add a valid `GROQ_API_KEY`, and set `GROQ_MODEL` if your account uses a different available model.

3. Start the weather server, then run:

   ```bash
   uv run mcp-training --mode agent --weather-url http://127.0.0.1:8000/mcp
   ```

## Validation

```bash
uv run pytest -q
```

The suite covers tool behavior, portable client configuration, and a full end-to-end integration across both stdio and Streamable HTTP transports.

## Project layout

```text
├── src/mcp_training/
│   ├── client.py           # Direct and optional agent clients
│   ├── config.py           # Portable multi-server configuration
│   ├── math_server.py      # FastMCP server over stdio
│   └── weather_server.py   # FastMCP server over Streamable HTTP
├── tests/                  # Unit and end-to-end tests
├── scripts/run_demo.sh     # One-command full integration run
├── docs/illustrations/     # Custom draft illustrations used in the deck
├── research/               # Video outline and use-case source notes
├── NOTICE.md               # Source and license provenance
└── README.md
```

## Troubleshooting

- **HTTP connection refused:** Start `mcp-weather-server` before running the client.
- **Wrong port or URL:** Pass the actual endpoint with `--weather-url` or set `MCP_WEATHER_URL`.
- **Agent mode fails on missing key:** Set `GROQ_API_KEY`, or use `--mode direct` for the key-free integration path.
- **Tool not discovered:** Check the server process log and verify that the client prints the discovered tool names.
- **Port already in use:** Start the server on another port, for example `uv run mcp-weather-server --port 8001`, and update the client URL.

## Security and training constraints

- The weather tool is a deterministic mock and must not be represented as live weather data.
- Run the HTTP demo on `127.0.0.1`; bind to another interface only after adding authentication and network controls.
- Treat MCP tool descriptions as part of the agent-facing instruction surface. Keep them precise, avoid sensitive data, and expose only the minimum required tools.
- Review upstream MCP security guidance before adapting the pattern for production.

## Educational deliverables

- [`docs/training-manual/Multi-Transport_MCP_Training_Manual.pptx`](docs/training-manual/Multi-Transport_MCP_Training_Manual.pptx) — illustrated PowerPoint training manual.
- [`docs/step-by-step-guide.md`](docs/step-by-step-guide.md) — step-by-step guide with programmer and vibe-coding learning tracks.
- [`docs/step-by-step-guide.html`](docs/step-by-step-guide.html) — browser-ready version of the step-by-step guide.
- [`docs/illustrations/`](docs/illustrations/) — original draft illustrations embedded in the manual.
- [`research/video-outline.md`](research/video-outline.md) — structured outline derived from the supplied video.
- [`research/use-case-examples.md`](research/use-case-examples.md) — recent official implementation examples used in the deck.

## License

This project is distributed under [GPL-3.0-only](LICENSE). See [`NOTICE.md`](NOTICE.md) for source provenance.