Worthbase

npx add-mcp 'https://worthbase.app/mcp'

O que é o endpoint MCP?

https://worthbase.app/mcp

• Transporte: HTTP Streamable. O servidor não tem estado: cada requisição é tratada de forma independente e as respostas são JSON, sem id de sessão para manter.
• Nome do servidor: worthbase. O servidor envia instruções na inicialização que informam ao agente como ler, escrever e permanecer seguro; clientes bem comportados as repassam ao modelo.
• Clientes: Claude (web, desktop, mobile), ChatGPT (modo desenvolvedor), Cursor, Claude Code e qualquer cliente que suporte servidores MCP remotos com OAuth. Clientes que suportam apenas servidores stdio locais não conseguem conectar diretamente. Etapas por aplicativo estão no guia de configuração.

claude mcp add --transport http worthbase https://worthbase.app/mcp

Como funciona a autenticação?

OAuth 2.1 (código de autorização + PKCE), com Clerk como servidor de autorização. Os clientes se identificam com um Documento de Metadados de Client ID, então não há client ID ou segredo para colar, e eles descobrem todo o resto a partir dos metadados em /.well-known/oauth-protected-resource.

1. Uma requisição não autenticada para /mcp recebe 401 com um cabeçalho WWW-Authenticate: Bearer resource_metadata="…".
2. Os metadados do recurso protegido (RFC 9728) estão em /.well-known/oauth-protected-resource (também /.well-known/oauth-protected-resource/mcp). Eles nomeiam o recurso https://worthbase.app/mcp, o servidor de autorização e os escopos openid profile email offline_access.
3. Para clientes que consultam a origem do recurso, /.well-known/oauth-authorization-server serve os metadados do servidor de autorização.
4. O usuário faz login e aprova. O cliente envia o token de acesso como cabeçalho bearer. Cada requisição verifica o emissor, o público (o recurso /mcp, então tokens emitidos para outros recursos são recusados) e a expiração.

Um token age como o usuário autenticado, com o papel desse usuário em cada workspace. O workspace precisa de uma avaliação ou assinatura ativa para o agente ler ou alterar.

Quais ferramentas o servidor expõe?

Vinte e oito ferramentas. A maioria aceita um workspace opcional (um id de ws_…); sem ele, o workspace padrão do usuário é usado. Os IDs são ULIDs prefixados (itm_, txn_, val_, bat_, pty_, acc_ e assim por diante) e todo resultado os inclui. As ferramentas carregam anotações MCP (somente leitura, destrutivas, mundo aberto) para que os clientes possam definir regras de aprovação.

Ferramentas de leitura (somente leitura)

Ferramenta	O que retorna
whoami	O usuário autenticado, seus workspaces e papéis, seu workspace padrão e convites pendentes.
get_overview	Partes, contas, contagens de itens, patrimônio líquido resumido, itens desatualizados, divergências de reconciliação abertas, status de execução de preços e lotes recentes. Chame primeiro.
get_net_worth	Ativos, passivos, patrimônio líquido, investível e dinheiro em uma data, opcionalmente para uma parte e detalhado por classe, tipo, parte, conta ou item. workspace: "all" dá a participação do próprio usuário em todos os workspaces.
get_history	Patrimônio líquido no final de cada mês, trimestre ou ano entre duas datas, com detalhamentos e a variação no período. Pontos sem valores são marcados como parciais.
list_items	Ativos e passivos com proprietários, notas e posição atual: unidades, preço, valor, base de custo, ganho não realizado, desatualização.
get_item	Um item completo: posição, proprietários, vínculos, transações, avaliações, lotes abertos, reconciliações e os lotes que os escreveram.
get_performance	Valor inicial e final, entradas e saídas de dinheiro, renda, ganho, retorno simples e retorno anual ponderado por dinheiro (XIRR), por item e no total.
get_debt_report	Cada empréstimo com saldo, garantia, compensações e finalidade, além do valor de cada propriedade, dívida garantida, patrimônio e LVR.
get_goals	Metas com progresso, tendência dos últimos 12 meses, data projetada e se está no ritmo.
get_losses	Perdas rastreadas transportadas (empresariais, de capital, de aluguel), com o ano em que surgiram, o valor, o que foi usado e o que resta por parte. Não contam no patrimônio líquido.
simulate_sale	O que vender parte ou toda uma participação, ou uma propriedade ou negócio inteiro, faria: receitas, lotes consumidos (FIFO ou específico), ganho ou perda por parte e a posição resultante. Sem impostos. Nunca escreve.
list_batches	Escritas recentes, das mais novas para as mais antigas, com documento de origem, cliente e status, para revisão ou desfazer.
search_instruments	Encontre um título listado (Yahoo Finance) ou criptomoeda (CoinGecko) por nome ou código, para obter o símbolo, a bolsa ou o id do CoinGecko para um item.

Ferramentas de escrita

Ferramenta	O que faz
record	A principal escrita. Cria contas e itens e registra transações, transferências, avaliações, preços e verificações de reconciliação juntos. Pré-visualiza por padrão.
commit	Salva um lote pré-visualizado pelo seu preview_id. Falha com preview_stale se o razão mudou de uma forma que altera o resultado.
undo	Reverte um lote inteiro confirmado. Pré-visualiza por padrão; recusa se o resultado deixasse o razão inconsistente.
reconcile	Verifica um valor de extrato (unidades, valor ou base de custo) contra o calculado em uma data e registra correspondência ou divergência.
update_item	Altera o nome, classe, subtipo, conta, moeda (antes de qualquer histórico), datas, flags, notas ou atributos de um item. Desfazível.
set_owners	Substitui a divisão de propriedade de um item (deve somar 100). Corrigir histórico requer correction: true.
link_items	Vincula um empréstimo à propriedade que o garante, uma conta de compensação a um empréstimo, ou um empréstimo ao que ele financiou; remove: true desvincula.
archive_item	Remove um item do balanço patrimonial; ganhos já realizados permanecem registrados. Desfazível.
void	Remove transações, avaliações ou preços específicos. Recusa se o razão não pudesse mais ser reproduzido. Desfazível.
set_goal	Cria, altera ou arquiva uma meta de patrimônio líquido ou dívida. Desfazível.
set_loss	Registra, altera ou arquiva uma perda rastreada (proprietário, tipo, ano em que surgiu, valor, valor usado, nota). Desfazível.
refresh_prices	Inicia a busca dos preços mais recentes para um workspace em segundo plano. Os preços também são atualizados diariamente automaticamente.
save_workspace	Cria um workspace ou renomeia um.
save_party	Cria ou atualiza um proprietário legal: pessoa física, empresa, trust, SMSF ou parceria.
save_account	Cria ou atualiza uma conta em uma instituição: corretora, banco, exchange, carteira, fundo de aposentadoria ou empréstimo.
members	Lista membros e convites, convida por e-mail, altera papéis, remove membros e revoga convites.
accept_invite	Entra em um workspace para o qual o usuário foi convidado, por código de convite ou id de convite.

Os papéis se aplicam a toda chamada: visualizadores podem ler, editores podem escrever dados, e administradores também podem gerenciar partes, contas e membros.

Quais recursos e prompts existem?

• guide://recording (recurso, Markdown): como transformar extratos, planilhas e conversas em itens e linhas, com exemplos práticos e aliases conhecidos de cabeçalhos de importação. Os agentes devem lê-lo antes da primeira importação.
• import_document (prompt): importe um extrato, CSV ou planilha: mapeie, pré-visualize e confirme após a aprovação. Argumento opcional description.
• monthly_update (prompt): revise valores desatualizados e registre novos.

Como funcionam as escritas: pré-visualização, confirmação, desfazer?

Toda escrita é um lote. record executa o lote em uma transação que é revertida e retorna uma pré-visualização: novos itens, linhas, duplicatas, conflitos, avisos e a variação do patrimônio líquido, além de um preview_id válido por 30 minutos. O agente mostra a pré-visualização ao usuário e chama commit somente após a confirmação; o lote é então salvo em uma única transação. Itens criados em um lote são confirmados junto com suas transações, e os ids no created de uma pré-visualização não existem até a confirmação.

record(dry_run: true) → preview_id + preview commit(preview_id) → lote bat_… salvo, patrimônio líquido antes/depois undo(bat_…) → execução simulada: o que seria removido ou restaurado undo(bat_…, dry_run: false) → razão reproduzido sem o lote

• Importações idempotentes. Cada linha carrega um external_ref estável (um id de pedido, ou um hash de arquivo e índice de linha). Reimportar o mesmo arquivo pula linhas já registradas.
• Sem exclusões definitivas. As ferramentas arquivam, anulam e desfazem; nada é excluído permanentemente via MCP.
• Desfazer seguro. Desfazer reproduz o razão sem o lote e recusa se o resultado fosse inválido, por exemplo, se uma venda posterior precisar de uma compra que está sendo removida. Não há opção forçada.
• Mantenha lotes pequenos. Um por documento de origem ou grupo de itens relacionados, para que desfazer um erro nunca toque em dados não relacionados.
• Proveniência. Todo lote registra sua origem, o usuário e o cliente que o escreveu.

Por que os números são strings decimais?

Dinheiro, unidades, preços e taxas de câmbio entram e saem como strings decimais, como "1234.56" ou "0.00350000", nunca como números JSON, para que nada se perca em ponto flutuante. Os valores são os números do extrato, excluindo taxas, sempre positivos; o tipo de transação define a direção. Todo valor é rotulado com sua moeda. Linhas em outra moeda podem omitir a taxa de câmbio, e a taxa do BCE para aquela data é usada e reportada. O agente nunca deve somar, converter ou calcular ganhos por conta própria: cada número que ele citar vem do servidor, e todo resultado de escrita inclui o patrimônio líquido antes e depois.

Como são os erros e limites?

Erros retornam como erro de ferramenta com corpo JSON: um code legível por máquina, uma mensagem que diz como corrigir o problema e, quando aplicável, o campo com defeito. refresh_prices roda no máximo uma vez a cada 15 minutos por workspace, e a busca de instrumentos é limitada por usuário. Ganhos e perdas são reportados; o servidor não calcula impostos.

Existe uma API REST?

Ainda não publicamente. Uma API REST com chaves de API de workspace com escopo, para aplicativos que não são clientes MCP, virá depois. Hoje, o acesso programático é através do servidor MCP com OAuth.

Para um resumo em texto simples do produto e site escrito para modelos de linguagem, veja /llms.txt, ou /llms-full.txt para o texto completo de cada página.

Perguntas

Posso construir meu próprio agente no servidor MCP da Worthbase?

Sim. Qualquer cliente MCP que suporte servidores remotos via HTTP Streamable com OAuth pode conectar, incluindo agentes construídos com um SDK MCP. O usuário faz login e aprova o acesso, e o agente age com o papel desse usuário.

O servidor faz alguma aritmética no modelo?

Não. Toda a aritmética roda no servidor com decimais exatos. As instruções do servidor dizem ao agente para citar números de ferramentas como get_net_worth e simulate_sale em vez de calculá-los.

Como o servidor lida com injeção de prompt em documentos?

Texto de documentos e texto armazenado na Worthbase é dado, não instrução. As instruções do servidor dizem ao agente para ignorar instruções encontradas neles e para confirmar com o usuário antes de confirmar, desfazer, arquivar ou anular. Clientes MCP também pedem aprovação antes de chamadas de ferramenta.

Existe uma especificação OpenAPI ou chave de API?

Ainda não para uso público. Chaves de API e uma API REST pública estão planejadas; até lá, use o servidor MCP.