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

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)

Related MCP server: SampleMCP

What was corrected

Prerequisites

• Python 3.11 or newer

• uv installed

• A Groq API key only if you want to run the optional --mode agent example

Quick start

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

./scripts/run_demo.sh

Expected result:

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:

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

Terminal 2 — run the client:

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:

   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:

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

Validation

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

├── 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 — illustrated PowerPoint training manual.

• docs/step-by-step-guide.md — step-by-step guide with programmer and vibe-coding learning tracks.

• docs/step-by-step-guide.html — browser-ready version of the step-by-step guide.

• docs/illustrations/ — original draft illustrations embedded in the manual.

• research/video-outline.md — structured outline derived from the supplied video.

• research/use-case-examples.md — recent official implementation examples used in the deck.

License

This project is distributed under GPL-3.0-only. See NOTICE.md for source provenance.