# Agentes de IA

A Fonteza foi feita para ser usada por agentes. O mesmo dado chega por três portas, com a mesma chave e a mesma cota.

| Seu agente | Use |
| --- | --- |
| Consulta dados durante uma conversa ou tarefa | [MCP remoto](#mcp-remoto) |
| Escreve código que integra a API | [Documentação em Markdown](#documentacao-para-llms) e [instruções para agentes de código](#instrucoes-para-agentes-de-codigo) |
| Gera ferramentas de function calling a partir de um contrato | [`/openapi.yaml`](https://fonteza.com.br/openapi.yaml) |

## MCP remoto

| | |
| --- | --- |
| Endpoint | `https://fonteza.com.br/mcp` |
| Transporte | Streamable HTTP |
| Autenticação | `Authorization: Bearer fk_...`, com uma chave criada no [painel](https://fonteza.com.br/app/login). Sem OAuth. |
| Modelo | Por sua conta: a Fonteza fornece os dados, não o modelo. |

### Instalar

Claude Code:

```bash
claude mcp add --transport http fonteza https://fonteza.com.br/mcp \
  --header "Authorization: Bearer $FONTEZA_KEY"
```

Cursor · `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "fonteza": {
      "url": "https://fonteza.com.br/mcp",
      "headers": { "Authorization": "Bearer ${env:FONTEZA_KEY}" }
    }
  }
}
```

VS Code · `.vscode/mcp.json`:

```json
{
  "inputs": [
    { "type": "promptString", "id": "fonteza-key", "description": "Chave da Fonteza (fk_...)", "password": true }
  ],
  "servers": {
    "fonteza": {
      "type": "http",
      "url": "https://fonteza.com.br/mcp",
      "headers": { "Authorization": "Bearer ${input:fonteza-key}" }
    }
  }
}
```

Codex · `~/.codex/config.toml`:

```toml
[mcp_servers.fonteza]
url = "https://fonteza.com.br/mcp"
bearer_token_env_var = "FONTEZA_KEY"
```

Claude Desktop · `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fonteza": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://fonteza.com.br/mcp", "--header", "Authorization:${FONTEZA_AUTH}"],
      "env": { "FONTEZA_AUTH": "Bearer fk_..." }
    }
  }
}
```

OpenAI Agents:

```json
{
  "type": "mcp",
  "server_label": "fonteza",
  "transport": {
    "type": "http",
    "server_url": "https://fonteza.com.br/mcp",
    "authorization": "Bearer <FONTEZA_API_KEY>"
  },
  "connection_origin": "service",
  "required": true
}
```

O Claude Desktop conecta por meio do proxy `mcp-remote`, que requer Node.js. Testados por nós em produção: Claude Code e OpenAI Agents. As demais configurações seguem a documentação de cada cliente; outros clientes de MCP remoto que enviem um header personalizado devem funcionar.

### Ferramentas

| Ferramenta | O que faz | Equivalente REST |
| --- | --- | --- |
| `descobrir_cobertura` | Fontes publicadas, período, cobertura, limitações e o aviso operacional vigente. Não consome cota. | [`/v1/meta`](https://fonteza.com.br/docs/referencia/meta.md) |
| `buscar_empresas` | Busca por nome, atividade ou só pelo código CNAE, com os filtros da API. Cada item traz telefone e e-mail cadastrais. Até 50 por chamada. | [`/v1/buscar`](https://fonteza.com.br/docs/referencia/buscar.md) |
| `obter_empresa` | Cadastro e sócios de um CNPJ. | [`/v1/empresas/{cnpj}`](https://fonteza.com.br/docs/referencia/empresas-cnpj.md) |
| `buscar_oportunidades` | Oportunidades do PNCP por palavras, UF, município, modalidade, status e prazo. Até 50, com cursor. | [`/v1/oportunidades`](https://fonteza.com.br/docs/referencia/oportunidades.md) |
| `despesas_federais_da_empresa` | Empenhos, liquidações e pagamentos de um CNPJ. Até 50, com cursor. | [`/v1/empresas/{cnpj}/despesas-federais`](https://fonteza.com.br/docs/referencia/empresas-cnpj-despesas-federais.md) |

Os argumentos de cada ferramenta chegam ao agente pela listagem do próprio MCP. Enquanto houver um aviso operacional, como manutenção ou carga em andamento, toda resposta o traz em `meta.aviso`.

### Cota no MCP

- Só chamadas bem-sucedidas a ferramentas de dados consomem cota, mesmo com resultado vazio.
- Listar ferramentas, `descobrir_cobertura`, argumentos inválidos, falhas, timeouts e cancelamentos não consomem.
- Após 20 falhas de autenticação em um minuto a partir do mesmo IP, o MCP responde `429` até a janela liberar.

## Documentação para LLMs

Toda esta documentação existe em Markdown, sem navegação nem HTML, para caber no contexto de um modelo.

| Endereço | Conteúdo |
| --- | --- |
| [`/llms.txt`](https://fonteza.com.br/llms.txt) | Índice no formato llms.txt: fatos essenciais e links para cada página. |
| [`/llms-full.txt`](https://fonteza.com.br/llms-full.txt) | Todos os guias e a referência de todas as rotas em um único arquivo. |
| `/docs/<página>.md` | Qualquer página em Markdown. Ex.: [`/docs/referencia/buscar.md`](https://fonteza.com.br/docs/referencia/buscar.md.md). |
| `Accept: text/markdown` | O endereço normal da página responde Markdown quando o cliente pede. |

```bash
curl https://fonteza.com.br/docs/paginacao.md
curl -H "Accept: text/markdown" https://fonteza.com.br/docs/erros
```

Em cada página, **Copiar Markdown** leva o conteúdo para a área de transferência, e **Abrir no Claude** ou **Abrir no ChatGPT** inicia uma conversa que já lê a página.

## Instruções para agentes de código

Cole no `AGENTS.md`, `CLAUDE.md` ou nas regras do Cursor do seu projeto:

AGENTS.md:

```markdown
## API Fonteza
- Documentação completa para LLMs: https://fonteza.com.br/llms-full.txt
- Contrato: https://fonteza.com.br/openapi.yaml
- URL base: https://api.fonteza.com.br. Só GET, JSON. Header X-Api-Key lido de FONTEZA_KEY; nunca escreva a chave no código, em logs ou no front-end.
- Trate erros pelo campo `codigo` (em `detail.codigo` ou na raiz do corpo), nunca pelo texto da mensagem.
- Toda chamada com chave válida conta na cota diária, inclusive erros. Em 429, pare: não há Retry-After e repetir também conta.
- /v1/buscar pagina por offset e só devolve CNPJs ativos. Oportunidades e despesas paginam por `next_cursor`; em 409 geracao_*_expirada, recomece sem cursor.
- Nenhum resultado não quer dizer que não existe: a busca cobre só o recorte publicado. Consulte /v1/meta (gratuito) para cobertura e guarde `meta.snapshot_id` junto com o dado.
```

## Segurança

- Uma chave por agente ou ambiente, guardada em um gerenciador de segredos. Revogar uma não derruba as outras.
- Nunca coloque a chave em prompts, definições de agente compartilhadas, arquivos versionados ou logs.
- Se a chave vazar, revogue no [painel](https://fonteza.com.br/app/login) e crie outra; a revogação vale na requisição seguinte.