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:

“Liste os clientes mais recentes da minha empresa”
“Mostre meu saldo de pontos para este cliente”
“Gere um cupom para este cliente”
“Resuma as métricas gerais da operação”

Requisitos

Para usar o MCP público do IndiqAI, você precisa de:

Uma API Key ativa com acesso à API pública
Um ambiente seguro para armazenar essa chave (backend, worker ou cliente MCP com segredo local)
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:

cadastrar um servidor MCP remoto por URL
usar transporte HTTP com type: "http"
enviar X-API-Key ou Authorization: Bearer ... com segurança
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:

confirme que a API Key está correta
confirme que a conta possui acesso à API pública
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:

confirme que o cliente está apontando para https://api.indiqai.com/mcp
confirme que a API Key está chegando em X-API-Key ou Authorization
confirme que a key tem api_access e o scope esperado
confirme que o cliente suporta MCP remoto HTTP

Limite excedido

Se você receber 429:

respeite Retry-After
reutilize X-Idempotency-Key nos 3 writes críticos
reduza polling e prefira agrupar leituras quando possível

Erros mais comuns

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

Comece aqui

Clientes

Cupons

Produtos

Cartões Fidelidade

Indicações

Quests Públicas

NFC-e

Email

Pontos

Métricas

Prêmios

Usando o MCP do IndiqAI

Usando o MCP do IndiqAI

Visão geral

Requisitos

Conectando ao MCP do IndiqAI

Endpoint MCP remoto

Base HTTP pública

Autenticação

Fluxo MCP suportado

Listando as tools disponíveis

Usando com Claude Code, GitHub Copilot e Codex

Usando com outros clientes MCP

Padrões de resposta

Lista paginada

Lista simples

Objeto de retorno

Idempotência

Segurança e isolamento por empresa

Semântica importante de fidelidade

O que fica fora do catálogo autenticado

Troubleshooting

Falha de autenticação

A tool não aparece no cliente MCP

Limite excedido

Erros mais comuns

Recursos

​Usando o MCP do IndiqAI

​Visão geral

​Requisitos

​Conectando ao MCP do IndiqAI

​Endpoint MCP remoto

​Base HTTP pública

​Autenticação

​Fluxo MCP suportado

​Listando as tools disponíveis

​Usando com Claude Code, GitHub Copilot e Codex

​Usando com outros clientes MCP

​Padrões de resposta

​Lista paginada

​Lista simples

​Objeto de retorno

​Idempotência

​Segurança e isolamento por empresa

​Semântica importante de fidelidade

​O que fica fora do catálogo autenticado

​Troubleshooting

​Falha de autenticação

​A tool não aparece no cliente MCP

​Limite excedido

​Erros mais comuns

​Recursos

Usando o MCP do IndiqAI

Visão geral

Requisitos

Conectando ao MCP do IndiqAI

Endpoint MCP remoto

Base HTTP pública

Autenticação

Fluxo MCP suportado

Listando as tools disponíveis

Usando com Claude Code, GitHub Copilot e Codex

Usando com outros clientes MCP

Padrões de resposta

Lista paginada

Lista simples

Objeto de retorno

Idempotência

Segurança e isolamento por empresa

Semântica importante de fidelidade

O que fica fora do catálogo autenticado

Troubleshooting

Falha de autenticação

A tool não aparece no cliente MCP

Limite excedido

Erros mais comuns

Recursos