Cuando creas una función con define(), se expone automáticamente como una herramienta MCP (Model Context Protocol). Tus agentes IA pueden descubrir e invocar tu función como un tool sin configuración adicional.
import { define, z } from "@jelou/functions";export default define({ name: "consultar-saldo", description: "Consulta el saldo de un cliente por número de teléfono", input: z.object({ telefono: z.string().min(10).describe("Número de teléfono con código de país"), }), output: z.object({ nombre: z.string(), saldo: z.number(), moneda: z.string(), }), handler: async (input, ctx) => { ctx.log("Consultando saldo", { telefono: input.telefono }); return { nombre: "María García", saldo: 150.00, moneda: "USD" }; },});
El endpoint /mcp expone este esquema:
{ "name": "consultar-saldo", "description": "Consulta el saldo de un cliente por número de teléfono", "inputSchema": { "type": "object", "properties": { "telefono": { "type": "string", "minLength": 10, "description": "Número de teléfono con código de país" } }, "required": ["telefono"] }}
El campo description de tu define() es lo que el agente IA lee para decidir cuándo invocar tu herramienta. Si la descripción es vaga, el agente no sabrá cuándo usarla — o peor, la usará en el momento incorrecto.
❌ Vaga
✅ Específica
Por qué importa
"Maneja usuarios"
"Busca un usuario por email o teléfono y retorna su perfil con saldo"
El agente sabe exactamente qué datos puede obtener
"Envía mensaje"
"Envía un mensaje de WhatsApp a un número con código de país (ej: 593…)"
El agente sabe el canal y el formato esperado
"Consulta API"
"Consulta el estado de un envío por tracking number en la API de Servientrega"
El agente sabe para qué proveedor y qué dato necesita
Las anotaciones .describe() de Zod se convierten en descripciones de parámetros del tool MCP. Esto es lo que ven los agentes IA cuando descubren tu función:
input: z.object({ telefono: z.string().min(10).describe("Número con código de país, ej: 593987654321"), tipo: z.enum(["prepago", "pospago"]).describe("Tipo de plan del cliente"), incluirHistorial: z.boolean().default(false).describe("Si incluir las últimas 5 transacciones"),})
Escribe descripciones claras y específicas en .describe(). Los agentes IA usan estas descripciones para decidir qué valores pasar a tu función.
En producción, el endpoint /mcp requiere el header X-Jelou-Token. Sin token, recibirás 401 Unauthorized. Solo /__health y /openapi.json son públicos sin token.
Cuando usas app(), un solo servidor MCP en /mcp registra automáticamente todos los tools. Cada tool aparece como una herramienta independiente con su nombre, descripción y esquema.Para excluir un tool específico del registro MCP, usa mcp: false en su config:
