Servidores MCP

Un servidor MCP (Model Context Protocol) es un endpoint que expone una o varias herramientas que la IA puede descubrir y usar en tiempo de ejecución. Te permite hacer evolucionar el conjunto de herramientas sin tocar la configuración del agente: añade una herramienta en tu servidor y la IA la verá en el próximo descubrimiento.

Qué es un servidor MCP

MCP es un protocolo abierto basado en JSON-RPC 2.0 sobre HTTP (Streamable HTTP). El servidor expone primitivas como tools/list y tools/call. yourang.ai llama a tu servidor al inicio de cada llamada para descubrir las herramientas, y luego las expone a la IA como funciones invocables. Cada invocación pasa por tu servidor, que ejecuta la lógica y responde.

Cómo se comunica la IA con el servidor MCP

1. 1

   Descubrimiento inicial

   Al iniciar la llamada, yourang.ai envía una petición tools/list a tu servidor MCP. El servidor responde con la lista de herramientas (nombre, descripción, esquema de parámetros). El descubrimiento no transporta datos de cliente: solo construye el catálogo de herramientas.

2. 2

   Sesión MCP

   La primera respuesta del servidor devuelve una cabecera Mcp-Session-Id. La reutilizamos en cada petición posterior (tools/list y tools/call) dentro de esa llamada vocal, para que tu servidor pueda mantener estado si lo necesita.

3. 3

   Exposición al agente

   Las herramientas descubiertas se entregan al modelo de IA como funciones invocables, junto a las predefinidas y los External Tools.

4. 4

   Invocación (tools/call)

   Cuando el modelo decide usar una herramienta MCP, yourang.ai llama a tools/call con nombre de herramienta + argumentos. Junto a los argumentos adjuntamos automáticamente un bloque _meta.caller con los metadatos de cliente que conocemos (ver sección a continuación).

5. 5

   Respuesta a la IA

   El contenido textual de la respuesta MCP se extrae de los bloques content[].text, se concatena y se devuelve al modelo como function output. La conversación continúa.

Payload JSON-RPC

Las dos peticiones que tu servidor recibirá son simples y estándar. El descubrimiento no transporta metadatos; la invocación sí.

{
 "jsonrpc": "2.0",
 "method": "tools/list",
 "params": {},
 "id": "<uuid>"
}

Metadatos de cliente enviados automáticamente

Cuando la IA invoca una herramienta, yourang.ai enriquece la petición con un bloque _meta.caller con el contexto de la llamada actual. Son campos estándar, rellenados con lo que ya sabemos del cliente en el momento de la llamada.

call_sid

UUID único de la llamada en curso. Útil para correlacionar tus logs del servidor MCP con el historial de llamadas en yourang.ai.

agent_id

UUID del agente de IA que invocó la herramienta. Úsalo si varios agentes comparten el mismo servidor MCP y debes diferenciar la lógica.

organization_id

UUID de la organización (tenant). Suele ser el primer filtro que aplicas en tu servidor: cada llamada pertenece a un único tenant.

phone

Número de teléfono del llamante en formato E.164 (p. ej. +34 612 345 678), cuando esté disponible.

name

Nombre del contacto, si ya lo tenemos en la agenda para ese número. Ausente si el llamante es desconocido.

email

Email del contacto, si está presente en la ficha de contacto en yourang.ai.

contact_id

UUID del contacto en yourang.ai si el número coincidió con un registro de la agenda. Úsalo para obtener más datos sin pasar por una búsqueda por teléfono.

Cómo configurar uno

1. 1

   Abre la configuración del agente

   /ai-agents → selecciona el agente → pestaña MCP.

2. 2

   Introduce URL y autenticación

   URL HTTPS del servidor MCP, método de autenticación (ninguna, Bearer, API key, cabeceras personalizadas).

3. 3

   Guarda y comprueba el descubrimiento

   El panel muestra el número de herramientas descubiertas la última vez y la marca temporal. Puedes forzar un nuevo descubrimiento con un clic.

4. 4

   Activa o desactiva herramientas individuales

   Aunque el servidor exponga 30 herramientas, puedes activar solo las 5 que necesitas para ese agente.

Autenticación y cabeceras

Cada petición MCP incluye siempre Content-Type y Accept estándar, además de la cabecera de autenticación configurada y un Mcp-Session-Id que reutilizamos en todas las peticiones de la misma sesión vocal.

# Sempre presenti
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Session-Id: <restituito dal server alla prima risposta>

# Auth (in base alla configurazione)
Authorization: Bearer <token>
# oppure
X-API-Key: <chiave>

Ninguna

Servidor público. Solo para pruebas o herramientas sin datos sensibles.

Bearer

Cabecera Authorization: Bearer <token> en cada petición.

API key

Cabecera HTTP a tu elección (p. ej. X-API-Key).

Cabeceras personalizadas

Combinaciones múltiples (p. ej. X-Tenant + X-Signature).

Cuándo preferir MCP vs External Tool

• Tienes muchas herramientas relacionadas. Un servidor MCP que expone 10 herramientas CRM (lookup, create, update, list, …) es más manejable que 10 External Tools separadas.
• Quieres hacer evolucionar el catálogo de herramientas. Añade herramientas en tu servidor sin tocar la configuración de yourang.ai: el próximo descubrimiento las detecta.
• Necesitas hablar con un único endpoint. Un External Tool es más ligero: menos sobrecarga, configuración directa.