SuperBooks MCP

Trabalhe com seus livros do SuperBooks: transações e categorias, faturas, clientes, recibos, controle de tempo e relatórios financeiros. Servidor remoto com login via OAuth.

Ver em superbooks.ioExperimente este MCPPatrocinado

Servidor MCP hospedado

npx add-mcp 'https://app.superbooks.io/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Aponte o Claude, o Claude Code, o Cursor ou qualquer cliente MCP para o SuperBooks por meio da URL remota.

O SuperBooks é um servidor MCP, portanto qualquer cliente compatível com MCP pode usá-lo sem plugin ou adaptador. O endpoint é:

https://api.superbooks.io/mcp

Ele fala Streamable HTTP, e os clientes se conectam diretamente a essa URL.

O que um cliente vê

Conecte qualquer cliente MCP e sua tools/list mostra exatamente duas ferramentas: search_tools e execute_typescript. Este é o Modo Código: em vez de uma ferramenta MCP por operação do SuperBooks, o assistente chama search_tools para descobrir as operações que sua credencial pode acessar e, em seguida, escreve e executa um pequeno programa TypeScript com execute_typescript que as chama. As 46 ferramentas reais do SuperBooks (45 em 12 domínios, mais list_teams) são acessadas dessa forma, em vez de listadas diretamente — veja A superfície de ferramentas. Cada uma ainda carrega seu próprio escopo e autenticação exatamente como se o cliente a tivesse chamado diretamente. O limite de 120 requisições por minuto conta requisições MCP, não chamadas de ferramenta: uma requisição conta uma vez, quer execute uma única ferramenta ou um programa execute_typescript que chame várias.

Escolhendo entre uma chave e OAuth

Clientes que suportam servidores MCP remotos com OAuth — entre eles o Claude — podem fazer login por meio da tela de consentimento do SuperBooks. Nada para copiar, nada para armazenar, e o acesso é revogável pelo aplicativo.

Clientes que esperam um cabeçalho estático querem uma chave de API. Crie uma em Configurações → Desenvolvedor; veja Autenticação.

Claude

O Claude conecta via OAuth, então você não lida com chave alguma.

Abra Configurações → Conectores.
Escolha Adicionar conector personalizado.
Insira https://api.superbooks.io/mcp.
O Claude se registra e, em seguida, envia você ao SuperBooks para fazer login, escolher quais de suas equipes ele pode usar e aprovar os escopos que solicitou.

search_tools e execute_typescript ficam então disponíveis na conversa, e o Claude as usa para encontrar e chamar as ferramentas reais do SuperBooks — veja O que um cliente vê. Revogue o acesso a qualquer momento na mesma tela de Conectores ou no aplicativo SuperBooks.

Clientes verificados na tela de consentimento

A tela de consentimento marca clientes de IA conhecidos, como Claude e Perplexity, como Verificados, com nome e logotipo próprios. O SuperBooks decide isso com base nos endereços que o cliente registrou para receber sua aprovação: todos devem ser o endereço de login publicado pela própria empresa, em seu próprio site. O nome e o logotipo que um cliente envia sobre si mesmo não têm papel algum, porque qualquer programa pode alegar qualquer nome.

Qualquer outro cliente, incluindo um que rode no seu próprio computador, aparece como desenvolvedor não verificado com um aviso. Isso não é um erro. Pede que você verifique se iniciou a conexão você mesmo antes de aprová-la.

Uma conexão, várias equipes

Uma conta SuperBooks pode pertencer a várias equipes, e uma conexão pode cobrir mais de uma delas. Na tela de consentimento, você escolhe:

Todas as minhas equipes: todas as equipes das quais você é membro quando uma requisição chega, incluindo equipes que você entrar depois.
Equipes específicas: apenas as equipes que você marcar. Marque pelo menos uma.

Escolha a concessão mais restrita que atenda ao trabalho: marque equipes específicas em vez de todas, porque um assistente que trabalha em várias equipes pode levar o que lê em uma para outra.

Uma conexão cobre no máximo 100 equipes. Uma conexão Todas as minhas equipes para alguém em mais de 100 equipes é recusada, e a mensagem diz para conectar novamente e marcar equipes específicas.

O SuperBooks verifica sua associação em toda requisição, não apenas quando você conecta. Saia de uma equipe e a conexão para de alcançá-la imediatamente. Se você não for mais membro de nenhuma equipe que ela cubra, as requisições são recusadas até você conectar novamente e escolher.

Quando uma conexão cobre uma equipe, toda ferramenta funciona nessa equipe e nada mais muda. Quando cobre várias, cada ferramenta que lê ou altera dados de uma equipe recebe um argumento opcional teamId:

list_teams retorna as equipes que a conexão cobre, com o id, o nome e seu papel em cada uma. Ela precisa apenas de acesso de leitura.
Passe teamId para escolher a equipe para aquela chamada.
Uma chamada sem teamId é recusada com TEAM_REQUIRED, e a mensagem lista as equipes para escolher por nome e id.
Um teamId que a conexão não cobre é recusado com TEAM_NOT_AVAILABLE. A mensagem é a mesma, exista ou não uma equipe com esse id.
Uma ferramenta destrutiva em uma equipe cuja configuração Ferramentas de IA destrutivas está desligada é recusada com DESTRUCTIVE_TOOLS_OFF, nomeando a equipe. Ative a configuração em Configurações > IA nessa equipe; reconectar não a altera.

As permissões são calculadas por equipe. Uma conexão somente leitura é somente leitura em todas as equipes, e uma ferramenta destrutiva também precisa da configuração ativada na equipe que a chamada nomeia.

Uma chave de API pertence a uma equipe. Suas ferramentas sempre funcionam nessa equipe, e um teamId nomeando qualquer outra equipe é recusado.

Claude Code

Um comando, usando uma chave de API:

claude mcp add --transport http superbooks https://api.superbooks.io/mcp \
  --header "Authorization: Bearer sb_your_api_key_here"

Depois verifique se está ativo:

claude mcp list

Cursor

Adicione o SuperBooks a ~/.cursor/mcp.json (global) ou .cursor/mcp.json em um projeto:

{
  "mcpServers": {
    "superbooks": {
      "url": "https://api.superbooks.io/mcp",
      "headers": {
        "Authorization": "Bearer sb_your_api_key_here"
      }
    }
  }
}

Reinicie o Cursor, e search_tools / execute_typescript aparecem em Configurações → MCP — veja O que um cliente vê.

Windsurf

O Windsurf usa o mesmo formato, em ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "superbooks": {
      "serverUrl": "https://api.superbooks.io/mcp",
      "headers": {
        "Authorization": "Bearer sb_your_api_key_here"
      }
    }
  }
}

A superfície de ferramentas

Estas são as 46 ferramentas reais do SuperBooks alcançáveis por meio de search_tools e execute_typescript (veja O que um cliente vê) — não o que uma chamada bruta de tools/list retorna, que é sempre apenas essas duas: 45 ferramentas em 12 domínios, mais list_teams para escolher uma equipe quando uma conexão cobre várias. O que a chamada de search_tools de uma determinada credencial realmente declara depende de seus escopos — veja Como os escopos controlam a superfície de ferramentas.

Domínio	Ferramentas	Destrutivas	O que cobre
`transactions`	5	1	Transações bancárias, filtragem, categorização
`invoices`	5	1	Elaboração, envio e cancelamento de faturas
`customers`	5	1	O livro de clientes
`tracker`	5	1	Projetos e lançamentos de controle de horas
`categories`	4	1	Categorias de transações
`documents`	4	1	Arquivos enviados e seus conteúdos
`tags`	3	1	Etiquetas em clientes, transações, projetos
`inbox`	3	1	Recibos e contas recebidos, e sua conciliação
`reports`	8	0	Receita, lucro e perda, taxa de queima, pista, gastos
`bank_accounts`	1	0	Contas conectadas
`search`	1	0	Busca entre domínios
`team`	1	0	O perfil da equipe atual
`list_teams`	1	0	As equipes que uma conexão cobre; somente MCP, não os SDKs

As oito ferramentas destrutivas são as sete ferramentas *_delete mais invoices_void (um cancelamento suave, não uma exclusão), e elas são controladas duas vezes — veja Ferramentas destrutivas precisam de dois portões.

Solução de problemas

O cliente não mostra ferramentas ou falha ao conectar. Verifique a credencial primeiro: um 401 retorna com um cabeçalho WWW-Authenticate apontando para os metadados OAuth. Se estiver usando uma chave, confirme que ela começa com sb_ e ainda existe em Configurações → Desenvolvedor. (A própria lista de ferramentas do cliente sempre mostra exatamente search_tools e execute_typescript, independentemente dos escopos — uma credencial ausente aparece como um 401, nunca como uma lista de ferramentas mais curta.)

search_tools retorna menos operações do que o esperado. Isso são os escopos funcionando como projetado. Uma chave somente leitura vê apenas o nível de leitura. Ferramentas destrutivas adicionalmente precisam de apis.all mais a configuração da equipe.

Uma chamada de ferramenta falha com TEAM_REQUIRED. A conexão cobre mais de uma equipe. Chame list_teams e repita a chamada com o teamId da equipe que você quer.

Requisições são recusadas depois que você saiu de uma equipe. A conexão não cobre mais nenhuma equipe da qual você é membro. Conecte novamente e escolha suas equipes.

Uma ferramenta destrutiva falha com DESTRUCTIVE_TOOLS_OFF. A equipe que a chamada nomeou tem Ferramentas de IA destrutivas desligado. Ative-o em Configurações > IA nessa equipe; conectar novamente não o altera.

Requisições começam a falhar após uso intenso. Você pode estar atingindo o limite de 120 requisições por minuto — veja Limites de taxa.

[

Autenticação

Chaves de API para sua própria equipe, OAuth com PKCE e registro dinâmico de clientes para integradores, e como os escopos controlam a superfície de ferramentas.

](https://docs.superbooks.io/authentication)[

Limites de taxa

O limite por credencial em chamadas MCP, o limite de registro e como lidar com um 429.

](https://docs.superbooks.io/rate-limits)