> ## 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

> Visão geral, requisitos, conexão, troubleshooting e recursos do MCP público do IndiqAI

# 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:

```text theme={null}
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:

```text theme={null}
https://api.indiqai.com/api/v1/public
```

<Tip>
  Se o seu cliente já suporta MCP remoto, use `/mcp`. Se você quer só chamadas HTTP tradicionais, use `/api/v1/public`.
</Tip>

## 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

<Warning>
  Nunca exponha sua API Key em frontend, app mobile, extensão distribuída ao usuário final ou repositório público.
</Warning>

## Conectando ao MCP do IndiqAI

### Endpoint MCP remoto

Todas as chamadas MCP vivem em:

```text theme={null}
https://api.indiqai.com/mcp
```

### Base HTTP pública

Todas as rotas documentadas aqui vivem sob:

```text theme={null}
https://api.indiqai.com/api/v1/public
```

### Autenticação

```http theme={null}
X-API-Key: indiqai_sua_chave_aqui
```

Clientes que só suportam `Authorization` também podem enviar:

```http theme={null}
Authorization: Bearer indiqai_sua_chave_aqui
```

<Warning>
  Envie apenas um dos headers. Se `Authorization` e `X-API-Key` vierem juntos com valores conflitantes, o servidor retorna `400`.
</Warning>

## 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](/api-reference/public-api/tools-catalog).

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](/api-reference/public-api/agent-integrations).

### 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`:

```json theme={null}
{
  "data": [],
  "total": 0,
  "page": 1,
  "pages": 1,
  "per_page": 20
}
```

### Lista simples

Usada em tools como `GET /products`, `GET /rewards` e `GET /loyalty-cards`:

```json theme={null}
[
  {}
]
```

### Objeto de retorno

Usado em writes e consultas individuais:

```json theme={null}
{
  "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:

```text theme={null}
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

| 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                                      |

## Recursos

* [Introdução](/api-reference/public-api/intro)
* [Autenticação](/api-reference/public-api/authentication)
* [Conectando clientes MCP ao IndiqAI](/api-reference/public-api/agent-integrations)
* [Catálogo de tools](/api-reference/public-api/tools-catalog)
* [Rate Limits](/api-reference/public-api/rate-limits)
* [Erros](/api-reference/public-api/errors)