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

Ready to start your MCP journey?

📋 Setup Guide → 🎓 Tutorial → 🚀 Build Something Amazing

MCP-Transition

Links

README

Step by Step to MCP Glory

🌟 Overview

🎯 What You'll Learn

🗺️ The Journey

🚀 Quick Start

Prerequisites

1-Minute Setup

Environment Variables

📖 Detailed Documentation

📁 Repository Structure

🎯 Stage Overview

Stage 1: Naive Implementation

Stage 2: Improved Architecture

Stage 3: MCP Foundation

Stage 4: Official Library

Stage 5: Remote Services

Stage 6: Multi-Transport

Stage 7: Streamable HTTP Migration

🛠️ Available Tools by Stage

🤝 Contributing

Development Setup

📚 Additional Resources

MCP Ecosystem

Related Technologies

📜 License

🙏 Acknowledgments

Collected info