Transition
Showing how to transition from a naive agent to an MCP agent in 3 steps
Ask AI about Transition
Powered by Claude Β· Grounded in docs
I know everything about Transition. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
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
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
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
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
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
