Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.indiqai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Usando o MCP do IndiqAI

No IndiqAI, o termo MCP descreve a superfície de tools consumível por integrações e agentes. O endpoint oficial do MCP remoto do IndiqAI está disponível em: 
https://api.indiqai.com/mcp
Ele usa JSON-RPC 2.0 sobre HTTP e pode ser consumido diretamente por clientes MCP que suportem servidor remoto com type: "http". Para integrações server-to-server que não usam MCP, a API HTTP pública continua disponível em: 
https://api.indiqai.com/api/v1/public
Se o seu cliente já suporta MCP remoto, use /mcp. Se você quer só chamadas HTTP tradicionais, use /api/v1/public.

​
Visão geral

Com o MCP público do IndiqAI, você pode:
  • listar e consultar clientes
  • creditar pontos e gerar cupons
  • consultar produtos, recompensas e métricas
  • operar programas de fidelidade e campanhas por tools previsíveis
  • conectar essas capacidades ao seu agente favorito
Para API Keys de empresa, o tools/list devolve o catálogo público documentado nesta seção. Chaves administrativas internas podem receber um catálogo diferente, mas esse escopo não faz parte da documentação pública. Exemplos de pedidos comuns:
  1. “Liste os clientes mais recentes da minha empresa”
  2. “Mostre meu saldo de pontos para este cliente”
  3. “Gere um cupom para este cliente”
  4. “Resuma as métricas gerais da operação”

​
Requisitos

Para usar o MCP público do IndiqAI, você precisa de:
  1. Uma API Key ativa com acesso à API pública
  2. Um ambiente seguro para armazenar essa chave (backend, worker ou cliente MCP com segredo local)
  3. Um cliente compatível:
  • um cliente MCP remoto com type: "http"; ou
  • chamadas HTTP diretas para a API pública
Nunca exponha sua API Key em frontend, app mobile, extensão distribuída ao usuário final ou repositório público.

​
Conectando ao MCP do IndiqAI

​
Endpoint MCP remoto

Todas as chamadas MCP vivem em: 
https://api.indiqai.com/mcp

​
Base HTTP pública

Todas as rotas documentadas aqui vivem sob: 
https://api.indiqai.com/api/v1/public

​
Autenticação

X-API-Key: indiqai_sua_chave_aqui
Clientes que só suportam Authorization também podem enviar: 
Authorization: Bearer indiqai_sua_chave_aqui
Envie apenas um dos headers. Se Authorization e X-API-Key vierem juntos com valores conflitantes, o servidor retorna 400.

​
Fluxo MCP suportado

O servidor remoto implementa o fluxo básico esperado por clientes MCP HTTP:
  • initialize
  • notifications/initialized
  • tools/list
  • tools/call
O catálogo retornado em tools/list é derivado dinamicamente da API key.

​
Listando as tools disponíveis

O catálogo público atual está em Catálogo de tools. Se você usa HTTP direto, esse catálogo é a referência principal para as rotas em /api/v1/public. Se você usa MCP remoto, o tools/list da sua sessão deve refletir esse catálogo quando a key for do escopo empresa.

​
Usando com Claude Code, GitHub Copilot e Codex

Temos um guia separado, passo a passo, para esses clientes em Conectando clientes MCP ao IndiqAI.

​
Usando com outros clientes MCP

Você também pode usar o MCP público do IndiqAI com outros clientes, desde que eles consigam:
  1. cadastrar um servidor MCP remoto por URL
  2. usar transporte HTTP com type: "http"
  3. enviar X-API-Key ou Authorization: Bearer ... com segurança
  4. respeitar os limites e retries do contrato público

​
Padrões de resposta

​
Lista paginada

Usada, por exemplo, em GET /clients: 
{
  "data": [],
  "total": 0,
  "page": 1,
  "pages": 1,
  "per_page": 20
}

​
Lista simples

Usada em tools como GET /products, GET /rewards e GET /loyalty-cards: 
[
  {}
]

​
Objeto de retorno

Usado em writes e consultas individuais: 
{
  "id": "uuid",
  "created_at": "2026-05-12T20:00:00+00:00"
}
O shape exato depende da tool.

​
Idempotência

Os writes críticos abaixo aceitam X-Idempotency-Key:
  • POST /points/credit
  • POST /coupons/generate
  • POST /loyalty-cards/{card_id}/stamp
Use a mesma chave quando houver retry de rede da mesma operação lógica.

​
Segurança e isolamento por empresa

Toda leitura e todo write autenticado rodam no contexto da empresa da API Key. Na prática, isso significa:
  • você não escolhe tenant manualmente
  • recursos de outra empresa não devem ser acessíveis
  • métricas, cupons, produtos e fidelidade sempre respeitam o contexto da chave

​
Semântica importante de fidelidade

Em POST /loyalty-cards/{card_id}/stamp, o card_id esperado hoje é o identificador do progresso retornado por: 
GET /loyalty-cards
Ou seja, o valor é o user_loyalty_progress.id, não o loyalty_cards.id.

​
O que fica fora do catálogo autenticado

Algumas rotas públicas desta documentação não fazem parte do catálogo autenticado, embora vivam sob a mesma base pública:
  • quests públicas de resposta/claim
  • tracking e opt-out público de email
Esses endpoints seguem o contrato da própria página e não herdam automaticamente as regras de X-API-Key.

​
Troubleshooting

​
Falha de autenticação

Se você receber 401 ou 403:
  1. confirme que a API Key está correta
  2. confirme que a conta possui acesso à API pública
  3. confirme que a chave está sendo enviada pelo ambiente servidor ou pelo adaptador, e não por código cliente

​
A tool não aparece no cliente MCP

Se você estiver usando um cliente MCP:
  1. confirme que o cliente está apontando para https://api.indiqai.com/mcp
  2. confirme que a API Key está chegando em X-API-Key ou Authorization
  3. confirme que a key tem api_access e o scope esperado
  4. confirme que o cliente suporta MCP remoto HTTP

​
Limite excedido

Se você receber 429:
  1. respeite Retry-After
  2. reutilize X-Idempotency-Key nos 3 writes críticos
  3. reduza polling e prefira agrupar leituras quando possível

​
Erros mais comuns

StatusCenário
401API Key inválida, revogada ou mal formatada
403conta sem acesso à API pública ou chave sem permissão para esta superfície
404recurso não pertence à empresa da key ou não existe
422header, query, path ou body inválidos
429limite global da API pública excedido

​
Recursos