Servidores MCP: herramientas, recursos, prompts y transporte

Un equipo de datos escribió un servidor MCP (MCP server) con consultas de solo lectura sobre su almacén de métricas. Cada ingeniero lo corre en su máquina, lanzado por Claude Code. Ahora lo quieren usar un chatbot en la nube, analistas con Claude Desktop y un agente del Agent SDK, y las credenciales del almacén no pueden salir del servidor. Para resolverlo hay que entender dos cosas: qué expone el servidor y por dónde se comunica.

Las piezas

• Host: la aplicación con la que trabaja la persona o el agente (Claude Code, Claude Desktop, tu app).
• Cliente: el componente del host que mantiene la conexión con un servidor.
• Servidor: el programa que expone capacidades. Se escribe con los SDK oficiales (Python, TypeScript y otros) y habla JSON-RPC.

Tres primitivas, tres dueños

La pregunta para elegir la primitiva es quién decide cuándo se usa:

Primitiva	Quién la controla	Para qué
Herramientas	El modelo	Acciones y consultas que Claude decide hacer durante la conversación: buscar contratos, crear un borrador
Recursos (resources)	La aplicación	Contexto de solo lectura identificado por una URI, que el host muestra, elige y adjunta: una biblioteca de cláusulas, un esquema de base de datos
Prompts de MCP (MCP prompts)	El usuario	Plantillas con argumentos que la persona invoca a propósito, por ejemplo como comando de barra: “Revisar un NDA” con contraparte y jurisdicción

Los recursos pueden ser fijos o plantillas de URI con parámetros (clausulas://{tipo}). Las herramientas de MCP siguen las mismas reglas de diseño que cualquier herramienta: descripciones claras y errores con isError y un mensaje útil.

Transporte: local o remoto

Transporte stdio (stdio transport):

• el host lanza el servidor como subproceso y se comunican por la entrada y la salida estándar;
• es para un servidor local, de una persona, en su máquina;
• por stdout solo pueden salir mensajes del protocolo: un print de depuración rompe la conexión, y los logs van a stderr.

HTTP transmisible (Streamable HTTP):

• el servidor es un proceso independiente que atiende a muchos clientes en un único endpoint (POST y GET), con SSE opcional para mandar varios mensajes;
• reemplazó al transporte HTTP+SSE de las primeras versiones del protocolo;
• es para un servidor remoto compartido: se despliega, se actualiza y se monitorea en un solo lugar;
• requiere autenticación (se recomienda OAuth para servidores remotos), validar el encabezado Origin y, si corre local, escuchar solo en localhost.

En el caso del almacén, la salida es un servidor remoto con Streamable HTTP y autenticación por usuario, con las credenciales del almacén del lado del servidor. Repartir un paquete stdio para que cada grupo lo corra con sus propias claves multiplica las credenciales y las versiones.

Integrarlo

• Claude Code: se agrega con claude mcp add o en un .mcp.json en el repositorio para compartirlo con el equipo; sus herramientas aparecen como mcp__<servidor>__<herramienta> y se controlan con los mismos permisos.
• Claude Desktop y claude.ai: como conector.
• Agent SDK: en la configuración de servidores MCP del agente.
• API de mensajes: con el conector MCP, que se conecta a servidores remotos.

Las trampas típicas

• Exponer como herramienta algo que es material de referencia que la app debería adjuntar, o como recurso un flujo que el usuario tiene que iniciar.
• Escribir logs por stdout en un servidor stdio.
• Distribuir copias locales con credenciales a cada equipo en lugar de un servidor remoto.
• Un servidor remoto sin autenticación, o escuchando en todas las interfaces en una máquina local.
• Pasar las credenciales del sistema de fondo a los clientes.

En el examen

Para las primitivas, preguntá quién decide: el modelo (herramienta), la aplicación (recurso) o el usuario (prompt). Para el transporte, preguntá cuántos lo usan y dónde corre: una persona en su máquina, stdio; varias aplicaciones contra un despliegue único, Streamable HTTP con autenticación y credenciales en el servidor.