Recaudo Docs
Criar conta

MCP e agentes

Ferramentas dos agentes

Conecte os agentes de inteligência artificial aos seus próprios sistemas

Uma ferramenta de API é uma chamada que seus agentes de inteligência artificial fazem ao seu sistema (ERP, CRM, qualquer API REST) durante a conversa, pelo WhatsApp ou por telefone. Por exemplo: o cliente pede o extrato e o agente o consulta no seu ERP. Depois de criá-la, habilite-a no agente.

GET /v1/ai-tools Listar ferramentas
POST /v1/ai-tools Criar ferramenta
GET /v1/ai-tools/{id} Ver ferramenta (sem o segredo)
PATCH /v1/ai-tools/{id} Atualizar os campos enviados
DELETE /v1/ai-tools/{id} Excluir e remover dos agentes
POST /v1/ai-tools/{id}/test Testar com um cliente real

Criar uma ferramenta

Exemplo de requisição 
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
  }'

Variáveis

{{customer.*}}, {{invoice.*}} e {{installment.*}} (a dívida em cobrança), {{tenant.id}}, {{conversation.id}} e {{now}} são preenchidas pelo Recaudo; o agente não pode alterá-las. {{params.x}} são os dados que o agente obtém da conversa.

Segurança

Apenas URLs HTTPS públicas: redes privadas, redirecionamentos e respostas acima de 512 KB são bloqueados.

Segredos

O campo secret é somente escrita: armazenado criptografado, nunca retornado e nunca visto pelo agente.

Habilitar em um agente

Adicione o code da ferramenta em tools_enabled do agente. Funciona igual em agentes de texto e de voz (OpenAI Realtime e ElevenLabs).

Testar

Executa a ferramenta com um cliente real. Retorna o que o agente receberia, a requisição enviada (sem segredos), o status HTTP e a duração.

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

Se o seu sistema tem um servidor MCP (transporte Streamable HTTP), conecte-o e o Recaudo lê as ferramentas dele: cada uma aparece com o código mcp_{servidor}_{ferramenta} e é habilitada no agente como qualquer outra. As que o servidor marca como somente leitura (readOnlyHint) rodam no testador; as demais são simuladas.

GET /v1/ai-mcp-servers Listar servidores e suas ferramentas
POST /v1/ai-mcp-servers Conectar e ler ferramentas
GET /v1/ai-mcp-servers/{id} Ver servidor (sem o segredo)
PATCH /v1/ai-mcp-servers/{id} Atualizar e ler novamente
POST /v1/ai-mcp-servers/{id}/sync Ler ferramentas novamente
DELETE /v1/ai-mcp-servers/{id} Excluir e remover dos 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"}'
Esta página ajudou? Obrigado por avisar.
Esc