Documentação

API & MCP.

A conversa com o Tomé funciona por integração: pelo MCP (seção 2), no mesmo limite diário do site. E duas funções do Tomé Enterprise também: o Export por administradora (o consolidado dos fundos — FIDC, FII e FIF — em planilha, direto pro seu cruzamento, seção 3), com a chave de API tome_…; e a Planilha viva (DY real 12m, P/VP e PL de um FII direto no seu Google Sheets ou Excel, seção 5), com uma chave própria tomeplan_…. No seu pipeline interno, num script agendado ou direto de um agente de IA via MCP. Mesmo motor das interfaces, mesmos dados, mesmas regras.

Se o que você quer é usar o Tomé dentro do seu Claude, o caminho é outro e mais curto: não precisa de chave nenhuma — você cola o endereço nos conectores do Claude e entra com o e-mail da sua conta. O passo a passo está em agentetome.com/claude. As perguntas feitas por lá contam no mesmo limite diário do site.

O resto desta seção é para integração por chave — script, agente próprio ou qualquer cliente MCP genérico por HTTP. Com a chave, o cliente conversa com o Tomé pela tool perguntar_ao_tome (no mesmo limite diário do site); a tool exportar_admin (seção 3) é do Tomé Enterprise. Endpoint único, JSON-RPC 2.0:

POST https://www.agentetome.com/api/mcp
Authorization: Bearer tome_SUA_CHAVE
Content-Type: application/json

Métodos: initialize, tools/list e tools/call. A chamada de tools/call da tool exportar_admin e a sua resposta (em result.content[0].text) estão na seção 3. Exemplo de configuração num cliente MCP genérico por HTTP:

{
  "mcpServers": {
    "tome": {
      "url": "https://www.agentetome.com/api/mcp",
      "headers": { "Authorization": "Bearer tome_SUA_CHAVE" }
    }
  }
}

Recurso do Tomé Enterprise. A rota /api/v1/export/* e a tool exportar_admin atendem contas do Enterprise; numa conta do plano gratuito elas respondem 403 com o código PLANO_ENTERPRISE (tabela abaixo). No plano gratuito, as perguntas seguem abertas no chat.

O mesmo pacote da página /exportar, sem humano clicando em download: o consolidado dos fundos de uma administradora (1 linha por fundo×competência, chave de junção CNPJ de 14 dígitos como texto + competência YYYY-MM), satélites de classes e aging (FIDC) e a visão de qualidade operacional. Dado 100% público (CVM/FNET), schema versionado (v1: coluna não some nem renomeia; adição só no fim), célula vazia = não declarado.

curl -L -o export-ot.zip \
  -H "Authorization: Bearer tome_SUA_CHAVE" \
  "https://www.agentetome.com/api/v1/export/admin?admin=oliveira%20trust&formato=csv&corte=competencia&competencia=2026-06"

Resposta — o arquivo binário (Content-Disposition: attachment). O header X-Tome-Export-Cache: hit|miss conta se veio do cache do dia (repetir o mesmo pedido no mesmo dia não custa nada). O contrato do pacote — grafias que casaram, janela de dados, notas de método, contagem de linhas por arquivo — vai no manifest.json (dentro do ZIP) e também em endpoint próprio, útil pra checar antes de baixar (ou quando consome XLSX):

curl -H "Authorization: Bearer tome_SUA_CHAVE" \
  "https://www.agentetome.com/api/v1/export/admin/manifest?admin=oliveira%20trust&corte=recente"

No mesmo servidor MCP da seção 2 (mesmo endpoint, mesma chave). A tool recebe admin / corte / competencia / formato e devolve um link de download temporário (validade 1h) — nunca o binário dentro do JSON:

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "exportar_admin",
    "arguments": { "admin": "oliveira trust", "corte": "recente", "formato": "csv" }
  }
}

Resposta (em result.content[0].text):

{
  "arquivo": "tome-export-oliveira-trust-foto-atual-2026-07-22.zip",
  "formato": "zip_de_csvs",
  "tamanho_bytes": 118742,
  "link_download": "https://www.agentetome.com/api/export/download?t=eyJ…",
  "expira_em": "2026-07-22T18:40:00.000Z",
  "como_baixar": "GET simples no link (sem header de auth — a assinatura no token é a credencial; validade 1h).",
  "manifest": { "schema_versao": 1, "filtro": { … }, "arquivos": { … }, "notas_metodo": { … } }
}

O link é assinado (HMAC) e expira em 1 hora; qualquer um com o link baixa o arquivo dentro da validade — trate-o como o próprio arquivo. A geração conta no limite de 10/hora da chave; o download pelo link, não. Numa conta do plano gratuito a tool falha com {"erro":"plano_enterprise","mensagem":"…"} — a mensagem traz o link do Tomé Enterprise.

No export: a base cobre o que a CVM/FNET publica e o Tomé já ingeriu — fundo ausente aparece como ausência, e ausência também é informação. No corte recente os meses variam por fundo por design (a coluna competencia acompanha toda linha); dias_atraso usa régua aproximada declarada no manifest. Todo número carrega o informe_id de origem — nada é estimado, nada é preenchido.

Na planilha viva: os limites da chave tomeplan_… estão na tabela da seção 5 — cada teto explicado com o porquê, e as mensagens de erro exatamente como aparecem na célula da sua planilha.

Recurso do Tomé Enterprise. Numa conta do plano gratuito a fórmula devolve a célula do plano (tabela de erros abaixo). Enviar a planilha da sua carteira e acompanhá-la em Carteira continua gratuito, e a demonstração sem chave logo abaixo segue aberta.

O dado do Tomé DENTRO da sua planilha, atualizando sozinho: DY real 12 meses (soma dos rendimentos por cota em 12 meses fechados ÷ preço B3 — não o DY declarado), P/VP, PL e as flags de honestidade, tudo com fonte por linha. Zero raspagem de site: é a mesma base pública (CVM/FNET + B3 COTAHIST) do chat, servida em CSV por um SELECT.

=IMPORTDATA("https://www.agentetome.com/api/v1/ticker/XPML11.csv?chave=tomeplan_SUA_CHAVE&locale=br")

=IMPORTDATA("https://www.agentetome.com/api/v1/watchlist.csv?chave=tomeplan_SUA_CHAVE&locale=br")

locale=br: com ele o CSV sai com ; de separador e vírgula decimal — o formato que um Sheets/Excel em português entende como NÚMERO. Sem o parâmetro, o CSV é o padrão RFC (, + ponto decimal) — num Sheets pt-BR os números virariam texto (pegadinha clássica do IMPORTDATA). Excel: mesma URL em Dados → Da Web (ou =WEBSERVICE+Power Query) — funciona igual.

Quer ver funcionando antes de criar conta? Este endpoint é aberto e devolve 1 fundo fixo (XPML11), com dado real:

=IMPORTDATA("https://www.agentetome.com/api/v1/ticker/demo.csv?locale=br")

A chave vai na URL (?chave=tomeplan_…) — o IMPORTDATA não envia headers — ou, pra scripts, no header Authorization: Bearer tomeplan_…. A variante .json devolve os mesmos campos com status HTTP real (integração séria usa ela). Cache de 15 minutos do nosso lado (o dado muda 1×/dia); o Google ainda aplica um cache próprio de até ~1h no IMPORTDATA — a planilha pode levar até uma hora pra refletir o dado novo, por conta dele.

Colunas (contrato v1 — coluna não some nem renomeia; adição só no fim):

Célula vazia = valor não declarado — nunca inventamos 0. Nenhuma coluna de recomendação, nota ou score: a pré-análise é sua. Cobertura v1: FII (551 fundos com DY real na base) — FIDC/FIF/CRI-CRA na planilha viva ficam pra uma v2 com colunas próprias por classe.

Limites (e o porquê de cada um):

Varredura automatizada da base (muitos fundos em sequência alfabética) suspende a chave na hora — você reativa sozinho na sua conta na primeira vez. O seu uso do dia (requisições e fundos distintos) fica visível na conta, antes de qualquer limite bater.

Erros — legíveis na célula. As rotas .csv respondem HTTP 200 com uma única célula em português (o Sheets mostraria só "Error: resource at url…"); as rotas .json respondem o status real (401/403/404/429/503) com {codigo, mensagem}. As mensagens, exatamente como aparecem na planilha:

Uso próprio; redistribuição comercial do CSV é proibida. O dado é público e as perguntas sobre ele seguem abertas no chat do site — a fonte (fonte_informe_id, competencia_informe, pregao) viaja em cada linha.

Dúvidas ou um caso de uso que a API ainda não cobre? Pergunta pro Tomé no chat — as conversas são lidas por gente.