# 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, corrige e exclui cobranças e contas a pagar, cadastra, edita e exclui 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 use as 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 ferramentas, com OAuth |

## Claude Code {#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:

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

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

Conecte a Tato:

```bash
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 {#claude-desktop}

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 {#primeira-chamada}

```text
initialize
  → tools/list              (cada ferramenta com inputSchema e outputSchema)
  → ler_dre {}              (somente leitura: confirma que o acesso chega na conta certa)
  → criar_cobranca {...}    (primeira escrita)
  → buscar_cobrancas {...}  (achar o id para corrigir ou excluir)
```

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

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

## Ferramentas {#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. |

### `buscar_clientes`

Lista até 20 clientes ativos desta conta, filtrando por parte do nome ou do CNPJ/CPF. Use o id para editar ou excluir.

Somente leitura: sim.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `texto` | string | não | Parte do nome ou do CNPJ/CPF (opcional). |

**Saída** (`structuredContent.clientes`)

| Campo | Tipo | Descrição |
|---|---|---|

### `editar_cliente`

Corrige nome, e-mail ou telefone de um cliente (por id ou CNPJ/CPF). O documento não muda; o endereço é mantido. E-mail ou telefone vazio apaga o campo.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `cliente` | string | sim | id do cliente ou CNPJ/CPF. |
| `nome` | string | não | Nome novo. |
| `email` | string | não | E-mail novo (vazio apaga). |
| `telefone` | string | não | Telefone novo (vazio apaga). |

**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 | editado. |

### `excluir_cliente`

Exclui um cliente (por id ou CNPJ/CPF). Se ele já tem cobrança ou nota, só sai da lista e o histórico fica.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `cliente` | string | sim | id do cliente ou CNPJ/CPF. |

**Saída** (`structuredContent.excluido`)

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador. |
| `tipo` | string | cliente, cobranca ou conta_pagar. |
| `descricao` | string | Nome ou descrição. |
| `status` | string | excluido ou removido_da_lista (cliente com histórico). |

### `buscar_cobrancas`

Lista até 20 cobranças desta conta (padrão: em aberto), por texto da descrição e faixa de vencimento. Use o id para corrigir ou excluir.

Somente leitura: sim.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `texto` | string | não | Parte da descrição (opcional). |
| `status` | string | não | aberta (padrão), paga ou todas. Valores: `aberta`, `paga`, `todas`. |
| `vencimento_de` | string | não | Data no formato AAAA-MM-DD. |
| `vencimento_ate` | string | não | Data no formato AAAA-MM-DD. |

**Saída** (`structuredContent.cobrancas`)

| Campo | Tipo | Descrição |
|---|---|---|

### `editar_cobranca`

Corrige descrição, valor ou vencimento de uma cobrança em aberto. Mudou o valor, o Pix é refeito. Paga ou com nota emitida não muda.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `cobranca_id` | string | sim | id da cobrança (de buscar_cobrancas). |
| `descricao` | string | não | Descrição nova. |
| `valor` | number | não | Valor em reais, com até 2 casas (ex.: 1250.5). Máximo 50000. |
| `vencimento` | string | não | 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 ou null | Nome do cliente. |
| `pix_copia_e_cola` | string ou null | Pix copia e cola. |

### `excluir_cobranca`

Exclui uma cobrança em aberto. Paga ou com nota emitida não pode.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `cobranca_id` | string | sim | id da cobrança (de buscar_cobrancas). |

**Saída** (`structuredContent.excluido`)

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador. |
| `tipo` | string | cliente, cobranca ou conta_pagar. |
| `descricao` | string | Nome ou descrição. |
| `status` | string | excluido ou removido_da_lista (cliente com histórico). |

### `buscar_contas_pagar`

Lista até 20 contas a pagar desta conta (padrão: em aberto), por texto da descrição e faixa de vencimento. Use o id para corrigir ou excluir.

Somente leitura: sim.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `texto` | string | não | Parte da descrição (opcional). |
| `status` | string | não | aberta (padrão), paga ou todas. Valores: `aberta`, `paga`, `todas`. |
| `vencimento_de` | string | não | Data no formato AAAA-MM-DD. |
| `vencimento_ate` | string | não | Data no formato AAAA-MM-DD. |

**Saída** (`structuredContent.contas_pagar`)

| Campo | Tipo | Descrição |
|---|---|---|

### `editar_conta_pagar`

Corrige descrição, valor, vencimento, categoria ou fornecedor de uma conta a pagar em aberto. Paga não muda.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `conta_pagar_id` | string | sim | id da conta a pagar (de buscar_contas_pagar). |
| `descricao` | string | não | Descrição nova. |
| `valor` | number | não | Valor em reais, com até 2 casas (ex.: 1250.5). Máximo 50000. |
| `vencimento` | string | não | Data no formato AAAA-MM-DD. |
| `categoria` | string | não | Categoria nova. 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 é. |

**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 ou null | Categoria. |
| `fornecedor` | string ou null | Para quem é. |

### `excluir_conta_pagar`

Exclui uma conta a pagar em aberto. Paga não pode.

Somente leitura: não.

**Entrada**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `conta_pagar_id` | string | sim | id da conta a pagar (de buscar_contas_pagar). |

**Saída** (`structuredContent.excluido`)

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador. |
| `tipo` | string | cliente, cobranca ou conta_pagar. |
| `descricao` | string | Nome ou descrição. |
| `status` | string | excluido ou removido_da_lista (cliente com histórico). |

## Erros e limites {#erros}

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`) |
| Alterações por conta (criar, corrigir, excluir) | 30 por hora, 200 por dia (`limite_atingido`) |
| Valor por lançamento | até R$ 50.000,00 |
| Leituras (DRE e buscas) | 60 por hora; DRE até 2 anos atrás; buscas devolvem até 20 itens |

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 mexe no que já foi pago (cobrança recebida ou conta paga), nem na assinatura, no e-mail conectado ou no WhatsApp, e não enxerga outra conta. Para corrigir ou excluir, ache o id com `buscar_cobrancas`, `buscar_contas_pagar` ou `buscar_clientes`. 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).