Tutorial MCP: De cero a servidor en producción con la especificación 2026-07-28

Puntos clave

• 97M+ descargas mensuales del SDK de MCP, pero solo el 8.5% de los servidores usan OAuth — la adopción del protocolo supera su postura de seguridad, lo que hace que los pasos de endurecimiento de producción de este tutorial no sean opcionales para ningún despliegue B2B.
• MCP SDK v2 redujo el tamaño del paquete 83% y mejoró la velocidad 25% — la especificación 2026-07-28 se publicó junto con SDKs rediseñados para TypeScript, Python, Go y C#, con guías de migración para cada uno.
• La especificación 2026-07-28 eliminó las sesiones y el handshake de inicialización — cada petición es ahora autónoma, llegando a cualquier instancia del servidor detrás de un balanceador de carga round-robin sin estado compartido.
• El roadmap de MCP del 22 de agosto define cinco áreas prioritarias — identidad de agentes, unificación de transporte HTTP, primitivas de mensajería agéntica, primitivas de herramientas mejoradas y experiencia de desarrollador del SDK — cada una abordada en el camino de producción de este tutorial.
• El 82% de los servidores MCP son vulnerables a path traversal (según Practical DevSecOps) — los pasos de sandboxing y validación de entradas aquí son la diferencia entre una demo y un despliegue.

El Model Context Protocol superó los 97 millones de descargas mensuales del SDK en 2026, con los SDKs de TypeScript y Python superando cada uno los 1,000 millones de descargas totales. La especificación 2026-07-28 publicó la mayor revisión desde el lanzamiento: un núcleo de protocolo stateless, extensiones de primera clase y tres deprecaciones que simplifican la superficie de despliegue. Tres semanas después, el 22 de agosto, los mantenedores de MCP publicaron un nuevo roadmap definiendo cinco áreas prioritarias para el próximo ciclo de especificación — identidad de agentes, unificación de transporte HTTP, primitivas de mensajería agéntica, primitivas de herramientas mejoradas y experiencia de desarrollador del SDK.

Este tutorial cubre el camino de producción: construir un servidor MCP que sea stateless, escalable horizontalmente, consciente de la identidad y listo para las prioridades empresariales del roadmap. El quickstart oficial recorre un servidor de clima conectado a Claude Desktop. Este artículo comienza donde termina ese quickstart — los pasos entre una demo funcional y un servidor que pondrías detrás de un sistema de agentes B2B en producción.

Paso 1 — Configuración del proyecto con SDK v2

La especificación 2026-07-28 se publicó junto con SDKs rediseñados. El TypeScript SDK v2 redujo el tamaño del paquete aproximadamente 83% y mejoró el rendimiento 25% mediante una nueva división cliente-servidor. El Python SDK 2.0+, el Go SDK y el C# SDK v2.0 todos hablan la versión de protocolo 2026-07-28 a partir del día de publicación, con notas de migración detalladas para los cambios disruptivos.

Para este tutorial, usamos Python 3.10+ con uv:

uv init mcp-server
cd mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]"

El extra mcp[cli] trae las herramientas CLI para ejecutar e inspeccionar servidores. El SDK usa type hints y docstrings de Python para generar definiciones de herramientas automáticamente — defines una función, la decoras y los metadatos del protocolo se derivan de la firma.

Paso 2 — Define tus primeras herramientas

Un servidor MCP expone tres tipos de capacidades: tools (funciones que el modelo llama), resources (datos que el modelo lee) y prompts (flujos de trabajo plantillados). Para un servidor B2B, las tools son la superficie principal — son cómo un agente busca en un catálogo, genera una cotización o retiene inventario.

from mcp.server import MCPServer

mcp = MCPServer("catalog-server")

@mcp.tool()
async def search_catalog(query: str, supplier_id: str | None = None) -> str:
    """Search the supplier catalog by keyword, optionally filtered by supplier.

    Args:
        query: Search keyword (SKU, product name, or category)
        supplier_id: Optional supplier filter (e.g., "s-12")
    """
    results = await catalog.search(query=query, supplier_id=supplier_id)
    return format_results(results)

@mcp.tool()
async def get_pricing(sku: str, quantity: int) -> str:
    """Get tiered pricing for a SKU at a given quantity.

    Args:
        sku: Supplier product identifier
        quantity: Order quantity (determines pricing tier)
    """
    price = await pricing_engine.get(sku=sku, quantity=quantity)
    return f"SKU {sku}: ${price.unit_price:.2f} (tier: {price.tier_name})"

El docstring de cada herramienta se convierte en la descripción que el modelo ve en su lista de herramientas. Los type hints se convierten en el esquema de entrada. Este es el patrón del MCP Module Code Standard: cada herramienta tiene un esquema tipado, un docstring claro y una única responsabilidad.

Trampa del logging STDIO: para servidores basados en STDIO, nunca escribas a stdout — corrompe el flujo de mensajes JSON-RPC. Usa el módulo estándar logging, que escribe a stderr:

import logging
logger = logging.getLogger(__name__)
logger.info("Catalog search: query=%s", query)  # stderr, safe

Paso 3 — Transporte: STDIO vs Streamable HTTP

La especificación 2026-07-28 hace que los servidores MCP remotos sean "no diferentes de cualquier otra carga HTTP" (changelog de la especificación). La segunda área prioritaria del roadmap — unificación de transporte HTTP-native — extiende esto a servidores locales que hablan Streamable HTTP sobre stdio, unificando en un modelo de transporte.

Para desarrollo local y clientes de escritorio, STDIO es el predeterminado:

if __name__ == "__main__":
    mcp.run(transport="stdio")

Para despliegues B2B en producción — donde el agente se ejecuta como una carga en la nube, no como una aplicación de escritorio — Streamable HTTP es el transporte de producción. El servidor se ejecuta detrás de un balanceador de carga, acepta peticiones HTTP POST con cabeceras Mcp-Method y Mcp-Name, y responde con JSON-RPC sobre HTTP:

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8080)

La función de enrutamiento basado en cabeceras significa que tu gateway, limitador de tasa o WAF puede enrutar y medir en las cabeceras Mcp-Method y Mcp-Name directamente — sin análisis del cuerpo JSON para decisiones de enrutamiento. Esta es la forma de despliegue para la que el protocolo stateless fue diseñado: un conjunto de instancias de servidor stateless detrás de un balanceador de carga round-robin, sin capa de sesión compartida.

Paso 4 — Handles explícitos para flujos de trabajo con estado

Stateless no significa que el estado desaparezca. La especificación 2026-07-28 reemplaza el estado de sesión oculto con el patrón de handle explícito: una herramienta crea un handle (un order_id, un quote_id, un basket_id) y el modelo lo pasa de vuelta como un argumento ordinario en llamadas subsecuentes. Esto se cubre en detalle en MCP 2026-07-28: Qué significa el protocolo stateless para despliegues de agentes B2B.

Para un flujo de cotización que abarca cinco llamadas a herramientas — crear petición, buscar catálogo, generar cotización, retener disponibilidad, aplicar nivel de precios — los handles se hilan a través de cada llamada:

@mcp.tool()
async def create_request(buyer_id: str, line_items: list[dict]) -> str:
    """Create an RFQ request and return a request_id handle."""
    request = await rfq_engine.create(buyer_id, line_items)
    return f"request_id={request.id}"

@mcp.tool()
async def generate_quote(request_id: str, supplier_ids: list[str]) -> str:
    """Generate a quote from specified suppliers. Returns quote_id."""
    quote = await rfq_engine.quote(request_id, supplier_ids)
    return f"quote_id={quote.id}"

Cada llamada lleva el handle que necesita. Ningún servidor recuerda nada entre llamadas. Si el balanceador de carga enruta la llamada 4 a una instancia diferente que la llamada 3, sigue funcionando — el handle está en la petición. Si el equipo de auditoría necesita reconstruir este flujo de trabajo una semana después, los handles en los argumentos de la petición cuentan la historia completa.

Paso 5 — Identidad de agentes: la brecha empresarial

La tercera área prioritaria del roadmap — identidad de agentes y seguridad empresarial — es la más significativa para despliegues B2B. El roadmap es explícito: la autorización MCP hoy está "construida alrededor de una persona aprobando acceso en un navegador," pero "cada vez más de los llamadores son agentes ejecutándose como cargas en la nube con su propia identidad, actuando en nombre de un usuario que no está presente, o delegando autoridad más estrecha a sub-agentes."

El camino a seguir, según lo definido por el roadmap:

1. DPoP (RFC 9449) — Demonstrating Proof of Possession vincula un token OAuth a una clave en posesión del cliente. Un token robado por sí solo no puede reproducir peticiones desde otro proceso. DPoP no decide qué se permite hacer al agente; hace que la credencial sea más difícil de reutilizar fuera de su titular previsto.
2. Workload Identity Federation — el grupo de trabajo IETF WIMSE está desarrollando arquitectura para identidad de cargas de trabajo en entornos multi-sistema. Un agente es una carga de trabajo, así que obtiene una identidad de carga de trabajo: nombrada con un SPIFFE ID, autenticada con credenciales de corta duración, no una API key compartida.
3. Enterprise-Managed Authorization (EMA) — la extensión EMA mueve la decisión de acceso al proveedor de identidad de la organización. El cliente MCP intercambia una aserción de identidad de usuario por un Identity Assertion JWT Authorization Grant (ID-JAG), luego intercambia ese grant por un token de acceso específico del servidor. Esto soporta asignación y revocación central.

Para el servidor de producción de este tutorial, la línea base mínima es:

• No API keys compartidas. Cada agente obtiene un token de corta duración, vinculado a una audiencia.
• OAuth con DPoP. El informe Practical DevSecOps MCP Security Statistics 2026 encontró que solo el 8.5% de los servidores MCP usan OAuth — el 91.5% restante confía en API keys o ninguna autenticación.
• Intercambio de tokens en cada límite de confianza. El estándar de intercambio de tokens CoSAI (publicado el 18 de agosto) establece el intercambio de tokens como control fundacional para flujos de trabajo agénticos. Cada punto de entrada register_tools() debería aceptar un token con alcance de tarea, no una credencial persistente.

Consulta el MCP Security Hardening Checklist para los 12 controles que verifican estos estándares antes de producción, y el MCP Module Code Standard para la postura defensiva a nivel de módulo.

Paso 6 — Descubrimiento progresivo de herramientas: resolviendo el problema de las cien herramientas

La cuarta área prioritaria del roadmap — primitivas mejoradas — aborda un problema concreto de producción: "Conectar a un servidor con cien herramientas significa que el modelo paga por toda esa superficie antes de que el usuario haya hecho una sola pregunta, y la selección de herramientas tiende a empeorar a medida que la lista crece."

La respuesta del roadmap es descubrimiento progresivo: un servidor ofrece un pequeño punto de entrada y revela más de su catálogo a medida que la conversación se estrecha. En lugar de volcar 100 esquemas de herramientas en la ventana de contexto del modelo al conectar, el servidor expone un puñado de herramientas de nivel superior y expande dinámicamente la superficie basándose en lo que el agente está haciendo.

La especificación 2026-07-28 ya proporciona los bloques de construcción:

• RPC server/discover — un cliente puede aprender las capacidades de un servidor antes de hacer nada más, sin un handshake de sesión.
• tools/list con ttlMs y cacheScope — las respuestas de lista llevan pistas de caché, así los clientes cachean los catálogos de herramientas y evitan refetch en cada conexión.
• _meta en cada petición — versión del protocolo, info del cliente y capacidades viajan por petición, no en una sesión negociada.

Para un servidor con 50+ herramientas, el patrón de descubrimiento progresivo se ve así:

@mcp.tool()
async def discover_tools(category: str) -> str:
    """Discover available tools in a category. Start here for a guided tour.

    Args:
        category: Tool category — 'catalog', 'pricing', 'inventory', 'orders'
    """
    available = tool_registry.by_category(category)
    return format_tool_list(available)

El agente llama discover_tools("catalog") primero, obtiene un conjunto enfocado de 5-8 herramientas, y solo expande a otras categorías cuando el flujo de trabajo lo requiere. Esto mantiene la ventana de contexto ligera y la selección de herramientas precisa — el mismo principio detrás del diseño de herramientas de responsabilidad única del MCP Module Code Standard.

Paso 7 — Despliegue: stateless, horizontal, detrás de un balanceador de carga

La forma de despliegue para la que la especificación 2026-07-28 fue diseñada:

                    ┌──────────────────┐
                    │  Load Balancer   │
                    │  (round-robin)   │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────┴────┐ ┌───────┴────┐ ┌───────┴────┐
     │ MCP Server  │ │ MCP Server  │ │ MCP Server  │
     │  Instance 1 │ │  Instance 2 │ │  Instance 3 │
     │ (stateless) │ │ (stateless) │ │ (stateless) │
     └─────────────┘ └─────────────┘ └─────────────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────┴─────────┐
                    │  Upstream Systems │
                    │  (NetSuite, etc.)  │
                    └──────────────────┘

Sin almacén de sesión compartido. Sin balanceador de carga con sesiones sticky. Sin infraestructura de replay de sesión. Cada petición lleva lo que necesita — versión del protocolo, info del cliente, capacidades y handles — en el cuerpo y cabeceras de la petición, no en estado del lado del servidor.

Para el endurecimiento de producción:

• Sandbox en cada instancia del servidor. El MCP Project Sandboxing Baseline (publicado el 16 de agosto) requiere sandboxing a nivel de SO para procesos generados. Usa Landlock (Linux), Seatbelt (macOS) o Windows ACLs para restringir el acceso al sistema de archivos y red. La tasa de vulnerabilidad de path traversal del 82% (según Practical DevSecOps) es la evidencia de que la validación de entradas por sí sola es insuficiente.
• Limita la tasa de cada herramienta. El MCP Module Code Standard requiere límites de tasa por herramienta. La vulnerabilidad DoS del MCP Ruby SDK (divulgada el 16 de agosto) confirma que los ataques de agotamiento de recursos son una superficie de ataque real.
• Log a OpenTelemetry, no al canal de logging de MCP. La especificación 2026-07-28 deprecó la característica de Logging en favor de stderr y OpenTelemetry. Los logs del servidor MCP se integran con pipelines de observabilidad existentes (Datadog, CloudWatch, Honeycomb) sin un transporte personalizado.
• Usa enrutamiento basado en cabeceras para WAF y limitación de tasa. Las cabeceras Mcp-Method y Mcp-Name permiten a tu gateway enrutar y autorizar sin analizar cuerpos JSON.

El roadmap adelante: cinco áreas prioritarias

El roadmap del 22 de agosto define la dirección para el próximo ciclo de especificación. Este tutorial cubre las partes listas para producción; el roadmap nombra lo que viene después:

Área prioritaria	Estado	Cobertura del tutorial
Identidad de agentes y seguridad empresarial	En progreso (DPoP, WIMSE, EMA)	Paso 5 — línea base establecida; implementación completa pendiente de finalización de la especificación
Unificación de transporte HTTP-native	Publicado (remoto), en progreso (local)	Paso 3 — HTTP remoto es producción; Streamable HTTP local sobre stdio es el objetivo del roadmap
Primitivas de mensajería agéntica	Extensiones publicándose (Tasks, suscripciones)	No cubierto — eventos iniciados por servidor (webhooks, canales) son la próxima frontera
Primitivas mejoradas (descubrimiento progresivo)	Fase de diseño	Paso 6 — el patrón es implementable hoy usando discover_tools; soporte a nivel de especificación está en camino
Experiencia de desarrollador del SDK mejorada	Publicado (SDK v2, pruebas de conformidad)	Paso 1 — SDK v2 es la línea base de producción actual

El roadmap es dirección, no una promesa de compatibilidad. La especificación del 28 de julio ya entregó el núcleo HTTP stateless y la extensión Tasks. Los eventos push, el descubrimiento unificado, la delegación y la conformidad entre SDKs aún necesitan trabajo de implementación. Para despliegues B2B, la prioridad de identidad de agentes es la que hay que observar — aborda la brecha exacta (API keys y tokens de larga duración) que los artículos de seguridad MCP y el checklist de gobernanza han estado señalando.

El camino de producción del tutorial cubre el checklist de producción de cinco pasos:

Lectura relacionada

• MCP 2026-07-28: Qué significa el protocolo stateless para despliegues de agentes B2B — el análisis complementario que cubre el protocolo stateless, el patrón de handle explícito y las deprecaciones en profundidad
• MCP Module Code Standard — el patrón estructural que hace cada módulo listo para producción: estructura de directorios, registro de herramientas, manejo de errores, límites de tasa y logging de auditoría
• MCP Security Hardening Checklist: 1,467 servidores expuestos y los controles que los cierran — los 12 controles que verifican un servidor antes de producción, abordando las brechas de path traversal del 82% y OAuth del 8.5%

Viñeta de construcción

Un distribuidor de mercado medio que ejecuta NetSuite quería dar a su equipo de ventas un asistente de IA que pudiera buscar catálogos de proveedores, generar cotizaciones y verificar niveles de inventario sin salir del CRM. El primer intento usó una sola API key compartida entre todas las instancias del agente — el 91.5% de los servidores MCP que omiten OAuth. Una actualización de la lista de precios de un proveedor expuso la clave en un archivo de log, y el equipo pasó dos días rotando credenciales en 15 servicios.

La reconstrucción siguió el camino de producción de este tutorial: SDK v2 con esquemas de herramientas tipados, transporte Streamable HTTP detrás de un balanceador de carga round-robin, tokens OAuth vinculados con DPoP con expiración de 15 minutos, handles explícitos para el flujo de cotización de cinco pasos y sandboxing a nivel de SO en cada instancia del servidor. El agente se conecta a NetSuite a través de un módulo MCP siguiendo el estándar de código, con descubrimiento progresivo exponiendo 8 herramientas de catálogo primero y expandiendo a precios e inventario solo cuando el flujo de trabajo lo requiere. Seis instancias de servidor se ejecutan stateless detrás del balanceador de carga. Sin almacén de sesión compartido. Sin sesiones sticky. Cada petición lleva su handle, su token y su versión de protocolo.

Solicita una construcción con alcance definido

Discovery de una semana. Obtienes un inventario de sistemas, un mapa de flujos de trabajo y un alcance fijo — construyas con nosotros o no.