Recaudo Docs
Crear cuenta

MCP y agentes

Herramientas de los agentes

Conecta a los agentes de inteligencia artificial con tus propios sistemas

Una herramienta API es una llamada que tus agentes de inteligencia artificial hacen a tu sistema (ERP, CRM, cualquier API REST) en plena conversación, por WhatsApp o por teléfono. Por ejemplo: el cliente pide su estado de cuenta y el agente lo consulta en tu ERP. Después de crearla, habilítala en el agente.

GET /v1/ai-tools Listar herramientas
POST /v1/ai-tools Crear herramienta
GET /v1/ai-tools/{id} Ver herramienta (sin el secreto)
PATCH /v1/ai-tools/{id} Actualizar campos enviados
DELETE /v1/ai-tools/{id} Eliminar y quitar de los agentes
POST /v1/ai-tools/{id}/test Probar con un cliente real

Crear una herramienta

Ejemplo de petición 
curl -X POST https://recaudo.app/api/v1/ai-tools \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consultar estado de cuenta",
    "description": "Úsala cuando el cliente pida su estado de cuenta o saldo detallado.",
    "method": "GET",
    "url": "https://erp.tuempresa.com/api/clientes/{{customer.external_id}}/estado",
    "query": [{"key": "contrato", "value": "{{params.contrato}}"}],
    "auth_type": "bearer",
    "secret": "token_de_tu_erp",
    "parameters": [
      {"name": "contrato", "type": "string", "description": "Número de contrato que menciona el cliente", "required": false}
    ],
    "response_fields": ["data.saldo", "data.movimientos.*.fecha", "data.movimientos.*.monto", "data.pdf_url"],
    "timeout_seconds": 5
  }'

Variables

{{customer.*}}, {{invoice.*}} e {{installment.*}} (el adeudo en cobro), {{tenant.id}}, {{conversation.id}} y {{now}} las llena Recaudo; el agente no puede alterarlas. {{params.x}} son los datos que el agente obtiene de la conversación.

Seguridad

Solo URLs HTTPS públicas: se bloquean redes privadas, redirecciones y respuestas mayores a 512 KB.

Secretos

El campo secret es de solo escritura: se guarda cifrado, nunca se devuelve y el agente nunca lo ve.

Habilitar en un agente

Agrega el code de la herramienta a tools_enabled del agente. Funciona igual en agentes de texto y de voz (OpenAI Realtime y ElevenLabs).

Probar

Ejecuta la herramienta con un cliente real. Devuelve lo que recibiría el agente, la petición enviada (sin secretos), el estado HTTP y la duración.

curl -X POST https://recaudo.app/api/v1/ai-tools/{id}/test \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "uuid-del-cliente", "parameters": {"contrato": "A-1029"}}'

Servidores MCP

Si tu sistema tiene un servidor MCP (transporte Streamable HTTP), conéctalo y Recaudo leerá sus herramientas: cada una aparece con el código mcp_{servidor}_{herramienta} y se habilita en el agente como cualquier otra. Las que el servidor marca como solo lectura (readOnlyHint) corren en el probador; las demás se simulan.

GET /v1/ai-mcp-servers Listar servidores y sus herramientas
POST /v1/ai-mcp-servers Conectar y leer herramientas
GET /v1/ai-mcp-servers/{id} Ver servidor (sin el secreto)
PATCH /v1/ai-mcp-servers/{id} Actualizar y volver a leer
POST /v1/ai-mcp-servers/{id}/sync Volver a leer herramientas
DELETE /v1/ai-mcp-servers/{id} Eliminar y quitar de los agentes 
curl -X POST https://recaudo.app/api/v1/ai-mcp-servers \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "ERP", "url": "https://mcp.tuempresa.com/mcp", "auth_type": "bearer", "secret": "token_del_servidor"}'
¿Te sirvió esta página? Gracias por avisarnos.
Esc