MCP Masterclass - Complete Guide For Beginners

A comprehensive, hands-on course that teaches you everything about Model Context Protocol (MCP) - from creating your first MCP server to deploying production-ready applications using Docker and cloud-native architectures.

📚 Table of Contents

• What is MCP?

• Course Overview

• Prerequisites

• Getting Started

• Course Structure

• Project Architecture

• Key Features

• Technologies

• Quick Start Guide

• Running Examples

• FAQ

• Resources

Related MCP server: MCP Terminal Server

🤖 What is MCP?

Model Context Protocol (MCP) is a standardized protocol that enables seamless communication between AI models and external tools/systems. It allows:

• 🔌 Tool Integration: Connect AI models to custom tools and services

• 🌐 Universal Communication: Standardized way for LLMs to interact with resources

• 🔄 Multi-Transport Support: Use stdio, HTTP, or custom transports

• 🛡️ Type-Safe: Full type support and validation

• 📡 Remote Execution: Execute tools on remote servers

📖 Course Overview

This masterclass takes you on a complete journey through MCP development:

Beginner  ─→  Intermediate  ─→  Advanced  ─→  Production
   ↓              ↓                 ↓             ↓
 CH-1          CH-2,3             CH-4,5        CH-6

Whether you're an AI enthusiast, developer, or DevOps engineer, this course has something for you!

✅ Prerequisites

• Python 3.12+ (MCP requires modern Python)

• Git for version control

• Docker (for Chapter 6)

• Basic Python knowledge (async/await, decorators)

• API familiarity (helpful for understanding HTTP transport)

• Terminal/Command Line comfort

🎯 Getting Started

1. Clone the Repository

git clone https://github.com/yourusername/MCP_Masterclass.git
cd MCP_Masterclass

2. Set Up Python Environment

Using uv (recommended - faster than pip):

uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Or using traditional venv:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

uv pip install -r pyproject.toml
# or
pip install -e .

The project includes:

• fastmcp - FastMCP framework for building MCP servers

• langchain - For integration with language models

• langchain-mcp-adapters - Bridge between LangChain and MCP

• mcp - Official MCP specification implementation

• agentic-terminal - Terminal-based MCP tools

4. Verify Installation

python main.py
# Expected output: "Hello from mcp-masterclass!"

📚 Course Structure

Chapter 1: Creating Your First MCP Server 🌱

File: CH-1_CreateMCP/

Learn the fundamentals of MCP by building a basic server:

• 1_first_mcpserver_stdio.py: Build a simple MCP server using stdio transport

  • Basic tool definition with @mcp.tool() decorator

  • Fetch and process data patterns

  • Running server locally

• 2_python_client.py: Create a Python client to connect to the MCP server

  • Understand client-server communication

  • Making tool calls programmatically

• 3_langchain_client.py: Integrate MCP with LangChain

  • Use MCP tools with language models

  • Automatic tool discovery and binding

Key Learnings:

• FastMCP framework basics

• Stdio transport protocol

• Async function handling

• Tool documentation with docstrings

Chapter 2: HTTP Transport & Scalability 🌐

File: CH-2_HTTP_MCP/

Scale your MCP servers for real-world applications:

• 1_http_mcp.py: Build an HTTP-based MCP server

  • Streamable HTTP transport

  • Network accessibility

  • Multi-client support

  • Running on port 8050

• 2_langchain_client.py: Connect LangChain to HTTP MCP server

  • Remote server communication

  • HTTP client setup

  • Tool availability over network

Key Learnings:

• HTTP transport vs Stdio

• Scalability considerations

• Network security basics

• Multi-client architectures

Chapter 3: Integrating 3rd Party MCPs 🔗

File: CH-3_3rdParty_MCPs/

Leverage community MCP servers in your applications:

• community_mcp.py: Use open-source community MCP servers

  • Discovering available MCPs

  • Integration patterns

  • Popular community tools

• tavily_mcp.py: Integrate Tavily search MCP

  • Real-world API integration

  • Web search capabilities

  • Data enrichment workflows

Key Learnings:

• MCP ecosystem exploration

• Third-party tool integration

• Composition and orchestration

• API key management

Chapter 4: Publishing to PyPI 📦

File: CH-4_PyPI_MCP/ & MCP_PYPI/

Package and distribute your MCP as a Python package:

• 1_test_package.py: Test your packaged MCP

• 2_client.py: Use the published package as a client

• MCP_PYPI/: Complete package structure

  • pyproject.toml: Package configuration

  • src/agentic_terminal/: Agentic terminal implementation

    • tools.py: Custom tool definitions

    • main.py: Entry point

Key Learnings:

• Python package structure

• PyPI publishing workflow

• Package versioning and dependency management

• Entry points and CLI tools

Chapter 5: MCP Gateway & Orchestration 🎯

File: CH-5_MCP_Gateway/

Build a unified gateway to manage multiple MCP servers:

• gateway.py: Central gateway for orchestrating multiple MCPs

  • Mounting multiple MCP servers

  • Request routing

  • Tool discovery and aggregation

  • Unified interface to many tools

  • Example: integrating duckduckgo-mcp-server

Key Learnings:

• Gateway pattern architecture

• MCP composition and mounting

• Load balancing concepts

• Tool proxy implementations

Chapter 6: Containerization & Docker 🐳

File: CH-6_MCP_Docker/

Deploy MCP servers in production using Docker:

• Dockerfile: Multi-stage Docker configuration

  • Base image: Python 3.11-slim

  • Pre-installed tools (duckduckgo-mcp-server, agentic_terminal)

  • FastMCP runtime

• requirements.txt: Python dependencies for container

• app/gateway.py: Gateway application for containerized deployment

Key Learnings:

• Dockerfile best practices

• Multi-stage builds

• Container environment setup

• Production deployment patterns

• Tool availability in containers

🏗️ Project Architecture

MCP_Masterclass/
│
├── CH-1_CreateMCP/           # Basics: Stdio-based MCP
│   ├── 1_first_mcpserver_stdio.py
│   ├── 2_python_client.py
│   └── 3_langchain_client.py
│
├── CH-2_HTTP_MCP/            # HTTP Transport & Scalability
│   ├── 1_http_mcp.py
│   └── 2_langchain_client.py
│
├── CH-3_3rdParty_MCPs/       # Integration Patterns
│   ├── community_mcp.py
│   └── tavily_mcp.py
│
├── CH-4_PyPI_MCP/            # Packaging
│   ├── 1_test_package.py
│   └── 2_client.py
│
├── CH-5_MCP_Gateway/         # Orchestration
│   └── gateway.py
│
├── CH-6_MCP_Docker/          # Production Deployment
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       └── gateway.py
│
├── MCP_PYPI/                 # PyPI Package Structure
│   ├── pyproject.toml
│   ├── README.md
│   └── src/
│       └── agentic_terminal/
│           ├── __init__.py
│           ├── main.py
│           └── tools.py
│
├── Notes/                    # Course Notes
│   └── MCP-Masterclass.png
│
├── pyproject.toml            # Main project config
├── package.json              # NPM metadata
├── main.py                   # Entry point
└── README.md                 # This file

💡 Key Features

Progressive Learning Path

• Start with basics (stdio servers)

• Progress to HTTP scalability

• Learn composition and orchestration

• Deploy with Docker

Hands-On Examples

• Every concept includes working code

• Multiple integration patterns

• Real-world scenarios (search, processing)

Production-Ready

• Docker containerization

• Gateway architecture

• Multi-server orchestration

• PyPI packaging

Community Integration

• Third-party MCP servers

• Popular tools (Tavily, DuckDuckGo)

• Integration patterns

• Extensibility examples

🛠️ Technologies

🚀 Quick Start Guide

Example 1: Run the First MCP Server

# Navigate to Chapter 1
cd CH-1_CreateMCP

# Activate your virtual environment
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Run the MCP server
python 1_first_mcpserver_stdio.py

Example 2: Connect a Python Client

# In another terminal, with venv activated
cd CH-1_CreateMCP
python 2_python_client.py

Example 3: Use with LangChain

cd CH-1_CreateMCP
python 3_langchain_client.py

Example 4: HTTP Server

cd CH-2_HTTP_MCP
python 1_http_mcp.py
# Server runs on http://localhost:8050

Example 5: Gateway Architecture

cd CH-5_MCP_Gateway
python gateway.py

Example 6: Docker Deployment

cd CH-6_MCP_Docker
docker build -t mcp-masterclass .
docker run -p 8050:8050 mcp-masterclass

🏃 Running Examples

Setup for Examples

1. Install all dependencies: uv pip install -r pyproject.toml

2. Ensure Python 3.12+ is active: python --version

3. Set any required API keys in environment variables

Running Individual Examples

Each chapter can be run independently:

# Chapter 1 - Basic Server
cd CH-1_CreateMCP && python 1_first_mcpserver_stdio.py

# Chapter 2 - HTTP Server  
cd CH-2_HTTP_MCP && python 1_http_mcp.py

# Chapter 5 - Gateway
cd CH-5_MCP_Gateway && python gateway.py

# Chapter 6 - Docker
cd CH-6_MCP_Docker && docker build -t mcp . && docker run mcp

Debugging

Enable verbose output for MCP debugging:

# Set debug environment variable
export MCP_DEBUG=1
python your_mcp_file.py

❓ FAQ

Q: Do I need GPU support?

A: No, MCP servers run on CPU. GPU is only needed if running large language models locally.

Q: Can I use MCP with other frameworks besides LangChain?

A: Yes! MCP is framework-agnostic. It works with any LLM framework that supports the MCP protocol.

Q: What's the difference between Stdio and HTTP transport?

A:

• Stdio: Local communication, lower latency, single machine

• HTTP: Network communication, scalable, accessible remotely

Q: How do I add my own tools to an MCP server?

A: Use the @mcp.tool() decorator:

@mcp.tool()
async def my_tool(param: str):
    """Tool description."""
    return {"result": "your result"}

Q: Is MCP production-ready?

A: Yes! The project includes Docker containerization and gateway patterns for production deployment.

Q: How do I integrate external APIs?

A: Tools can make HTTP calls internally. See Chapter 3 for Tavily integration example.

Q: Can I run multiple MCP servers together?

A: Yes! Use the gateway pattern (Chapter 5) to orchestrate multiple servers.

Q: What's the purpose of PyPI publishing?

A: It allows others to install and use your MCP server as a package: pip install your-mcp-server

📚 Resources

Official Documentation

• MCP Specification

• FastMCP Documentation

• LangChain Integration

Community

• MCP GitHub Repository

• FastMCP GitHub Issues

• LangChain Discord Community

Related Tutorials

• MCP Tool Creation Best Practices

• LLM Integration Patterns

• Docker & Kubernetes for AI

Learning Path

1. Beginner: Read Chapter 1-2 documentation

2. Intermediate: Work through Chapter 3-4 examples

3. Advanced: Study Chapter 5-6 architecture

4. Expert: Extend with your own MCPs

🔧 Troubleshooting

Issue: Python version not compatible

Solution: Ensure Python 3.12+ is installed

python --version  # Should show 3.12.x or higher

Issue: FastMCP import error

Solution: Reinstall dependencies

uv pip install --force-reinstall fastmcp

Issue: Port already in use

Solution: Use a different port or kill the process

# On Windows
netstat -ano | findstr :8050
# On Linux/Mac
lsof -i :8050

Issue: Docker build fails

Solution: Clear Docker cache and rebuild

docker system prune -a
docker build --no-cache -t mcp-masterclass .

💬 Contributing

We welcome contributions! Areas for enhancement:

• Additional example MCPs

• Documentation improvements

• Additional transport protocols

• Testing suite expansion

• Deployment examples (Kubernetes, Cloud Run, etc.)

🎓 Learning Outcomes

After completing this masterclass, you will be able to:

✅ Create and deploy MCP servers using FastMCP ✅ Understand and implement different transport protocols ✅ Integrate with LangChain and other frameworks ✅ Compose multiple MCPs into orchestrated systems ✅ Package and publish MCP tools to PyPI ✅ Deploy MCPs using Docker and containerization ✅ Design scalable, production-ready MCP architectures ✅ Troubleshoot and debug MCP applications