Vapi client MCP

Un servidor MCP stdio local para aprovisionar asistentes de respuesta entrante de Vapi a nivel de cliente. Envuelve la API REST de Vapi en lugar del conjunto de herramientas MCP de Vapi alojado más pequeño.

La primera plantilla responde de inmediato, se identifica como IA, captura el nombre del llamante, el número de devolución de llamada, el motivo y la ventana de devolución de llamada, y luego ofrece una transferencia disponible o una devolución de llamada claramente explicada. Los datos de fin de llamada pueden ir a un webhook público o permanecer en Vapi para su posterior gestión en el CRM.

Qué está implementado

Los registros de clientes viven en clients/<slug>.json. Contienen IDs de recursos de Vapi y configuración empresarial no secreta, nunca la clave de Vapi ni credenciales de proveedor. Estos archivos JSON son adecuados para configuración como código si los metadatos empresariales en sí son aceptables para hacer commit.

Related MCP server: RetellAI MCP Server

Instalación y ejecución

Requiere Node.js 20 o superior.

cd /home/blaine/projects/vapi-mcp
npm install
npm run check
npm run build
export VAPI_API_KEY="your private server-side Vapi key"
npm start

El servidor habla MCP sobre stdio, por lo que su salida estándar está reservada para mensajes de protocolo. Los registros van a la salida de error estándar.

Para un host MCP, copie examples/mcp-client.json, reemplace las rutas absolutas y ponga la clave real solo en la configuración privada del host o en el gestor de secretos. El ejemplo incluido y .env.example contienen solo marcadores de posición. Este proyecto no carga automáticamente archivos .env.

Flujo de trabajo del primer cliente

Llame a las herramientas en este orden:

1. provision_client

2. set_structured_outputs

3. attach_phone

4. attach_tools para acciones de transferencia, devolución de llamada, calendario o CRM

5. smoke_test_call

6. list_client_status

Ejemplo de argumentos de provision_client:

{
  "clientSlug": "acme-hvac",
  "businessName": "Acme HVAC",
  "trade": "HVAC",
  "timezone": "America/New_York",
  "businessHours": "Monday-Friday 08:00-17:00; closed federal holidays",
  "transferNumber": "+12125550123",
  "crm": "GoHighLevel",
  "webhookUrl": "https://example.com/webhooks/vapi/end-of-call"
}

Sin outputDefinitions, set_structured_outputs instala el esquema de templates/inbound-answering.json. Extrae:

• callerName

• callbackNumber

• reason

• callbackWindow

• transferOutcome

• complete

Vincular un número existente:

{
  "clientSlug": "acme-hvac",
  "phoneNumberId": "00000000-0000-4000-8000-000000000000"
}

O pase un cuerpo POST /phone-number específico del proveedor como phoneConfiguration. El servidor sobrescribe cualquier assistantId proporcionado con el ID de asistente del cliente. Prefiera los IDs de credenciales de Vapi sobre los secretos sin procesar de Twilio, Telnyx, Vonage o SIP; los argumentos MCP transitorios no se escriben en el registro del cliente.

attach_tools acepta definiciones completas de POST /tool de Vapi, UUIDs de herramientas existentes, o ambos. Esto preserva intencionalmente las uniones de herramientas específicas del proveedor de Vapi en lugar de inventar un esquema local más restringido. Se requiere una respuesta exitosa de la herramienta Vapi antes de adjuntar su ID al asistente.

Ruta de prueba de humo

smoke_test_call crea una llamada telefónica saliente real y puede incurrir en cargos de Vapi y del operador. No se ejecutará a menos que confirmBillableCall sea exactamente true.

{
  "clientSlug": "acme-hvac",
  "customerNumber": "+12125550999",
  "waitSeconds": 45,
  "confirmBillableCall": true
}

Con waitSeconds: 0, la herramienta devuelve la llamada en cola inmediatamente. Entre 1 y 55 segundos, sondea GET /call/:id y devuelve el estado actual, el motivo de finalización, la transcripción y los datos estructurados cuando estén disponibles. Pruebe solo números que esté autorizado a llamar y siga las reglas aplicables de llamadas, consentimiento de grabación y privacidad.

Comportamiento y límites de la plantilla

La plantilla utiliza un mensaje primero del asistente para que la divulgación sea inmediata. El prompt utiliza enrutamiento de intención hablada y le dice al modelo que no afirme que una transferencia, reserva, devolución de llamada o escritura en CRM tuvo éxito sin confirmación de la herramienta. Cuando el estado abierto/cerrado es incierto, captura una devolución de llamada en lugar de adivinar.

Las horas incluidas son contexto del prompt, no un motor determinista de festivos/calendario. La ejecución real de transferencias y devoluciones de llamada requiere herramientas Vapi adjuntas. Un webhook debe ser público y capaz de aceptar cargas útiles de end-of-call-report de Vapi. Para negocios regulados, agregue los controles requeridos de consentimiento de grabación, retención y asesoramiento profesional antes de producción.

Verificación

npm run check

Las pruebas enfocadas enumeran las ocho herramientas MCP, inspeccionan el contrato de la plantilla, ejercitan el flujo de trabajo REST contra un cliente Vapi simulado y verifican la redacción de la clave de portador. No realizan una llamada real a Vapi porque no se incluye ninguna clave privada, número aprovisionado o destino consentido en este repositorio.

Fuentes

Los contratos de implementación siguen la documentación oficial actual de Vapi para assistants, phone numbers, custom tools, structured outputs, calls y server events.