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
Escreve código que integra a API	Documentação em Markdown e instruções para agentes de código
Gera ferramentas de function calling a partir de um contrato	`/openapi.yaml`

MCP remoto


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

Instalar

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

~/.cursor/mcp.json

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

.vscode/mcp.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/config.toml

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

claude_desktop_config.json

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

{
  "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`
`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`
`obter_empresa`	Cadastro e sócios de um CNPJ.	`/v1/empresas/{cnpj}`
`buscar_oportunidades`	Oportunidades do PNCP por palavras, UF, município, modalidade, status e prazo. Até 50, com cursor.	`/v1/oportunidades`
`despesas_federais_da_empresa`	Empenhos, liquidações e pagamentos de um CNPJ. Até 50, com cursor.	`/v1/empresas/{cnpj}/despesas-federais`

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`	Índice no formato llms.txt: fatos essenciais e links para cada página.
`/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`.
`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

## 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 e crie outra; a revogação vale na requisição seguinte.