# Servidor MCP

O servidor MCP da PrismaData permite que assistentes de IA — Claude.ai, Claude Code, Cursor, VS Code e agentes próprios — usem as APIs PrismaData como ferramentas (*tools*). O assistente decide quando consultar; cada chamada de tool vira uma consulta à API REST, feita com a credencial da sua própria conta.

- **URL:** `https://mcp.prismadata.io`
- **Transporte:** Streamable HTTP (MCP), sem estado entre chamadas.
- **Respostas:** o mesmo JSON da API REST, sem alterações, inclusive os prefixos `prismadata__<serviço>__<campo>`.
- **Nenhum modelo de IA roda do lado da PrismaData:** o servidor só repassa a chamada para a API e devolve a resposta.

## Como conectar

### Claude.ai (conector)

1. Em **Configurações → Conectores**, adicione um conector personalizado com a URL `https://mcp.prismadata.io`.
2. Clique em **Conectar** e entre com o seu usuário e senha PrismaData.

A autorização usa OAuth: o Claude.ai nunca vê a sua senha nem a sua API key. Para revogar o acesso, desconecte o conector.

### Claude Code

Com login PrismaData (OAuth):

```bash
claude mcp add --transport http prismadata https://mcp.prismadata.io
```

Depois, rode `/mcp` no Claude Code e escolha **Authenticate**.

Ou com API key, lida de uma variável de ambiente para não ficar no histórico do shell:

```bash
claude mcp add --transport http prismadata https://mcp.prismadata.io \
  --header "X-Apikey: $PRISMADATA_API_KEY"
```

### Outros clientes MCP e agentes próprios

Qualquer cliente com transporte Streamable HTTP e headers personalizados usa a mesma URL, com o header `X-Apikey: <sua API key>`. Clientes com suporte a OAuth podem, em vez disso, fazer login PrismaData como no Claude.ai.

Exemplo com o Claude Agent SDK (Python):

```python
import os
from claude_agent_sdk import ClaudeAgentOptions, query

opcoes = ClaudeAgentOptions(
    mcp_servers={"prismadata": {
        "type": "http",
        "url": "https://mcp.prismadata.io",
        "headers": {"X-Apikey": os.environ["PRISMADATA_API_KEY"]},
    }},
    allowed_tools=["mcp__prismadata"],
)
async for mensagem in query(prompt="A Av. Paulista, 1000, São Paulo fica perto de uma favela?", options=opcoes):
    print(mensagem)
```

**No MCP, a credencial nunca vai na URL.** O servidor ignora credenciais na query string; use sempre um header (ou o login OAuth).

Sem credencial, o cliente ainda consegue listar as tools e ler a documentação (`documentacao`); as tools de dados respondem explicando como configurar a credencial.

## Tools

| Tool | Produto | Endpoint REST equivalente | Cobrança |
|------|---------|---------------------------|----------|
| `geocodificar_endereco` | [Geocoder](https://prismadata.io/llm/geocoder.md) | `GET /location/geocoder` | 1 consulta |
| `endereco_de_coordenada` | [Geocoder](https://prismadata.io/llm/geocoder.md) | `GET /location/reverse_geocoder` | 1 consulta |
| `exposicao_fronteira` | [Fronteiras](https://prismadata.io/llm/fronteiras.md) | `GET /location/border` | 1 consulta |
| `proximidade_favela` | [Favelas](https://prismadata.io/llm/favelas.md) | `GET /location/slum` | 1 consulta |
| `setor_censitario` | [InfoSC](https://prismadata.io/llm/infosc.md) | `GET /location/infosc` | 1 consulta |
| `renda_da_regiao` | [Renda](https://prismadata.io/llm/renda.md) | `GET /location/personal_income_static` | 1 consulta |
| `distribuicao_renda_da_regiao` | [Renda](https://prismadata.io/llm/renda.md) | `GET /location/personal_income_pdf` | 1 consulta |
| `proximidade_presidio` | [Prisões](https://prismadata.io/llm/prisoes.md) | `GET /location/prison` | 1 consulta |
| `tipologia_de_coordenada` | [Tipologia](https://prismadata.io/llm/tipologia.md) | `GET /location/tipologia` | 1 consulta |
| `tipologia_de_endereco` | [Tipologia](https://prismadata.io/llm/tipologia.md) | `GET /location/tipologia/endereco` | 1 consulta |
| `confere_endereco_coordenada` | [Validação de Endereços](https://prismadata.io/llm/validacao-de-enderecos.md) | `GET /location/addr_validation/compare_address` | 1 consulta |
| `consultar_cnpj` | [CNPJ](https://prismadata.io/llm/cnpj.md) | `GET /cnpj/{cnpj}` | 1 consulta |
| `historico_cnpj` | [CNPJ](https://prismadata.io/llm/cnpj.md) | `GET /cnpj/{cnpj}/historico` | 1 consulta |
| `historico_socios_cnpj` | [CNPJ](https://prismadata.io/llm/cnpj.md) | `GET /cnpj/{cnpj}/historico/socios` | 1 consulta |
| `cnpjs_no_endereco` | [CNPJ](https://prismadata.io/llm/cnpj.md) | `POST /cnpj/endereco/cnpjs` | 1 consulta |
| `aglomeracao_comercial` | [Aglomerações Comerciais](https://prismadata.io/llm/aglomeracoes-comerciais.md) | `GET /location/commercial_cluster` | 1 consulta |
| `informacoes_de_ip` | [Identity](https://prismadata.io/llm/identity.md) | `GET /identity/ipinfo` | 1 consulta |
| `rota_entre_pontos` | [Rotas](https://prismadata.io/llm/rotas.md) | `GET /routing/route` | 1 consulta |
| `consultar_creditos` | [Conta](https://prismadata.io/llm/conta.md) | `GET /account/credits` | Não cobrada |
| `extrato_debitos` | [Conta](https://prismadata.io/llm/conta.md) | `GET /account/credits/debits` | Não cobrada |
| `historico_chamadas` | [Conta](https://prismadata.io/llm/conta.md) | `GET /account/activities` | Não cobrada |
| `consumo_mes` | [Conta](https://prismadata.io/llm/conta.md) | `GET /account/consumption` | Não cobrada |

Além das tools de dados, o servidor tem:

- **Tools da conta** — `consultar_creditos`, `extrato_debitos`, `historico_chamadas` e `consumo_mes`: saldo e extrato dos créditos pré-pagos, histórico de chamadas e consumo do mês. Gratuitas.
- **`documentacao`** — devolve a documentação de um produto (significado dos campos, metodologia, armadilhas) e, opcionalmente, um guia geral (erros, rate limit, lote, créditos). Gratuita.

A documentação também está disponível como *Resources* MCP, para clientes que os leem.

Para endereços em texto, o assistente chama `geocodificar_endereco` primeiro e usa a coordenada nas tools de ponto. As tools de lote da API REST não estão no MCP: cada chamada de tool consulta um item.

## Cobrança

- Cada chamada de uma tool de dados é **1 consulta cobrada**, como a chamada equivalente na API REST. Em `cnpjs_no_endereco`, cada página é 1 consulta.
- As tools da conta e `documentacao` **não são cobradas**.
- Entradas inválidas (por exemplo, latitude fora de -90..90 ou CNPJ com dígito verificador errado) são recusadas pelo servidor MCP **antes** da consulta, sem cobrança.
- Erros não são cobrados (veja **Tratamento de Erros → Cobrança**).
- O consumo aparece no seu histórico de chamadas como as chamadas REST equivalentes.

## Limites

- O servidor MCP tem um limite próprio de requisições por minuto, por conta.
- Valem também a quota e o rate limit da sua conta, iguais aos da API REST (veja **Rate Limiting & Quota**).

## Erros

As tools devolvem erros como texto em português, explicando o que fazer, e não repassam o corpo bruto da API. Os mais comuns:

| Situação | O que fazer |
|---|---|
| Credencial ausente, inválida ou expirada | Com API key, confira o header `X-Apikey`; com login PrismaData, reconecte (refaça o login) no cliente |
| Sua conta não tem acesso a este produto | Fale com a PrismaData para habilitá-lo |
| Saldo pré-pago insuficiente | Nada foi cobrado; confira com `consultar_creditos` |
| Limite por minuto ou quota esgotada | Espere o horário indicado na mensagem |
| IP fora da rede autorizada | Veja **Contas com restrição de rede**, abaixo |
| Serviço temporariamente indisponível | O servidor já repetiu a chamada uma vez; tente de novo em alguns minutos |

### Contas com restrição de rede

Se a sua conta só aceita chamadas de redes autorizadas, o IP verificado é o de quem abre a conexão MCP. No Claude Code e em agentes próprios, é o IP da sua máquina ou servidor. No Claude.ai, é o IP dos servidores do Claude, não o do seu computador; nesse caso, use um cliente local ou peça ao administrador da conta para ajustar a restrição.

## Privacidade

O servidor MCP não guarda os parâmetros nem as respostas das consultas. Para operação e suporte, ele registra de cada chamada só a tool, o endpoint (sem os dados consultados), o status, a latência, o IP de origem e a conta que fez a chamada.

---

- Índice geral: https://prismadata.io/llms.txt
- Documentação Redoc interativa: https://prismadata.io/redoc.html