MCP + LangChain Demo

A beginner-friendly project that demonstrates how to build MCP (Model Context Protocol) servers and connect them to an LLM agent using LangChain and LangGraph.

---

What is MCP?

MCP (Model Context Protocol) is an open protocol that lets you expose custom tools (functions) to LLMs in a standardized way. Think of it as a universal plugin system for AI models.

Key concepts:

Term	Definition
MCP Server	A process that exposes tools (functions) over a transport (stdio or HTTP). The LLM can call these tools.
MCP Client	A process that connects to one or more MCP servers, discovers their tools, and forwards them to an LLM.
Tool	A Python function decorated with @mcp.tool() that the LLM can invoke.
Transport	The communication method between client and server. stdio = same machine via stdin/stdout. streamable-http = over HTTP.
FastMCP	A high-level Python class from the mcp library that makes it easy to create MCP servers.

---

Project Structure

MCPLEARNING/
├── mathserver.py      # MCP Server 1 - Math tools (stdio transport)
├── weather.py         # MCP Server 2 - Weather tool (HTTP transport)
├── client.py          # LangChain agent that connects to both servers
├── .env               # API keys (NOT pushed to GitHub)
├── .gitignore
├── requirements.txt
└── pyproject.toml

---

How It Works (Step by Step)

Step 1: MCP Server — mathserver.py

This file creates an MCP server named "Math" that exposes two tools:

• add(a, b) — Returns the sum of two integers.
• multiply(a, b) — Returns the product of two integers.

It runs on stdio transport, meaning the client spawns it as a subprocess and communicates through stdin/stdout. No port needed.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Addition of two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiplication of two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

Step 2: MCP Server — weather.py

This file creates an MCP server named "Weather" that exposes one tool:

• get_weather(location) — Returns weather info for a given location.

It runs on streamable-http transport, meaning it starts a web server on http://127.0.0.1:8000/mcp. The client connects to it over HTTP.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> str:
    """Get the weather"""
    return "It's always raining in California"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Step 3: Client Agent — client.py

This is the brain of the project. It:

1. Connects to both MCP servers using MultiServerMCPClient.
2. Discovers all tools from both servers (add, multiply, get_weather).
3. Creates a Groq LLM (hosted open-source model) and binds the tools to it.
4. Builds a LangGraph agent — a state machine where:
   • The LLM decides whether to call a tool or respond directly.
   • If a tool is called, the result is fed back to the LLM for a final answer.
5. Tests two queries:
   • "What is 3 + 5?" → Uses the add tool.
   • "What is the weather in California?" → Uses the get_weather tool.

---

Prerequisites

• Python 3.13+
• uv package manager (recommended) or pip
• A Groq API key — Get one free at console.groq.com

---

Setup

1. Clone the repository

git clone https://github.com/<YOUR_USERNAME>/MCPLEARNING.git
cd MCPLEARNING

2. Create and activate virtual environment

# Using uv (recommended)
uv venv
uv pip install -r requirements.txt

# Or using pip
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Mac/Linux
pip install -r requirements.txt

3. Set up your API key

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key_here

IMPORTANT: Never commit your .env file. It is excluded via .gitignore.

---

Running the Project

You need two terminals open:

Terminal 1 — Start the Weather MCP Server

python weather.py

You should see:

INFO: Uvicorn running on http://127.0.0.1:8000

Note: Only weather.py needs to be started manually. The mathserver.py is spawned automatically by the client (stdio transport).

Terminal 2 — Run the Client

python client.py

Expected Output

Available MCP tools:
- add
- multiply
- get_weather

==============================
Testing Math MCP
==============================

Math Response: 3 + 5 = 8.

==============================
Testing Weather MCP
==============================

Weather Response: It's always raining in California.

---

How to Create Your Own MCP Server

1. Install the MCP library:

pip install mcp

2. Create a new Python file (e.g., myserver.py):

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool()
def my_tool(param: str) -> str:
    """Description of what this tool does."""
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run(transport="stdio")        # For stdio transport
    # mcp.run(transport="streamable-http")  # For HTTP transport

3. Connect it in your client by adding it to the MultiServerMCPClient config:

client = MultiServerMCPClient({
    "myserver": {
        "command": "python",
        "args": ["myserver.py"],
        "transport": "stdio",
    },
})

---

Transport Comparison

Transport	How it Works	When to Use
stdio	Client spawns the server as a subprocess. Communicates via stdin/stdout.	Local tools, simple setup, no network needed.
streamable-http	Server runs as a web server. Client connects via HTTP.	Remote tools, multiple clients, cross-machine access.

---

Key Libraries Used

Library	Purpose
mcp	Build MCP servers with FastMCP.
langchain-mcp-adapters	Bridge between MCP servers and LangChain tools.
langchain-groq	LangChain integration for Groq-hosted LLMs.
langgraph	Build agent workflows as a graph (agent ↔ tools loop).
python-dotenv	Load API keys from .env file.

---

Important Things to Take Care Of

1. Weather server must be running before the client — Since it uses HTTP transport, the server process must be started first. The math server (stdio) is auto-spawned by the client.

2. Groq API key is required — Without it, the LLM calls will fail. Get a free key at console.groq.com.

3. Never commit .env — Always add .env to .gitignore before pushing code.

4. Port conflicts — The weather server runs on port 8000 by default. If another process uses that port, the server will fail to start.

5. Windows encoding issue — On Windows, the console may not support UTF-8 characters returned by the LLM. The client.py handles this with sys.stdout.reconfigure(encoding="utf-8").

6. Model availability — The Groq model name (openai/gpt-oss-120b) must be valid and available on the Groq platform. Check Groq's model list for current options.