Recaudo Docs
Sign up

MCP & agents

Agent tools

Connect artificial intelligence agents to your own systems

An API tool is a call your artificial intelligence agents make to your system (ERP, CRM, any REST API) during a conversation, on WhatsApp or by phone. For example: the customer asks for their account statement and the agent looks it up in your ERP. After creating it, enable it on the agent.

GET /v1/ai-tools List tools
POST /v1/ai-tools Create a tool
GET /v1/ai-tools/{id} Get a tool (without the secret)
PATCH /v1/ai-tools/{id} Update the fields sent
DELETE /v1/ai-tools/{id} Delete and remove from agents
POST /v1/ai-tools/{id}/test Test with a real customer

Create a tool

Request example 
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.*}} and {{installment.*}} (the debt being collected), {{tenant.id}}, {{conversation.id}} and {{now}} are filled by Recaudo; the agent cannot change them. {{params.x}} is data the agent gets from the conversation.

Security

Only public HTTPS URLs: private networks, redirects and responses over 512 KB are blocked.

Secrets

The secret field is write-only: stored encrypted, never returned and never seen by the agent.

Enable on an agent

Add the tool code to the agent tools_enabled. Works the same on text and voice agents (OpenAI Realtime and ElevenLabs).

Test

Runs the tool with a real customer. Returns what the agent would receive, the request sent (without secrets), the HTTP status and the duration.

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"}}'

MCP servers

If your system has an MCP server (Streamable HTTP transport), connect it and Recaudo reads its tools: each one shows up with the code mcp_{server}_{tool} and is enabled on the agent like any other. Tools the server marks as read-only (readOnlyHint) run in the tester; the rest are simulated.

GET /v1/ai-mcp-servers List servers and their tools
POST /v1/ai-mcp-servers Connect and read tools
GET /v1/ai-mcp-servers/{id} Get a server (without the secret)
PATCH /v1/ai-mcp-servers/{id} Update and read again
POST /v1/ai-mcp-servers/{id}/sync Read tools again
DELETE /v1/ai-mcp-servers/{id} Delete and remove from agents 
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"}'
Was this page helpful? Thanks for letting us know.
Esc