kavilo
Iniciar sesión

Guía

Conectar tu propio servidor MCP

El agente normalmente responde desde lo que escribiste en el Context. Cuando la respuesta está en un sistema en vivo — un CRM, un servicio de inventario, una base de datos — puedes apuntarlo a un servidor MCP que tú ejecutes. El agente llama a ese servidor en el momento de la pregunta, usa lo que devuelve y sigue. Tu sistema de origen se queda en tu red; la petición de la herramienta y la respuesta cruzan a nuestro servicio alojado para esa conversación.

Hay dos maneras de hacerlo según cómo ejecutes kavilo:

  • Plan Enterprise alojado — configura un proveedor de contexto en el portal. Cuando el token firmado del visitante lleva una clave de contexto, el agente invoca una herramienta MCP antes de responder para que tu servidor pueda devolver datos específicos de ese visitante. Los visitantes sin esa clave omiten la llamada.
  • Autoalojado — añade uno o más servidores MCP a tools.mcpServers en tu config.json. Se convierten en herramientas que el agente puede invocar durante su razonamiento, igual que funcionan las herramientas nativas.

Enterprise alojado: proveedor de contexto

En el portal, abre la configuración de tu bot y baja hasta proveedor de contexto MCP. Configurarás cuatro cosas:

  • URL del endpoint — la dirección HTTP o HTTPS de tu servidor MCP. Debe ser alcanzable desde nuestra nube. Una dirección local o una IP privada no funcionará; usa un nombre de host público o un túnel (Cloudflare Tunnel, Tailscale Funnel, ngrok) durante el desarrollo.
  • Nombre de la herramienta — el nombre de la herramienta MCP a invocar. Es la herramienta que tu servidor expone; el nombre lo eliges tú.
  • Cabecera que lleva la clave del visitante (opcional) — el nombre de la cabecera usada para reenviar la clave de contexto opaca desde el token del visitante emitido por tu backend. Por defecto es X-Context-Key. La herramienta se invoca solo cuando ese token contiene una clave; los visitantes con clave pública omiten la llamada.
  • Cabecera y credencial de autenticación (opcional) — una cabecera y un valor estático que identifican a kavilo ante tu servidor, por ejemplo X-API-Key y un secreto que emites tú. Independiente de la clave de contexto: la credencial de autenticación identifica a quien llama, la clave de contexto identifica al visitante. La credencial es de solo escritura: tú la fijas y nosotros nunca la devolvemos.

Tras guardar, usa Test connection para verificar que el agente puede alcanzar tu servidor e invocar la herramienta. La prueba lista las herramientas que tu servidor expone; si la herramienta nombrada no está en esa lista, no estará disponible para el bot en tiempo de ejecución.

En tiempo de ejecución, un visitante con clave de contexto dispara la herramienta antes de la respuesta. Lo que devuelve se inyecta en el contexto del agente para ese turno. Si la llamada expira (cinco segundos por defecto) o devuelve un error, el agente continúa sin ella en lugar de negarse a responder: diseña tu herramienta para que responda rápido y se degrade bien.

La respuesta cruda de la herramienta no se añade al Context permanente del bot, pero los datos de ella pueden aparecer en la respuesta y, por tanto, en la conversación guardada y en la transcripción.

Autoalojado: tools.mcpServers

En config.json, añade cada servidor bajo tools.mcpServers. La clave es el alias; el agente ve herramientas llamadas mcp_<alias>_<tool>.

Un servidor HTTP:

"tools": { "mcpServers": { "inventory": { "url": "https://internal.example.com/mcp", "enabled": true } } }

Un proceso local (stdio):

"tools": { "mcpServers": { "crm": { "command": "npx", "args": ["-y", "@example/crm-mcp"], "env": { "CRM_API_KEY": "sk_…" }, "enabled": true } } }

El agente invoca estas herramientas por iniciativa propia durante el razonamiento, igual que invoca las herramientas integradas. También puedes fijar enabledTools para restringir qué herramientas de un servidor se exponen.

Los cambios en config.json entran en vigor en el siguiente kavilo start. El comando kavilo mcp ayuda a gestionar las entradas de servidor sin editar el archivo a mano.

Lo que sale de tu red

En el plan Enterprise alojado, la conversación, la petición MCP y la respuesta de la herramienta se procesan en nuestra nube. Tu sistema base se queda en tu red, pero la petición, el token firmado del visitante (opcional) y las filas u objetos devueltos cruzan la frontera. Si eso no es aceptable, autoaloja el agente y usa inferencia local para que ni la conversación ni los datos de las herramientas salgan.

Cómo acceder

El contexto MCP está disponible en el plan Enterprise. En planes inferiores, la configuración está oculta. Mejora tu plan o háblanos si quieres discutir la frontera de los datos antes de elegir un despliegue.