Step by Step to MCP Glory

A Comprehensive Tutorial for Building Model Context Protocol (MCP) Enabled AI Agents

---

🌟 Overview

This repository provides a complete, hands-on journey from building a simple AI agent to creating sophisticated, distributed systems using the Model Context Protocol (MCP). Through 6 carefully crafted iterations, you'll master the fundamental concepts and advanced patterns of MCP architecture.

🎯 What You'll Learn

• Agent Architecture Evolution: From monolithic to modular, protocol-driven design
• MCP Protocol Mastery: stdio and SSE transports, tool discovery, session management
• Production Patterns: Error handling, structured data, multi-transport composition
• Real-world Integration: External APIs, remote services, distributed tool ecosystems

---

🗺️ The Journey

🏁	Stage 1	Naive Agent	Simple agent with hardcoded tools
🔧	Stage 2	Improved Agent	Async patterns and code cleanup
🔌	Stage 3	MCP Foundation	stdio server and custom MCP client
📚	Stage 4	Official Library	Using Anthropic's MCP Python SDK
🌐	Stage 5	Remote Services	SSE transport with ather API integration
🌍	Stage 6	Multi-Transport	Unified agent with local + remote tools
🔄	Stage 7	Streamable HTTP Migration	SSE to Streamable HTTP transport upgrade

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• API Keys: Tavily (web search), OpenWeatherMap (weather)
• OpenAI API access

1-Minute Setup

# Clone and setup
git clone <repository-url>
cd MCP-Transition
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Run any stage
python naive_agent.py           # Stage 1
python improved_agent.py        # Stage 2
python mcp_agent_sse.py         # Stage 5 (requires weather server)
python mcp_agent_streamable.py  # Stage 7 (requires streamable server)

Environment Variables

# .env file
OPENAI_API_KEY=your_openai_key_here
TAVILY_API_KEY=your_tavily_key_here
OPENWEATHERMAP_API_KEY=your_weather_key_here

---

📖 Detailed Documentation

Document	Purpose	Audience
📋 Setup Guide	Complete installation and configuration	All users
🎓 Step-by-Step Tutorial	Detailed code walkthrough with highlights	Developers

---

📁 Repository Structure

MCP-Transition/
├── README.md                              # This file
├── requirements.txt                       # Python dependencies
├── prompts.py                            # Shared prompt templates
│
├── 🏁 STAGE 1: Naive Implementation
│   └── naive_agent.py                    # Basic agent with hardcoded tools
│
├── 🔧 STAGE 2: Improved Architecture  
│   └── improved_agent.py                 # Async patterns and cleanup
│
├── 🔌 STAGE 3: MCP Foundation
│   ├── mcp_server_stdio.py              # Local MCP server (stdio transport)
│   └── mcp_client_stdio.py              # Custom MCP client implementation
│
├── 📚 STAGE 4: Official Library
│   └── mcp_agent_with_standard_client.py # Using official Anthropic MCP SDK
│
├── 🌐 STAGE 5: Remote Services
│   ├── mcp_server_sse.py                # Remote weather server (SSE transport)
│   └── mcp_agent_sse.py                 # SSE-based agent
│
├── 🌍 STAGE 6: Multi-Transport
│   └── mcp_agent_multi_transport.py     # Unified local + remote agent
│
├── 🔄 STAGE 7: Streamable HTTP Migration
│   ├── mcp_server_streamable.py         # Weather server (Streamable HTTP transport)
│   └── mcp_agent_streamable.py          # Streamable HTTP-based agent
│
└── docs/                                 # Detailed documentation
    ├── SETUP.md                         # Installation guide
    ├── TUTORIAL.md                      # Step-by-step code walkthrough
    ├── MCP_CONCEPTS.md                  # Protocol deep dive
    └── DEPLOYMENT.md                    # Production deployment

---

🎯 Stage Overview

Stage 1: Naive Implementation

File: naive_agent.py

• Basic PydanticAI agent with hardcoded tools
• Synchronous execution with async workarounds
• Direct API calls without abstraction

Why PydanticAI? I chose PydanticAI as the starting framework because it provides the cleanest, non-vendor-specific approach to building AI agents. Unlike framework-specific solutions, PydanticAI offers excellent separation between conversation management and tooling, making it ideal for demonstrating MCP integration patterns.

Alternative Frameworks: This is just one of many possible implementations! For the same agent implemented across 8 different frameworks (LangChain, LangGraph, CrewAI, Llama-Index, OpenAI Assistants, Anthropic, and Atomic Agents), check out my Agent Framework Comparison Repository. You can use any of these as your starting point for MCP integration.

Key Concepts: Basic agent architecture, tool registration, conversation flow

---

Stage 2: Improved Architecture

File: improved_agent.py

• Proper async/await patterns
• Better error handling and type hints
• Cleaner code structure and formatting

Key Concepts: Async programming, code quality, maintainable architecture

🎓 Tutorial Link

---

Stage 3: MCP Foundation

Files: mcp_server_stdio.py, mcp_client_stdio.py

• First MCP implementation using stdio transport
• Custom client with full protocol implementation
• Tool discovery and JSON-RPC 2.0 messaging

Key Concepts: MCP protocol, stdio transport, JSON-RPC, tool discovery

🎓 Tutorial Link

---

Stage 4: Official Library

File: mcp_agent_with_standard_client.py

• Replacement of custom client with official Anthropic MCP SDK
• Simplified codebase (~100 lines reduction)
• Production-ready protocol compliance

Key Concepts: Official libraries vs custom implementation, code simplification

🎓 Tutorial Link

---

Stage 5: Remote Services

Files: mcp_server_sse.py, mcp_agent_sse.py

• HTTP-based MCP server with Server-Sent Events
• Real-world API integration (OpenWeatherMap)
• Remote deployment capabilities

Key Concepts: SSE transport, remote services, external API integration

🎓 Tutorial Link

---

Stage 6: Multi-Transport

File: mcp_agent_multi_transport.py

• Simultaneous connection to multiple MCP servers
• Mixed local (stdio) and remote (SSE) tools
• Unified tool interface and session management

Key Concepts: Multi-transport architecture, tool composition, distributed systems

🎓 Tutorial Link

---

Stage 7: Streamable HTTP Migration

Files: mcp_server_streamable.py, mcp_agent_streamable.py

• Migration from SSE to Streamable HTTP transport
• Single endpoint design (/mcp vs /sse + /messages)
• Improved scalability and infrastructure compatibility
• Future-proof transport implementation

Key Concepts: Transport migration, protocol evolution, backward compatibility patterns

---

🛠️ Available Tools by Stage

Stage	Tools	Transport	Location
1-2	📅 Date, 🔍 Web Search	Direct calls	Local
3-4	📅 Date, 🔍 Web Search	stdio MCP	Local subprocess
5	🌤️ Current Weather, 📊 Forecast, 🗺️ Coordinates	SSE MCP	Remote HTTP server
6	📅 Date, 🔍 Web Search, 🌤️ Weather Tools	stdio + SSE MCP	Local + Remote
7	🌤️ Current Weather, 📊 Forecast, 🗺️ Coordinates	Streamable HTTP MCP	Remote HTTP server

---

🤝 Contributing

We welcome contributions! Here are some ways to help:

• 🐛 Bug Reports: Found an issue? Open an issue
• 💡 Feature Requests: Ideas for new stages or improvements
• 📖 Documentation: Help improve guides and examples
• 🔧 Code: Submit PRs for bug fixes or enhancements

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/MCP-Transition.git
cd MCP-Transition

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # If available

# Run tests
python -m pytest tests/  # If tests are available

---

📚 Additional Resources

MCP Ecosystem

• Official MCP Specification - Complete protocol documentation
• Anthropic MCP Repository - Official Python SDK
• MCP Community - Community MCP servers

Related Technologies

• Pydantic AI - AI agent framework used in examples
• OpenAI API - Language model integration
• Tavily API - Web search capabilities

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Anthropic for creating the Model Context Protocol and providing excellent documentation
• Pydantic AI team for the elegant agent framework
• Community contributors who helped improve this tutorial

---