MCP

Use uma única credencial para acessar os workspaces autorizados em clientes compatíveis com o Model Context Protocol.

Instalação local

cd mcp
npm install
npm run build

O pacote ainda não é distribuído pelo npm. Configure seu cliente para executar o arquivo mcp/dist/index.js deste projeto.

Configuração do cliente

{
  "mcpServers": {
    "matias": {
      "command": "node",
      "args": ["CAMINHO_ABSOLUTO/mcp/dist/index.js"],
      "env": {
        "MATIAS_API_KEY": "um_api_..."
      }
    }
  }
}

MATIAS_API_KEY é obrigatória. MATIAS_API_URL é opcional e usa https://api.usematias.com/v1 por padrão.

Destino explícito

1. Use list_authorized_workspaces para descobrir IDs e permissões atuais.
2. Confirme com o usuário em qual destino executar a ação.
3. Envie workspaceId em toda ferramenta de negócio, mesmo quando houver apenas um workspace.

O MCP não mantém workspace ativo global. Cada chamada revalida a chave, o destino e os scopes no backend.

Recursos disponíveis

• Movimentações, categorias, carteiras, análises, metas e alertas.
• Ciclo completo de sócios: cadastro, aportes, despesas, empréstimos, reembolsos, distribuições, liquidações e correções auditáveis.
• Configurações, dimensões, orçamentos, aprovações, auditoria e relatórios programados de empresas autorizadas.

Operação segura por agentes

1. Consulte o recurso, a versão e as capacidades atuais.
2. Prepare ou visualize o efeito sem escrever quando houver preview.
3. Confirme com o usuário o destino, valor e efeito.
4. Execute com confirmed: true e preserve o identificador idempotente.
5. Releia o recurso e confira o resultado registrado.

Carteiras usam valores em centavos no MCP. Criação e transferência exigem operationId; edição e arquivamento também exigem o expectedUpdatedAt consultado. A conciliação de saldo deve usar preview_wallet_balance_reconciliation antes de reconcile_wallet_balance. A carteira digital Matias, exclusão permanente e recálculos globais não são expostos ao agente.

Sócios

Use get_partner_ledger para obter IDs, versões e saldos. O cadastro usa partyId estável. Eventos documentais usam document_partner_event; registros ou vínculos imediatos usam register_partner_event e exigem escrita financeira e liquidação. Eventos não são editados: correções preservam o histórico por estorno e novo evento.

Planejamento empresarial

• create_company_project aceita initialBudgetopcional. Orçamento Único usa periodType: one_time e permite fim aberto; mensal/anual não renovam automaticamente.
• Consulte get_company_budget e list_company_budget_revisions antes de revisar. Em update_company_budget, amount é o novo teto total em reais, não um acréscimo; informe motivo em reason e a expectedVersion consultada.
• close_company_budget encerra com closedOninclusivo; delete_company_budget arquiva sem apagar histórico. Confirme cada mutação e preserve operationId em retries de criação, encerramento e arquivamento. Não repita escritas automaticamente.

Obrigações avulsas (create_financial_obligation) existem no workspace pessoal e empresarial: uma receita ou despesa ainda não paga. Recorrência é só o molde; consulte e liquide ocorrências por list_financial_obligations, filtrando recurringExpenseId quando vier de regra. record_financial_settlement registra pagamento/recebimento ocorrido, inclusive parcial; reverse_financial_settlement estorna e unlink_financial_settlement desfaz apenas o vínculo. A aprovação não debita; a confirmação manual exige payables:pay e confirmed=true. Regras usam create_recurring_expense e list_recurring_expenses em ambos os workspaces. Valor fixo lança em Transações no vencimento; não transforme estimativa nem obrigação com aprovação pendente em pagamento automático. Cartão recorrente é aceito nos dois workspaces apenas para despesas e registra a compra na fatura sem debitar carteira.