Demo de MCP — Herramientas de agente Python desde cero

¿Qué es MCP?

MCP (Model Context Protocol) es un protocolo estandarizado que permite a las aplicaciones de IA descubrir y usar herramientas, recursos e indicaciones externos a través de una interfaz consistente.

En lugar de que cada framework de IA invente una integración diferente para cada base de datos, API, sistema de archivos o servicio interno, un host de MCP puede conectarse a un servidor de MCP y usar la misma superficie de protocolo.

Problemas que resuelve MCP

En el cable, MCP usa mensajes JSON-RPC 2.0 sobre transportes como stdio y transportes basados en HTTP (SSE/Streamable HTTP). Este repositorio usa stdio: el cliente lanza el servidor como un subproceso, envía mensajes de protocolo a través de stdin y recibe respuestas a través de stdout.

Related MCP server: Weather MCP Server

Arquitectura

flowchart TD
    A[User: "What's the weather in London?"] --> B[AI Agent<br/>OpenAI Responses API]
    B --> C[1. Discovers MCP tools]
    B --> D[2. Decides whether to call]
    B --> E[3. Emits function call]
    E --> F[MCP Client<br/>ClientSession + stdio]
    F --> G[initialize]
    F --> H[tools/list]
    F --> I[tools/call]
    I --> J[JSON-RPC 2.0<br/>stdin/stdout]
    J --> K[MCP Server subprocess]
    K --> L[get_current_weather tool]
    K --> M[greeting://{name} resource]

¿Por qué el SDK oficial?

Este repositorio usa el SDK oficial de MCP para Python en lugar de reimplementar el protocolo. El SDK proporciona:

• Ciclo de vida y validación del protocolo

• Abstracción de transporte (stdio, HTTP/SSE)

• APIs tipadas de cliente/servidor

El código de la aplicación aún hace explícitos los conceptos importantes de MCP: registro del servidor, esquemas de herramientas, initialize, tools/list, tools/call, lecturas de recursos y gestión de procesos stdio.

La API estable v2 del SDK actual usa MCPServer para la construcción del servidor y ClientSession/stdio_client para clientes stdio.

Estructura del proyecto

mcp-demo/
├── README.md
├── requirements.txt
├── .env.example
├── pyproject.toml
├── src/
│   ├── mcp_server/
│   │   ├── __init__.py
│   │   ├── server.py      # MCP server entry point
│   │   ├── tools.py       # Tool implementations
│   │   ├── handlers.py    # Request handlers
│   │   └── utils.py       # Shared utilities
│   ├── mcp_client/
│   │   ├── __init__.py
│   │   ├── client.py      # MCP client wrapper
│   │   ├── agent.py       # OpenAI agent integration
│   │   └── runner.py      # Demo runner
│   └── shared/
│       ├── __init__.py
│       └── types.py       # Shared Pydantic models
├── tests/
│   ├── test_server.py
│   └── test_client.py
├── examples/
│   └── demo.ipynb
└── scripts/
    └── run_demo.sh

Requisitos

• Python 3.10+

• Clave de API de OpenAI (para la demo de agente de IA)

• No se requiere clave de API de clima — la herramienta de clima usa datos de muestra deterministas para que la ruta de MCP funcione sin conexión.

Inicio rápido

1. Crear entorno virtual

python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\Activate.ps1       # Windows PowerShell

2. Instalar dependencias

python -m pip install --upgrade pip
pip install -r requirements.txt

3. Configurar OpenAI

cp .env.example .env

Edita .env con tus credenciales:

OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4.1-mini

El servidor en sí no necesita la clave de OpenAI.

Ejecutar la demo

Desde la raíz del repositorio

python src/mcp_client/runner.py

Qué hace el ejecutor:

Alternativa: envoltorio de shell

bash scripts/run_demo.sh

Salida esperada

La redacción exacta varía según el modelo, pero el flujo de registros se ve así:

INFO mcp_client.client: -> MCP initialize
INFO mcp_client.client: <- MCP initialize: server=mcp-demo-server
INFO mcp_client.client: -> MCP tools/list
INFO mcp_client.client: <- MCP tools/list: ["get_current_weather"]
INFO mcp_client.agent: User: What's the weather in London?
INFO mcp_client.agent: OpenAI requested tool: get_current_weather {"city":"London","units":"metric"}
INFO mcp_client.client: -> MCP tools/call name=get_current_weather arguments={"city":"London","units":"metric"}
INFO mcp_server.tools: weather lookup city=London units=metric
INFO mcp_client.client: <- MCP tools/call result={"city":"London","temperature":18.0,...}
INFO mcp_client.agent: Final: London is 18°C and partly cloudy.

Los registros muestran deliberadamente mensajes semánticos de MCP en el límite de la aplicación. El SDK maneja el encuadre JSON-RPC internamente.

Ejecutar servidor MCP de forma independiente

python src/mcp_server/server.py

Un servidor MCP stdio parece "colgarse" — esto es esperado. Espera mensajes de protocolo en stdin. Un host/cliente debe lanzarlo y ser dueño de las tuberías stdio.

Inspección interactiva del protocolo

pip install "mcp[cli]"
mcp dev src/mcp_server/server.py

Métodos MCP demostrados

El SDK oficial maneja el ciclo de vida JSON-RPC:

El cliente llama explícitamente a initialize() antes de listar o invocar capacidades. Los decoradores del servidor generan esquemas de herramientas/recursos a partir de anotaciones de tipo de Python.

Herramienta: get_current_weather

get_current_weather(
    city: str,
    units: Literal["metric", "imperial"] = "metric"
) -> WeatherResponse

Devuelve un payload estructurado respaldado por Pydantic:

{
  "city": "London",
  "temperature": 18.0,
  "units": "metric",
  "condition": "partly cloudy",
  "humidity_percent": 72
}

Las ciudades desconocidas fallan con un error controlado de herramienta MCP en lugar de bloquear el servidor.

Flujo de integración del agente

El agente usa llamadas de función de OpenAI simples (sin framework adicional) para mantener la demo enfocada:

flowchart LR
    A[MCP Tool Schema] --> B[OpenAI Function Tool]
    B --> C[Model Chooses Function]
    C --> D[MCP ClientSession.call_tool]
    D --> E[MCP Server Executes Tool]
    E --> F[Function Call Output]
    F --> G[Final Model Answer]

Este es el mismo patrón que envuelven los frameworks de agentes: descubrir herramientas MCP → exponer esquemas al modelo → enrutar las llamadas seleccionadas de vuelta a través de MCP → alimentar los resultados en el siguiente turno del modelo.

Pruebas

pytest -q

La suite de pruebas cubre:

• ✅ Ejecución de herramienta (clima métrico)

• ✅ Ejecución de herramienta (clima imperial)

• ✅ Comportamiento de validación/error (ciudad desconocida)

• ✅ Descubrimiento de cliente MCP en proceso e invocación de herramientas

Las pruebas usan el cliente en memoria del SDK cuando es posible — evita la inestabilidad de subprocesos mientras se ejercita la capa real del protocolo MCP.

Formato y linting

Este proyecto usa Ruff:

# Check
ruff check .
ruff format --check .

# Format
ruff format .

Notas de producción

Esta demo es deliberadamente pequeña, pero representa varias preocupaciones de producción:

Para fuentes de datos externas reales: reemplaza el clima determinista con llamadas autenticadas a API/bases de datos, agrega timeouts, reintentos, limitación de tasa, observabilidad y gestión de secretos.

Modelo mental del protocolo

Secuencia JSON-RPC simplificada:

// Client -> Server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

// Server -> Client
{"jsonrpc":"2.0","id":1,"result":{...}}

// Client -> Server
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Server -> Client
{"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

// Client -> Server
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"get_current_weather","arguments":{"city":"London"}}}

// Server -> Client
{"jsonrpc":"2.0","id":3,"result":{"content":[...],"structuredContent":{...}}}

El esquema exacto del protocolo es mantenido por la especificación de MCP y el SDK. Lo anterior está intencionalmente simplificado para la enseñanza.

Referencias

• SDK oficial de MCP para Python: https://py.sdk.modelcontextprotocol.io/

• Especificación de MCP: https://modelcontextprotocol.io/specification/

• Llamadas de función de OpenAI: https://platform.openai.com/docs/guides/function-calling