Tato · MCP para agentes

Canonical: https://tato.finance/agentes

A Tato é o financeiro de MEI e Simples Nacional. Pelo servidor MCP, um agente (Claude Code, Claude Desktop, claude.ai ou outro cliente MCP) cria cobranças com Pix, lança contas a pagar, cadastra clientes e lê a DRE da empresa de quem autorizou.

Resposta curta: conecte https://tato.finance/api/mcp, entre com o e-mail e a senha do cadastro da Tato, clique em Permitir e chame as quatro ferramentas. Cada acesso vale só para aquela conta.

Superfícies de descoberta

Superfície	Endereço	Para quê
Índice	https://tato.finance/llms.txt	Resumo curto para o agente
Pacote completo	https://tato.finance/llms-full.txt	Esta documentação inteira em Markdown
Descoberta	https://tato.finance/.well-known/tato.json	URLs, autenticação, ferramentas e limites em JSON
Esta página	https://tato.finance/agentes	HTML; com `Accept: text/markdown` devolve este Markdown na mesma URL
Servidor MCP	https://tato.finance/api/mcp	O produto: as quatro ferramentas, com OAuth

Claude Code

Precisa do Claude Code de linha de comando. Se o terminal disser que claude não é reconhecido, instale antes, abra o terminal de novo e rode claude uma vez para entrar:

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# macOS ou Linux
curl -fsSL https://claude.ai/install.sh | bash

Conecte a Tato:

claude mcp add --transport http --scope user tato https://tato.finance/api/mcp

Dentro do Claude Code, rode /mcp, escolha tato e Authenticate. O navegador abre o login da Tato: entre com o e-mail do cadastro e clique em Permitir. Conferir: claude mcp list. Remover: claude mcp remove tato.

Claude Desktop e claude.ai

Configurações → Conectores → Adicionar conector personalizado, nome Tato, URL https://tato.finance/api/mcp. Clique em Conectar e entre com o e-mail do cadastro. Na Tato, o mesmo passo a passo está em Configurações → Claude.

Primeira chamada verificada

initialize
  → tools/list            (4 ferramentas, cada uma com inputSchema e outputSchema)
  → ler_dre {}            (somente leitura: confirma que o acesso chega na conta certa)
  → criar_cobranca {...}  (primeira escrita)

Para conferir o token sem chamar ferramenta, um GET autenticado devolve o descritor da conexão (servidor, conta, limites e ferramentas):

curl -H "Authorization: Bearer $TOKEN" https://tato.finance/api/mcp

Ferramentas

Todas as respostas usam as mesmas colunas: id, descricao, valor (reais, número), vencimento (AAAA-MM-DD) e status. Cada ferramenta anuncia um outputSchema e devolve structuredContent junto do texto JSON. A lista viva em tools/list é a fonte da verdade.

`criar_cobranca`

Cria uma cobrança (conta a receber) com QR Pix na chave da empresa. Se o cliente não existir, cadastra pelo CNPJ/CPF (com CPF, informe cliente_nome).

Somente leitura: não.

Entrada

Campo	Tipo	Obrigatório	Descrição
`cliente_documento`	string	sim	CNPJ ou CPF do cliente (só números ou formatado).
`cliente_nome`	string	não	Nome do cliente; obrigatório para CPF novo.
`descricao`	string	sim	O que foi feito (até 140 caracteres).
`valor`	number	sim	Valor em reais, com até 2 casas (ex.: 1250.5). Máximo 50000.
`vencimento`	string	sim	Data no formato AAAA-MM-DD.

Saída (structuredContent.cobranca)

Campo	Tipo	Descrição
`id`	string	Identificador na Tato.
`descricao`	string	Descrição.
`valor`	number	Valor em reais.
`vencimento`	string	Vencimento, AAAA-MM-DD.
`status`	string	aberta, paga ou cancelada.
`cliente`	string	Nome do cliente.
`pix_copia_e_cola`	string ou null	Pix copia e cola; null sem chave Pix na conta.

`lancar_conta_pagar`

Lança uma conta a pagar (boleto, fatura, despesa). A Tato não paga nada: só registra e avisa no vencimento.

Somente leitura: não.

Entrada

Campo	Tipo	Obrigatório	Descrição
`descricao`	string	sim	Descrição (até 140 caracteres).
`valor`	number	sim	Valor em reais, com até 2 casas (ex.: 1250.5). Máximo 50000.
`vencimento`	string	sim	Data no formato AAAA-MM-DD.
`categoria`	string	não	Categoria da despesa. Valores: `aluguel`, `condominio`, `agua_luz_gas`, `internet_telefone`, `software_assinaturas`, `impostos_taxas`, `contador`, `salarios_prolabore`, `fornecedores_servicos`, `materiais`, `marketing`, `transporte`, `alimentacao`, `equipamentos`, `emprestimos_financiamentos`, `tarifas_bancarias`, `outros`.
`fornecedor`	string	não	Para quem é (opcional).

Saída (structuredContent.conta_pagar)

Campo	Tipo	Descrição
`id`	string	Identificador na Tato.
`descricao`	string	Descrição.
`valor`	number	Valor em reais.
`vencimento`	string	Vencimento, AAAA-MM-DD.
`status`	string	aberta, paga ou cancelada.
`categoria`	string	Categoria da despesa.
`fornecedor`	string ou null	Para quem é.

`cadastrar_cliente`

Cadastra um cliente pelo CNPJ (nome vem da Receita) ou CPF (informe o nome). Se já existir, devolve o cadastro existente.

Somente leitura: não.

Entrada

Campo	Tipo	Obrigatório	Descrição
`documento`	string	sim	CNPJ ou CPF.
`nome`	string	não	Nome (obrigatório para CPF).
`email`	string	não	E-mail (opcional).
`telefone`	string	não	Telefone com DDD (opcional).

Saída (structuredContent.cliente)

Campo	Tipo	Descrição
`id`	string	Identificador na Tato.
`nome`	string	Nome.
`documento`	string	CNPJ ou CPF, só números.
`tipo`	string	cnpj ou cpf.
`email`	string ou null	E-mail.
`status`	string	cadastrado ou ja_existia.

`ler_dre`

Lê a DRE da empresa em regime de caixa (só o que foi pago): receitas, despesas, resultado e as linhas. Sem mes, devolve o ano inteiro.

Somente leitura: sim.

Entrada

Campo	Tipo	Obrigatório	Descrição
`ano`	integer	não	Ano (padrão: o atual; até 2 anos atrás).
`mes`	integer	não	Mês de 1 a 12 (opcional).

Saída (structuredContent.dre)

Campo	Tipo	Descrição
`periodo`	string	AAAA ou AAAA-MM.
`regime`	string	Sempre caixa.
`receitas`	number	Total de receitas em reais.
`despesas`	number	Total de despesas em reais.
`resultado`	number	Receitas menos despesas, em reais.
`linhas`	array	Linhas da DRE.

Erros e limites

Erro de ferramenta volta como resultado com isError: true e o texto JSON {"erro": {"codigo", "mensagem", "tentar_em_segundos"?}}. Decida pelo codigo, não pela frase.

Código	O que fazer
`entrada_invalida`	Algum campo está faltando ou errado. Corrija o que a mensagem diz e chame de novo.
`limite_atingido`	Limite de uso atingido. Espere tentar_em_segundos antes de repetir.
`acesso_bloqueado`	A conta precisa de uma ação da pessoa no site (assinatura ou e-mail). Não repita: avise a pessoa.
`nao_encontrado`	O registro não existe nesta conta.
`indisponivel`	Falha temporária. Tente de novo em um minuto.

Limite	Valor
Pedidos por conexão	60 por minuto, 1.000 por dia (acima disso: HTTP 429 com `Retry-After`)
Lançamentos por conta	30 por hora, 200 por dia (`limite_atingido`)
Valor por lançamento	até R$ 50.000,00
Leitura da DRE	60 por hora, até 2 anos atrás

Repita só limite_atingido (depois de tentar_em_segundos) e indisponivel (depois de 1 minuto). Nunca repita acesso_bloqueado: avise a pessoa (teste grátis acabou, assinatura pendente ou e-mail sem confirmar).

Autenticação e consentimento

OAuth 2.1 com código de autorização e PKCE S256; cliente público (sem segredo) por registro dinâmico (RFC 7591).
O retorno do código só vai para claude.ai, claude.com ou localhost (Claude Code e Desktop).
A pessoa entra com o e-mail e a senha do cadastro da Tato e vê o que o agente pode e não pode fazer antes de Permitir.
Token de acesso: 1 hora. Renovação: 30 dias, trocada a cada uso (a anterior deixa de valer).
Sem token, https://tato.finance/api/mcp responde 401 com WWW-Authenticate apontando para https://tato.finance/.well-known/oauth-protected-resource.
Desligar: Configurações → Claude → Desconectar (vale na hora).

API ou MCP?

Necessidade	MCP
Agente descobre e chama ferramentas	Sim, é o caminho
Integração de backend sem pessoa	Não oferecido: todo acesso nasce de um Permitir humano

O que o conector não faz

Não emite nota fiscal, não apaga nada, não mexe na assinatura, no e-mail conectado nem no WhatsApp, e não enxerga outra conta. Tudo fica na auditoria da conta como feito pelo Claude (canal mcp).

Para desenvolvedores

Recurso protegido (RFC 9728): https://tato.finance/.well-known/oauth-protected-resource
Servidor de autorização (RFC 8414): https://tato.finance/.well-known/oauth-authorization-server
Registro dinâmico (RFC 7591): https://tato.finance/api/mcp/oauth/registrar
Token: https://tato.finance/api/mcp/oauth/token
Protocolo: JSON-RPC 2.0 sobre HTTP, sem sessão; versões 2025-06-18, 2025-03-26 e 2024-11-05. GET com Accept: text/event-stream responde 405 (não há fluxo do servidor).