Credit - Huggingface Agents Course

Model Context Protocol (MCP) – A Comprehensive Guide

Table of Contents

1. Why MCP Matters
2. What You’ll Learn
3. Understanding the Integration Problem
4. Key Concepts & Terminology
5. MCP Architecture
6. How MCP Works – Communication Flow
7. Design Principles
8. Communication Protocol Deep Dive
9. MCP Clients: The Bridge Between AI and Tools
10. Summary Table

1. Why MCP Matters

As AI systems, particularly Large Language Models (LLMs), grow more powerful, a critical limitation persists: isolation. These models are constrained by their training data and often lack direct access to real-time tools, APIs, or external knowledge bases.

Model Context Protocol (MCP) addresses this limitation by establishing a standardized way for AI systems to interface with external tools and data sources. Much like USB-C revolutionized hardware connectivity, MCP aims to do the same for AI systems—enabling interoperability, reducing integration complexity, and unlocking more intelligent, real-world applications.

2. What You’ll Learn

This unit introduces the foundational concepts of MCP:

• What is MCP? – Definition and role in the AI stack
• Core Concepts – The terminology and abstractions used in MCP
• The Integration Challenge – The M×N problem and MCP’s M+N solution
• MCP Benefits – Standardization, extensibility, and AI capability enhancement
• Example Use Case – How MCP enables practical integrations

3. Understanding the Integration Problem

The M×N Problem

Without a standard like MCP, integrating M AI applications with N tools requires building M×N custom connectors. This leads to:

• High development and maintenance overhead
• Redundant work for each integration
• A fragmented ecosystem

The M+N Solution

MCP simplifies integration by introducing a shared protocol. Each:

• AI Host implements the MCP Client once
• Tool or Data Source implements the MCP Server once

Result: only M + N integrations are needed. This modular architecture streamlines connectivity and fosters ecosystem growth.

4. Key Concepts & Terminology

Components

Note: The Client is part of the Host, handling communication with one Server.

Capabilities

MCP defines four main capability types:

This structure allows AI models to execute actions, fetch data, and interact using standardized templates.

5. MCP Architecture

MCP adopts a client-server architecture with clearly separated responsibilities:

Host

• Presents the user interface
• Determines what capabilities to use
• Connects via Clients to MCP Servers
• Renders results from external tools

Client

• Manages a 1:1 connection with one MCP Server
• Handles protocol messaging
• Acts as a bridge between Host logic and Server responses

Server

• Exposes capabilities in a standardized format
• Provides access to tools or data
• Can run locally or remotely

6. How MCP Works – Communication Flow

1. User Input: A user interacts with the Host (e.g., asks a question).
2. Intent Processing: The Host uses LLMs to understand the request.
3. Client Activation: The Host’s Client connects to the appropriate MCP Server.
4. Discovery: The Client queries the Server for available capabilities.
5. Invocation: The Host selects and invokes the needed capability.
6. Execution: The Server processes the request and returns results.
7. Response Rendering: The Host presents the results to the user.

This pipeline enables scalable, context-aware AI behavior with external support.

7. Design Principles

MCP’s design is guided by the following principles:

• Standardization: A unified protocol for all AI-tool interactions
• Simplicity: Minimal overhead with powerful abstractions
• Safety: Explicit permissioning for sensitive operations
• Discoverability: Dynamic capability discovery at runtime
• Extensibility: Versioning and modular growth
• Interoperability: Cross-platform, cross-vendor compatibility

Model Context Protocol (MCP): Communication Protocol Deep Dive

Introduction

The Model Context Protocol (MCP) defines how AI applications (Clients) and external tools or services (Servers) communicate. This standard protocol ensures consistency, predictability, and interoperability across a diverse AI ecosystem. While developers don’t need to master every detail to use MCP effectively, understanding the foundation helps with debugging, implementation, and design.

1. Communication Format: JSON-RPC 2.0

MCP is built on JSON-RPC 2.0, a lightweight, language-agnostic protocol for remote procedure calls. JSON-RPC is used because it’s:

• Human-readable
• Simple to implement across languages
• Widely adopted with well-documented standards

Message Types

MCP supports three primary JSON-RPC message types:

1. Request (Client → Server)

Used to initiate operations.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "weather",
    "arguments": {
      "location": "San Francisco"
    }
  }
}

2. Response (Server → Client)

Returned in reply to a request. Includes either a result or an error.

Success:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "temperature": 62,
    "conditions": "Partly cloudy"
  }
}

Error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid location parameter"
  }
}

3. Notification (One-way)

No id field and does not expect a response.

{
  "jsonrpc": "2.0",
  "method": "progress",
  "params": {
    "message": "Processing data...",
    "percent": 50
  }
}

2. Transport Mechanisms

While JSON-RPC defines the message structure, MCP specifies how messages are transmitted:

A. Standard Input/Output (stdio)

• Used when Client and Server run on the same machine.
• The Host launches the Server as a subprocess and communicates via stdin/stdout.

Advantages:

• Simple and secure
• No network setup required
• Suitable for local tools (e.g., file access, local scripts)

B. HTTP + SSE (Server-Sent Events)

• Used when Client and Server are on different machines.
• Communication uses HTTP for requests and SSE for real-time Server → Client updates.

Advantages:

• Works over the network
• Supports serverless environments
• Enables real-time streaming of updates

Streamable HTTP: Recent MCP versions allow dynamic upgrades to SSE, making communication both flexible and compatible with serverless hosting.

3. The MCP Interaction Lifecycle

MCP interactions follow a structured, four-stage lifecycle:

1. Initialization

• Client connects and exchanges protocol versions and capabilities.

Client → initialize
Server → response
Client → initialized

2. Discovery

• Client queries the Server to discover available capabilities.

Client → tools/list
Server → response

This is repeated for resources/list and prompts/list.

3. Execution

• Client invokes specific capabilities.

Client → tools/call
Server → progress (optional)
Server → result

4. Termination

• Client closes the session gracefully.

Client → shutdown
Server → response
Client → exit

4. Core Capability Types

A. Tools (Model-controlled)

• Executable functions triggered by the LLM.
• Can have side effects (e.g., API calls, file updates).
• Require user approval due to potential risks.

Example:

def get_weather(location: str) -> dict:
    return {
        "temperature": 72,
        "conditions": "Sunny"
    }

B. Resources (Application-controlled)

• Read-only data (no side effects).
• Safer and used for providing context.

Example:

def read_file(path: str) -> str:
    with open(path, 'r') as f:
        return f.read()

C. Prompts (User-controlled)

• Predefined instruction sets or templates for guiding interactions.
• Often selected by users via a UI.

Example:

def code_review(code: str, language: str) -> list:
    return [
        {"role": "system", "content": f"You are a code reviewer..."},
        {"role": "user", "content": f"Please review:\n{code}"}
    ]

D. Sampling (Server-initiated)

• Allows the Server to ask the Client to initiate LLM interaction.
• Enables multi-step, agent-like behaviors.

Example:

def request_sampling(messages):
    return {
        "role": "assistant",
        "content": "Here's a refined version based on your data..."
    }

Sampling Flow:

Server → sampling/createMessage
Client → sample from LLM
Client → returns message

5. Discovery Protocol

Clients can dynamically adapt by querying:

• tools/list – Discover Tools
• resources/list – Discover Resources
• prompts/list – Discover Prompts

This dynamic approach allows flexible and extensible integration with Servers.

6. Capability Comparison Table

9. MCP Clients: The Bridge Between AI and Tools

Overview

In the Model Context Protocol (MCP) ecosystem, the Client plays a pivotal role. It acts as a bridge between an AI application (called the Host) and external services (called Servers) that provide capabilities such as tools, resources, prompts, and sampling.

This section will guide you through:

• What MCP Clients are and their purpose
• How to configure MCP Clients for both local and remote use
• Real-world client implementations in chat interfaces, IDEs, and code agents
• Hands-on examples using smolagents and Hugging Face MCP-compatible servers

1. What is an MCP Client?

An MCP Client is a component within a Host (like an AI assistant or smart IDE) that manages communication with one or more MCP Servers.

Key Responsibilities:

• Connect to MCP Servers using defined transport (e.g., stdio, sse)
• Discover and list available capabilities
• Send requests and receive results from MCP Servers
• Relay data between LLMs and external tools or data

Think of it as the “network card” of your AI application—it translates and channels intent into action.

2. Examples of MCP Clients in Action

A. Chat Interfaces

• Claude Desktop (Anthropic) – Integrates with multiple MCP Servers, exposing capabilities through natural language chat.

B. Developer Tools

• Cursor IDE – Embedded MCP Client supports tool invocation for AI-powered code writing.
• Continue.dev (VS Code) – A popular open-source plugin that allows AI-driven development via MCP integrations.

3. Configuring MCP Clients

Configuration is typically done via a standardized JSON file: mcp.json.

A. Base Structure

{
  "servers": [
    {
      "name": "Server Name",
      "transport": {
        "type": "stdio" | "sse"
      }
    }
  ]
}

B. Local Server with stdio Transport

Launches a local script as a server:

{
  "servers": [
    {
      "name": "File Explorer",
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/file_explorer_server.py"]
      }
    }
  ]
}

C. Remote Server with HTTP + SSE Transport

Connects to a web-accessible server:

{
  "servers": [
    {
      "name": "Weather API",
      "transport": {
        "type": "sse",
        "url": "https://example.com/mcp-server"
      }
    }
  ]
}

D. Using Environment Variables

To securely pass credentials or config values:

# In your server script
import os
token = os.environ.get("GITHUB_TOKEN")

{
  "servers": [
    {
      "name": "GitHub API",
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/github_server.py"],
        "env": {
          "GITHUB_TOKEN": "your_github_token"
        }
      }
    }
  ]
}

4. Coding with MCP Clients

You can use the MCP Client directly within code to integrate tools into intelligent agents.

A. Using smolagents with Local Server

from smolagents import ToolCollection
from mcp.client.stdio import StdioServerParameters

server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"])

with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tools:
    for tool in tools.tools:
        print(f"{tool.name}: {tool.description}")

B. Connecting to a Remote MCP Server

from smolagents.mcp_client import MCPClient

with MCPClient({"url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"}) as tools:
    for t in tools:
        print(f"{t.name}: {t.description}")

C. Using Tools in a Code Agent

from smolagents import InferenceClientModel, CodeAgent, ToolCollection
from mcp.client.stdio import StdioServerParameters

model = InferenceClientModel()
server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"])

with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tools:
    agent = CodeAgent(tools=[*tools.tools], model=model)
    agent.run("What's the weather in Tokyo?")

D. Connecting to a Packaged MCP Tool (e.g. pubmedmcp)

import os
from smolagents import ToolCollection, CodeAgent
from mcp import StdioServerParameters

server_parameters = StdioServerParameters(
    command="uv",
    args=["--quiet", "pubmedmcp@0.1.3"],
    env={"UV_PYTHON": "3.12", **os.environ},
)

with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tools:
    agent = CodeAgent(tools=[*tools.tools], add_base_tools=True)
    agent.run("Please find a remedy for hangover.")

10. Summary Table