MCP Server Examples

A collection of Model Context Protocol (MCP) implementations ranging from a minimal hello-world introduction to a full autonomous AI agent that can build software on its own.

What is MCP? The Model Context Protocol is an open standard that lets LLMs call external tools — functions you define — in a structured, safe way. The model sees a schema; you control the implementation.

---

Repository Structure

mcp-server-example/
│
├── mcp_server.py              # Intro: minimal MCP server (2 tools)
├── mcp_client.py              # Intro: Ollama client that calls those tools
├── requirements.txt           # All Python dependencies
│
├── data_science_mcp/          # Advanced: data visualisation + stats + coding tools
│   ├── mcp_server.py          #   Full server (36 tools: plots, stats, system, web)
│   ├── mcp_client.py          #   Ollama multi-agent client (MAS with supervisor)
│   ├── mcp_client_gpustack.py #   GPUStack API client (OpenAI-compatible)
│   └── README.md
│
└── autonomous_agent/          # Expert: time-budgeted autonomous AI agent
    ├── mcp_server.py          #   Lean server (13 tools: system + web only)
    ├── mcp_client_autonomous.py #  Master planner + parallel workers
    └── README.md

---

1. Intro — Root Level

The simplest possible MCP setup. Two tools, one model, one conversation.

Tools exposed:

• get_current_time — returns the current timestamp
• calculate_sum — adds two numbers

Run it:

# Install dependencies
pip install -r requirements.txt

# Start a chat
python mcp_client.py

The root client uses Ollama with a local model. Change OLLAMA_MODEL at the top of mcp_client.py to switch models.

---

2. Data Science MCP — data_science_mcp/

A production-grade multi-agent system for data analysis and software development. See data_science_mcp/README.md for full details.

Highlights:

• 36 MCP tools: interactive Plotly charts, static Matplotlib plots, statistical tests, shell commands, file I/O, web search, and more
• Two clients: local Ollama (mcp_client.py) and GPUStack API (mcp_client_gpustack.py)
• Supervisor + specialist agent architecture (routing, delegation, parallel execution)

---

3. Autonomous Agent — autonomous_agent/

Give it a time budget and a goal (or no goal at all) and it works autonomously. See autonomous_agent/README.md for full details.

Highlights:

• Master planner dispatches subtasks to up to 3 parallel workers
• Focused on software engineering: shell, files, web search, HTTP testing
• Safety guard blocks destructive commands and restricts write paths
• Produces a full Markdown report at the end of every session

---

Installation

# Clone and enter the repo
git clone <repo-url>
cd mcp-server-example

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate   # Linux/macOS
# venv\Scripts\activate    # Windows

# Install all dependencies
pip install -r requirements.txt

# Add your API credentials once in the project root (used by all clients)
cp .env.example .env
# then edit .env with your api_key and api_base_url

# For Playwright screenshots (optional)
playwright install chromium
sudo venv/bin/playwright install-deps chromium

---

Learning Path

Step	What to read/run	Concept learned
1	Root mcp_server.py	Defining MCP tools with @mcp.tool()
2	Root mcp_client.py	Connecting a client, listing tools, calling them
3	data_science_mcp/mcp_server.py	Scaling to many tools, complex implementations
4	data_science_mcp/mcp_client.py	Multi-agent routing and delegation
5	autonomous_agent/mcp_client_autonomous.py	Planner + parallel workers + safety + reporting