Model Context Protocol (MCP): el estándar que conecta los agentes de IA con el mundo real

11 min read

El model context protocol es la pieza que faltaba para que los agentes de IA dejen de ser demos y se conviertan en herramientas reales de producción. Llevo meses trabajando con MCP en proyectos propios y la diferencia es tan grande que merece una guía completa. Aquí te explico qué es, cómo funciona por dentro y cómo construir tu propio servidor desde cero en TypeScript.

MCP no es una librería ni un framework. Es un protocolo, como HTTP o WebSocket. Eso significa que puedes implementarlo en cualquier lenguaje y conectarlo con cualquier cliente compatible.

Flujo completo de una llamada MCP desde el usuario hasta tu API

El MCP Inspector es tu mejor aliado para depurar. Antes de abrir Claude, verifica siempre que tus tools responden correctamente desde el inspector. Te ahorra el ciclo de reiniciar Claude Desktop con cada cambio.

La clave de un MCP server mantenible es que el protocolo no sepa nada de negocio y el negocio no sepa nada del protocolo. McpServer registra tools. ProductService ejecuta lógica. Jamás mezcles los dos.

El model context protocol resuelve un problema real que todo equipo que trabaja con agentes de IA ha sufrido: la falta de un estándar para conectar modelos con el mundo. No es una tecnología experimental; en 2026 ya es parte del stack de producción de equipos serios. Si ya tienes una API REST funcionando, añadir una capa MCP encima es cuestión de días, no de meses. El SDK de TypeScript está maduro, el ecosistema de clientes compatibles crece cada semana y las lecciones de producción, aunque reales, son manejables con los patrones correctos. Si estás construyendo agentes de IA o integrando LLMs en tus sistemas, MCP no es opcional. Es el siguiente paso natural.

Qué es el Model Context Protocol y por qué la industria lo está adoptando#

El Model Context Protocol es un protocolo abierto creado por Anthropic que estandariza cómo los modelos de IA se comunican con herramientas y fuentes de datos externas. La primera versión pública apareció a finales de 2024 y en 2026 ya lo soportan Claude, varios modelos de OpenAI, Cursor, Continue, Zed y decenas de herramientas del ecosistema. Cuando hablo de protocolo contexto modelo con clientes y equipos de desarrollo, la analogía que mejor funciona es la del lenguaje común: antes de MCP, cada modelo hablaba su propio dialecto con cada herramienta. Ahora todos hablan el mismo idioma.

La arquitectura tiene tres componentes principales. El MCP Host es la aplicación que el usuario utiliza directamente, por ejemplo Claude Desktop o Claude Code. El MCP Client vive dentro del host y gestiona la conexión con los servidores. El MCP Server es el proceso externo que expone capacidades concretas: herramientas que el modelo puede invocar, recursos de datos que puede leer y prompts predefinidos que puede reutilizar. Un MCP servidor bien diseñado es independiente del modelo que lo consume; puedes conectar el mismo servidor a Claude, a un modelo de OpenAI o a cualquier host compatible sin cambiar una sola línea de código del servidor.

La comunicación entre cliente y servidor puede ocurrir de dos formas. La primera es mediante stdio, donde el host lanza el servidor como un subproceso y se comunica a través de stdin/stdout. Es la opción más simple para uso local y la que usarás durante el desarrollo. La segunda es HTTP con Server-Sent Events (SSE), que permite servidores remotos y es la opción natural para producción cuando varios agentes necesitan acceder al mismo servidor de forma concurrente.

Lo que hace especial a MCP no es solo la estandarización técnica. Es que al ser un protocolo abierto, cualquier herramienta que soporte MCP puede conectarse a cualquier servidor MCP, independientemente de quién lo construyó. Es el USB-C de las integraciones de IA: un conector universal que elimina el caos de los adaptadores propietarios. La velocidad de adopción habla por sí sola: en menos de dos años pasó de ser un experimento de Anthropic a convertirse en el estándar de facto que empresas como Block, Replit, Sourcegraph y decenas más ya usan en producción para conectar sus agentes IA con APIs internas.

MCP en producción: lecciones reales desde mcp-canva#

Llevo tiempo trabajando en mcp-canva, un MCP servidor que conecta Claude con la API de Canva para generar presentaciones educativas de forma automatizada. Este proyecto me ha enseñado más sobre el model context protocol en producción que cualquier documentación oficial. Voy al grano con lo que importa.

Lo primero que aprendí es que la autenticación es el problema más delicado. En un servidor MCP que corre localmente vía stdio, las credenciales viven en el archivo de configuración del cliente. Eso está bien para desarrollo, pero en producción con transporte HTTP necesitas un sistema de autenticación propio. En mcp-canva lo resolvemos con tokens de corta duración que el servidor valida en cada request. El flujo es: el agente obtiene un token de sesión, lo pasa como variable de entorno al servidor y el servidor lo refresca automáticamente antes de caducar. No des acceso permanente a ningún servidor MCP que toques datos sensibles.

Lo segundo es el manejo de timeouts. Las agentes IA API como Canva o Gemini tienen latencia variable. Un proceso de generación de imágenes puede tardar entre 3 y 45 segundos según la carga del servidor externo. Si tu tool MCP no gestiona esto correctamente, Claude marcará la operación como fallida y el usuario verá un error confuso. La solución es implementar operaciones asíncronas: la tool devuelve inmediatamente un job ID, y una segunda tool permite al agente consultar el estado. Es el mismo patrón que cualquier cola de trabajos. El agente sondea periódicamente hasta que el job termina.

Lo tercero es el testing. Un servidor MCP es, al final, un servidor JSON-RPC. Puedes testearlo con cualquier framework estándar de Node.js. En mcp-canva usamos Vitest con un cliente MCP en memoria que no necesita stdio ni red. Cada tool tiene sus tests de integración que verifican el contrato de entrada/salida. El MCP Inspector también tiene un modo headless útil para pipelines de CI.

Lo cuarto es la observabilidad. En producción necesitas saber qué tools invoca el agente, con qué parámetros y cuánto tarda cada llamada. Un middleware de logging a nivel de transport te da esa visibilidad sin modificar la lógica de negocio. Configura alertas cuando una tool tarde más de tu SLA objetivo. Los agentes IA API son sistemas distribuidos y deben monitorizarse como tales.

Implementación completa del servidor MCP#

A continuación el servidor completo. Fíjate en tres cosas: los schemas Zod que definen qué acepta cada herramienta, el handler que ejecuta la lógica real y el transport stdio que gestiona la comunicación con el host.

TypeScript

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// Tipo de producto — en producción esto viene de tu ORM o API client
interface Product {
  id: string;
  sku: string;
  name: string;
  price: number;
  stock: number;
  status: 'active' | 'disabled' | 'out_of_stock';
}

// Simulamos una capa de servicio real
async function fetchProducts(filters: {
  sku?: string;
  status?: string;
  limit?: number;
}): Promise<Product[]> {
  // Aquí iría tu llamada a la API de Magento, tu ORM de Symfony, etc.
  const baseUrl = process.env.API_BASE_URL;
  const apiKey = process.env.API_KEY;

  const params = new URLSearchParams();
  if (filters.sku) params.append('sku', filters.sku);
  if (filters.status) params.append('status', filters.status);
  if (filters.limit) params.append('limit', String(filters.limit));

  const response = await fetch(`${baseUrl}/products?${params}`, {
    headers: { 'X-API-Key': apiKey ?? '' },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

async function updateProductStock(
  sku: string,
  quantity: number
): Promise<{ success: boolean; message: string }> {
  const baseUrl = process.env.API_BASE_URL;
  const apiKey = process.env.API_KEY;

  const response = await fetch(`${baseUrl}/products/${sku}/stock`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey ?? '',
    },
    body: JSON.stringify({ quantity }),
  });

  if (!response.ok) {
    throw new Error(`Stock update failed: ${response.status}`);
  }

  return response.json();
}

// Crear el servidor MCP
const server = new McpServer({
  name: 'product-catalog-mcp',
  version: '1.0.0',
});

// Tool 1: consultar productos
server.tool(
  'search_products',
  'Busca productos en el catálogo por SKU, estado o con límite de resultados',
  {
    sku: z.string().optional().describe('SKU exacto del producto'),
    status: z
      .enum(['active', 'disabled', 'out_of_stock'])
      .optional()
      .describe('Estado del producto'),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(10)
      .describe('Número máximo de resultados'),
  },
  async ({ sku, status, limit }) => {
    const products = await fetchProducts({ sku, status, limit });

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(products, null, 2),
        },
      ],
    };
  }
);

// Tool 2: actualizar stock
server.tool(
  'update_stock',
  'Actualiza la cantidad en stock de un producto por su SKU',
  {
    sku: z.string().describe('SKU del producto a actualizar'),
    quantity: z
      .number()
      .int()
      .min(0)
      .describe('Nueva cantidad en stock'),
  },
  async ({ sku, quantity }) => {
    const result = await updateProductStock(sku, quantity);

    return {
      content: [
        {
          type: 'text',
          text: result.success
            ? `Stock actualizado correctamente: ${result.message}`
            : `Error al actualizar: ${result.message}`,
        },
      ],
    };
  }
);

// Resource: documentación de la API
server.resource(
  'api-docs',
  'docs://product-api',
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        text: `# Product Catalog API\n\nEndpoints disponibles:\n- GET /products — lista productos con filtros\n- PATCH /products/:sku/stock — actualiza stock\n\nAutenticación: header X-API-Key requerido en todas las llamadas.`,
      },
    ],
  })
);

// Arrancar con transport stdio
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('Product Catalog MCP server running on stdio');

Estructura de proyecto recomendada para un MCP server en producción#

Después de varios proyectos, esta es la estructura que recomiendo. Separa claramente la lógica de negocio del protocolo MCP para que puedas testear cada capa de forma independiente.

TypeScript

// src/server.ts — punto de entrada, solo protocolo
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { registerProductTools } from './tools/product.tools.js';
import { registerProductResources } from './resources/product.resources.js';
import { logger } from './lib/logger.js';

const server = new McpServer({
  name: 'product-catalog-mcp',
  version: process.env.npm_package_version ?? '1.0.0',
});

registerProductTools(server);
registerProductResources(server);

const transport = new StdioServerTransport();
await server.connect(transport);
logger.info('MCP server ready');

// src/tools/product.tools.ts — tools puras, testeables
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { ProductService } from '../services/product.service.js';

const productService = new ProductService();

export function registerProductTools(server: McpServer): void {
  server.tool(
    'search_products',
    'Busca productos en el catálogo',
    {
      sku: z.string().optional(),
      status: z.enum(['active', 'disabled', 'out_of_stock']).optional(),
      limit: z.number().int().min(1).max(100).default(10),
    },
    async (params) => {
      const products = await productService.search(params);
      return { content: [{ type: 'text', text: JSON.stringify(products) }] };
    }
  );
}

// src/services/product.service.ts — lógica de negocio pura
export class ProductService {
  private readonly baseUrl: string;
  private readonly apiKey: string;

  constructor() {
    this.baseUrl = process.env.API_BASE_URL ?? '';
    this.apiKey = process.env.API_KEY ?? '';

    if (!this.baseUrl || !this.apiKey) {
      throw new Error('API_BASE_URL y API_KEY son obligatorias');
    }
  }

  async search(filters: {
    sku?: string;
    status?: string;
    limit?: number;
  }) {
    const params = new URLSearchParams(
      Object.entries(filters)
        .filter(([, v]) => v !== undefined)
        .map(([k, v]) => [k, String(v)])
    );

    const res = await fetch(`${this.baseUrl}/products?${params}`, {
      headers: { 'X-API-Key': this.apiKey },
    });

    if (!res.ok) throw new Error(`API ${res.status}: ${res.statusText}`);
    return res.json();
  }
}

Model Context Protocol (MCP): el estándar que conecta los agentes de IA con el mundo real

También te puede interesar

Tutoriales cada dos semanas

Hablemos

El problema: los LLMs están ciegos sin contexto externo#

Qué es el Model Context Protocol y por qué la industria lo está adoptando#

Flujo de llamada end-to-end#

MCP vs REST vs GraphQL: cuándo usar cada uno#

MCP en producción: lecciones reales desde mcp-canva#

Anatomía de un MCP server en TypeScript#

Conectar Claude a tu API en minutos#

Debugging con MCP Inspector#

Implementación completa del servidor MCP#

Tabla de decisión: cuándo usar cada protocolo#

Estructura de proyecto recomendada para un MCP server en producción#

Configuración del cliente Claude#