# Section 03 - Model Context Protocol (MCP) Integration

## Introduction to MCP (Model Context Protocol)

The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. Using MCP, AI applications like Claude or ChatGPT can connect to data sources (e.g., local files, databases), tools (e.g., search engines, calculators), and workflows (e.g., specialized prompts)—enabling them to access key information and perform tasks.

Think of MCP like a **USB-C port for AI applications**. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.

### What Can MCP Enable?

MCP unlocks powerful capabilities for AI applications:

- **Personalized AI Assistants**: Agents can access your Google Calendar and Notion, acting as a more personalized AI assistant
- **Advanced Code Generation**: Claude Code can generate an entire web app using a Figma design
- **Enterprise Data Integration**: Enterprise chatbots can connect to multiple databases across an organization, empowering users to analyze data using chat
- **Creative Workflows**: AI models can create 3D designs on Blender and print them out using a 3D printer
- **Real-time Information Access**: Connect to external data sources for up-to-date information
- **Complex Multi-step Operations**: Perform sophisticated workflows combining multiple tools and systems

### Why Does MCP Matter?

MCP provides benefits across the ecosystem:

**For Developers**: MCP reduces development time and complexity when building, or integrating with, an AI application or agent.

**For AI Applications**: MCP provides access to an ecosystem of data sources, tools and apps which enhance capabilities and improve the end-user experience.

**For End-users**: MCP results in more capable AI applications or agents which can access your data and take actions on your behalf when necessary.

## Small Language Models (SLMs) in MCP

Small Language Models represent an efficient approach to AI deployment, offering several advantages:

### Benefits of SLMs
- **Resource Efficiency**: Lower computational requirements
- **Faster Response Times**: Reduced latency for real-time applications  
- **Cost Effectiveness**: Minimal infrastructure needs
- **Privacy**: Can run locally without data transmission
- **Customization**: Easier to fine-tune for specific domains

### Why SLMs Work Well with MCP

SLMs paired with MCP create a powerful combination where the model's reasoning capabilities are augmented by external tools, compensating for their smaller parameter count through enhanced functionality.

## Python MCP SDK Overview

The Python MCP SDK provides the foundation for building MCP-enabled applications. The SDK includes:

- **Client Libraries**: For connecting to MCP servers
- **Server Framework**: For creating custom MCP servers
- **Protocol Handlers**: For managing communication
- **Tool Integration**: For executing external functions

## Practical Implementation: Phi-4 MCP Client

Let's explore a real-world implementation using Microsoft's Phi-4 mini model integrated with MCP capabilities.

### MCP Architecture Overview

MCP follows a **client-server architecture** where an MCP host (an AI application like Claude Code or Claude Desktop) establishes connections to one or more MCP servers. The MCP host accomplishes this by creating one MCP client for each MCP server.

#### Key Participants

- **MCP Host**: The AI application that coordinates and manages one or multiple MCP clients
- **MCP Client**: A component that maintains a connection to an MCP server and obtains context from an MCP server for the MCP host to use
- **MCP Server**: A program that provides context to MCP clients

#### Two-Layer Architecture

MCP consists of two distinct layers:

**Data Layer**: Defines the JSON-RPC based protocol for client-server communication, including:
- Lifecycle management (connection initialization, capability negotiation)
- Core primitives (tools, resources, prompts)
- Client features (sampling, elicitation, logging)
- Utility features (notifications, progress tracking)

**Transport Layer**: Defines the communication mechanisms and channels:
- **STDIO Transport**: Uses standard input/output streams for local processes (optimal performance, no network overhead)
- **Streamable HTTP Transport**: Uses HTTP POST with optional Server-Sent Events for remote servers (supports standard HTTP authentication)

```
┌─────────────────────────────────────┐
│           MCP Host                  │
│     (AI Application)                │
└─────────────────┬───────────────────┘
                  │
┌─────────────────┴───────────────────┐
│         MCP Client 1                │
│  ┌─────────────────────────────────┐ │
│  │        Data Layer               │ │
│  │  ├── Lifecycle Management       │ │
│  │  ├── Primitives (Tools/Resources)│ │
│  │  └── Notifications              │ │
│  └─────────────────────────────────┘ │
│  ┌─────────────────────────────────┐ │
│  │      Transport Layer           │ │
│  │  ├── STDIO Transport           │ │
│  │  └── HTTP Transport            │ │
│  └─────────────────────────────────┘ │
└─────────────────┬───────────────────┘
                  │
┌─────────────────┴───────────────────┐
│         MCP Server 1                │
│    (Local/Remote Context Provider)  │
└─────────────────────────────────────┘
```

### MCP Core Primitives

MCP defines primitives that specify the types of contextual information that can be shared with AI applications and the range of actions that can be performed.

#### Server Primitives

MCP defines three core primitives that servers can expose:

**Tools**: Executable functions that AI applications can invoke to perform actions
- Examples: file operations, API calls, database queries
- Methods: `tools/list`, `tools/call`
- Support dynamic discovery and execution

**Resources**: Data sources that provide contextual information to AI applications
- Examples: file contents, database records, API responses
- Methods: `resources/list`, `resources/read`
- Enable access to structured data

**Prompts**: Reusable templates that help structure interactions with language models
- Examples: system prompts, few-shot examples
- Methods: `prompts/list`, `prompts/get`
- Standardize AI interaction patterns

#### Client Primitives

MCP also defines primitives that clients can expose to enable richer interactions:

**Sampling**: Allows servers to request language model completions from the client's AI application
- Method: `sampling/complete`
- Enables model-independent server development
- Provides access to the host's language model

**Elicitation**: Allows servers to request additional information from users
- Method: `elicitation/request`
- Enables user interaction and confirmation
- Supports dynamic information gathering

**Logging**: Enables servers to send log messages to clients
- Used for debugging and monitoring purposes
- Provides visibility into server operations

### MCP Protocol Lifecycle

#### Initialization and Capability Negotiation

MCP is a stateful protocol that requires lifecycle management. The initialization process serves several critical purposes:

1. **Protocol Version Negotiation**: Ensures both client and server use compatible protocol versions (e.g., "2025-06-18")
2. **Capability Discovery**: Each party declares supported features and primitives
3. **Identity Exchange**: Provides identification and versioning information

```python
# Example initialization request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "elicitation": {},  # Client supports user interaction
      "sampling": {}      # Client can provide LLM completions
    },
    "clientInfo": {
      "name": "edge-ai-client",
      "version": "1.0.0"
    }
  }
}
```

#### Tool Discovery and Execution

After initialization, clients can discover and execute tools:

```python
# Discover available tools
tools_response = await session.list_tools()

# Execute a tool
result = await session.call_tool(
    "weather_current",
    {
        "location": "San Francisco",
        "units": "imperial"
    }
)
```

#### Real-time Notifications

MCP supports real-time notifications for dynamic updates:

```python
# Server sends notification when tools change
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

# Client responds by refreshing tool list
await session.list_tools()  # Get updated tools
```

## Getting Started: Step-by-Step Guide

### Step 1: Environment Setup

Install required dependencies:
```bash
pip install fastmcp mcp-python-client openai requests pyautogui Pillow
```

### Step 2: Basic Configuration

Set up your environment variables:
```python
# System Configuration
SYSTEM_PROMPT = "You are an AI assistant with some tools."

# Ollama Configuration (Local)
OLLAMA_URL = "http://localhost:11434/api/chat"
OLLAMA_MODEL_ID = "phi4-mini:3.8b-fp16"

# vLLM Configuration (Server)
VLLM_URL = "http://localhost:8000/v1"
VLLM_MODEL_ID = "microsoft/Phi-4-mini-instruct"
```

### Step 3: Running Your First MCP Client

**Basic Ollama Setup:**
```bash
python ghmodel_mcp_demo.py
```

**Using vLLM Backend:**
```bash
python ghmodel_mcp_demo.py --env vllm
```

**Server-Sent Events Connection:**
```bash
python ghmodel_mcp_demo.py --run sse
```

**Custom MCP Server:**
```bash
python ghmodel_mcp_demo.py --server /path/to/server.py
```

### Step 4: Programmatic Usage

```python
import asyncio
from ghmodel_mcp_demo import OllamaClient, Phi4MiniMCPClient

async def automated_interaction():
    # Configure MCP server parameters
    server_params = StdioServerParameters(
        command="npx",
        args=["@playwright/mcp@latest"],
        env=None,
    )
    
    # Create MCP client and process tools
    async with Phi4MiniMCPClient(server_params) as mcp_client:
        tools = await process_mcp_tools(mcp_client)
        llm_client = OllamaClient()
        
        # Generate response with tool capabilities
        response, messages = await llm_client.generate_response(
            "Help me automate a web task",
            tools
        )
        return response

# Execute the automation
result = asyncio.run(automated_interaction())
print(result)
```

## Advanced Features

### Multi-Backend Support

The implementation supports both Ollama and vLLM backends, allowing you to choose based on your requirements:

- **Ollama**: Better for local development and testing
- **vLLM**: Optimized for production and high-throughput scenarios

### Flexible Connection Protocols

Two connection modes are supported:

**STDIO Mode**: Direct process communication
- Lower latency
- Suitable for local tools
- Simple setup

**SSE Mode**: HTTP-based streaming
- Network-capable
- Better for distributed systems
- Real-time updates

### Tool Integration Capabilities

The system can integrate with various tools:
- Web automation (Playwright)
- File operations
- API interactions
- System commands
- Custom functions

## Error Handling and Best Practices

### Comprehensive Error Management

The implementation includes robust error handling for:

**Connection Errors:**
- MCP server failures
- Network timeouts
- Connectivity issues

**Tool Execution Errors:**
- Missing tools
- Parameter validation
- Execution failures

**Response Processing Errors:**
- JSON parsing issues
- Format inconsistencies
- LLM response anomalies

### Best Practices

1. **Resource Management**: Use async context managers
2. **Error Handling**: Implement comprehensive try-catch blocks
3. **Logging**: Enable appropriate logging levels
4. **Security**: Validate inputs and sanitize outputs
5. **Performance**: Use connection pooling and caching

## Real-World Applications

### Web Automation
```python
# Example: Automated web testing
async def web_automation_example():
    tools = await setup_playwright_tools()
    response = await llm_client.generate_response(
        "Navigate to example.com and take a screenshot",
        tools
    )
```

### Data Processing
```python
# Example: File analysis
async def data_processing_example():
    tools = await setup_file_tools()
    response = await llm_client.generate_response(
        "Analyze the CSV file and generate a summary report",
        tools
    )
```

### API Integration
```python
# Example: API interactions
async def api_integration_example():
    tools = await setup_api_tools()
    response = await llm_client.generate_response(
        "Fetch weather data and create a forecast summary",
        tools
    )
```

## Performance Optimization

### Memory Management
- Efficient message history handling
- Proper resource cleanup
- Connection pooling

### Network Optimization
- Async HTTP operations
- Configurable timeouts
- Graceful error recovery

### Concurrent Processing
- Non-blocking I/O
- Parallel tool execution
- Efficient async patterns

## Security Considerations

### Data Protection
- Secure API key management
- Input validation
- Output sanitization

### Network Security
- HTTPS support
- Local endpoint defaults
- Secure token handling

### Execution Safety
- Tool filtering
- Sandboxed environments
- Audit logging

## MCP Ecosystem and Development

### MCP Project Scope

The Model Context Protocol ecosystem includes several key components:

- **[MCP Specification](https://modelcontextprotocol.io/specification/latest)**: Official specification outlining implementation requirements for clients and servers
- **[MCP SDKs](https://modelcontextprotocol.io/docs/sdk)**: SDKs for different programming languages that implement MCP
- **MCP Development Tools**: Tools for developing MCP servers and clients, including the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
- **[MCP Reference Server Implementations](https://github.com/modelcontextprotocol/servers)**: Reference implementations of MCP servers

### Getting Started with MCP Development

To begin building with MCP:

**Build Servers**: [Create MCP servers](https://modelcontextprotocol.io/docs/develop/build-server) to expose your data and tools

**Build Clients**: [Develop applications](https://modelcontextprotocol.io/docs/develop/build-client) that connect to MCP servers

**Learn Concepts**: [Understand the core concepts](https://modelcontextprotocol.io/docs/learn/architecture) and architecture of MCP

## Conclusion

SLMs integrated with MCP represent a paradigm shift in AI application development. By combining the efficiency of small models with the power of external tools, developers can create intelligent systems that are both resource-efficient and highly capable.

The Model Context Protocol provides a standardized way to connect AI applications to external systems, much like USB-C provides a universal connection standard for electronic devices. This standardization enables:

- **Seamless Integration**: Connect AI models to diverse data sources and tools
- **Ecosystem Growth**: Build once, use across multiple AI applications
- **Enhanced Capabilities**: Augment SLMs with external functionality
- **Real-time Updates**: Support dynamic, responsive AI applications

Key takeaways:
- MCP is an open standard that bridges AI applications and external systems
- The protocol supports tools, resources, and prompts as core primitives
- Real-time notifications enable dynamic, responsive applications
- Proper lifecycle management and error handling are essential for production use
- The ecosystem provides comprehensive SDKs and development tools

## References and Further Reading

### Official MCP Documentation

- **[Model Context Protocol Official Site](https://modelcontextprotocol.io/)** - Complete documentation and specifications
- **[MCP Getting Started Guide](https://modelcontextprotocol.io/docs/getting-started/intro)** - Introduction and core concepts
- **[MCP Architecture Overview](https://modelcontextprotocol.io/docs/learn/architecture)** - Detailed technical architecture
- **[MCP Specification](https://modelcontextprotocol.io/specification/latest)** - Official protocol specification
- **[MCP SDKs Documentation](https://modelcontextprotocol.io/docs/sdk)** - Language-specific SDK guides

### Development Resources

- **[MCP for Beginners](https://aka.ms/mcp-for-beginners)** - Comprehensive beginner's guide to Model Context Protocol
- **[MCP GitHub Organization](https://github.com/modelcontextprotocol)** - Official repositories and examples
- **[MCP Server Repository](https://github.com/modelcontextprotocol/servers)** - Reference server implementations
- **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)** - Development and debugging tool
- **[Build MCP Servers Guide](https://modelcontextprotocol.io/docs/develop/build-server)** - Server development tutorial
- **[Build MCP Clients Guide](https://modelcontextprotocol.io/docs/develop/build-client)** - Client development tutorial

### Small Language Models and Edge AI

- **[Microsoft Phi Models](https://aka.ms/phicookbook)** - Phi model family 
- **[Foundry Local Documentation](https://github.com/microsoft/Foundry-Local)** - Microsoft's edge AI runtime
- **[Ollama Documentation](https://ollama.ai/docs)** - Local LLM deployment platform
- **[vLLM Documentation](https://docs.vllm.ai/)** - High-performance LLM serving

### Technical Standards and Protocols

- **[JSON-RPC 2.0 Specification](https://www.jsonrpc.org/)** - Underlying RPC protocol used by MCP
- **[JSON Schema](https://json-schema.org/)** - Schema definition standard for MCP tools
- **[OpenAPI Specification](https://swagger.io/specification/)** - API documentation standard
- **[Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)** - Web standard for real-time updates

### AI Agent Development

- **[Microsoft Agent Framework](https://github.com/microsoft/agent-framework)** - Production-ready agent development
- **[LangChain Documentation](https://docs.langchain.com/)** - Agent and tool integration framework
- **[Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/)** - Microsoft's AI orchestration SDK

### Industry Reports and Research

- **[Anthropic's Model Context Protocol Announcement](https://www.anthropic.com/news/model-context-protocol)** - Original MCP introduction
- **[Small Language Models Survey](https://arxiv.org/abs/2410.20011)** - Academic survey of SLM research
- **[Edge AI Market Analysis](https://www.marketsandmarkets.com/Market-Reports/edge-ai-software-market-74385617.html)** - Industry trends and forecasts
- **[AI Agent Development Best Practices](https://arxiv.org/abs/2309.02427)** - Research on agent architectures

This section provides the foundation for building your own SLM-powered MCP applications, opening up possibilities for automation, data processing, and intelligent system integration. 

## ➡️ What's next

- [Module 7. Edge AI samples](../Module07/README.md)