Cdf MCP Server

CDF Finance MCP

Conecte Claude, ChatGPT e qualquer client MCP (OAuth 2.1) à sua conta CDF Finance — consulte e registre sua vida financeira por linguagem natural.

Remoto: https://mcp.cdf.finance/mcp (Streamable HTTP) · Website: https://cdf.finance/mcp · Status: https://status.cdf.finance · Suporte: support@cdf.finance

---

O que é

MCP server stateless e isolado para o CDF Finance — app de controle financeiro pessoal (contas, cartões, transações, faturas, orçamentos, metas, dívidas, investimentos e insights).

• Para usuários: pergunte ao Claude/ChatGPT sobre seu dinheiro e registre lançamentos sem abrir o app.
• Para desenvolvedores/revisores: código auditável, sem dependência do backend-husk — só HTTP sobre a API pública que o app mobile já usa.

Source-available sob BUSL-1.1: pode auditar, usar com o CDF Finance, contribuir. Uso em produção como produto concorrente exige licença comercial. Vira Apache-2.0 em 2030-09-01.

Exemplos

English: "How much is left of my salary?" / "Will my next bill fit the budget?" / "Log an Uber ride of R$27.50 on Nubank as Transportation."

---

Arquitetura

Isolamento total do backend-husk — este serviço não importa código do backend.

Claude / ChatGPT (MCP client)
        │  OAuth 2.1 — DCR + PKCE (S256)
        ▼
┌───────────────────────────────┐
│  cdf-mcp-server (este repo)   │  Postgres isolado (Railway)
│  • Authorization Server        │  ├─ oauth_clients / oauth_codes
│  • Resource Server (/mcp)     │  ├─ oauth_tokens (hash SHA-256)
│  • Catálogo declarativo       │  └─ sessions (JWT mobile criptografado
│    ~50 tools → REST           │                AES-256-GCM)
└───────────────┬───────────────┘
                │  HTTPS — Bearer <mobile JWT>
                ▼
        backend-husk (api.vessell.app)
        API pública — mesmo contrato do app mobile

Fluxo de login:

1. Client faz Dynamic Client Registration em /register.
2. Usuário autoriza em /authorize (form server-rendered, sem terceiros) → POST /api/mobile/auth/login com device_id=mcp-<sessionId>, platform=mcp.
3. access/refresh do backend ficam criptografados em sessions; client MCP recebe apenas token opaco (oauth_tokens).
4. Cada tool renova o access_token via refresh automaticamente (getValidAccessToken).
5. Sessão aparece como device em GET /api/mobile/devices — revogável em DELETE /api/mobile/devices/:id.

Por que isolado (README original): sem dependência circular, deploy/escala independentes (Railway vs Coolify no backend) e imune a troca de linguagem do backend — só fala HTTP.

Tools

Catálogo 100% declarativo em src/tools/catalog/ — cada tool é { name, method, path, input(zod) } executada por src/tools/register.ts. Nova rota no backend = nova entrada, sem handler.

Fora de escopo de propósito (igual ao backend): admin, Stripe/pagamentos, webhooks, S3/anexos, /api/ai/*.

Modo somente leitura: MCP_TOOLS_MODE=readonly expõe só readOnly:true — ideal para diretórios curados.

---

Quick start

cp .env.example .env   # preencha DATABASE_URL, TOKEN_ENCRYPTION_KEY, SESSION_SECRET
npm install
npm run db:migrate
npm run dev            # http://localhost:8090

Teste com MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP → http://localhost:8090/mcp

Variáveis de ambiente

Ver .env.example comentado.

Deploy (Railway)

1. railway init ou conecte o repo no dashboard.
2. Adicione addon Postgres (injeta DATABASE_URL).
3. Configure envs acima — gere domínio em Settings → Networking primeiro.
4. Deploy: Dockerfile → node dist/index.js (railway.json já configurado).
5. Migration: railway run npm run db:migrate.
6. No Claude.ai/ChatGPT aponte o connector para https://<seu-dominio>.up.railway.app/mcp — DCR/OAuth é automático.

---

Segurança

• PKCE S256 obrigatório em todo authorization_code.
• Tokens opacos — só SHA-256 persiste (oauth_tokens), bruto é entregue uma vez.
• JWT mobile criptografado AES-256-GCM em sessions — nunca exposto ao client (src/crypto.ts, src/mcp/http.ts).
• Device isolado — cada sessão mcp-<id> (src/backend/client.ts:45) revogável sem afetar outros logins.
• Sanitização — redactLargeInlineData + redactFields (src/tools/register.ts:19) evita vazamento de data: URI e campos sensíveis pro LLM.

Reporte vulnerabilidades em SECURITY.md — não abra issue pública: support@cdf.finance [SECURITY].

Conformidade — Diretório Anthropic (Seção 4.A)

Este conector não transfere dinheiro/cripto/ativos e não executa pagamentos em nome do usuário — apenas lê e registra lançamentos no controle financeiro pessoal, igual ao app. Toda escrita é explícita e solicitada na conversa.

• Para listagens curadas use MCP_TOOLS_MODE=readonly.
• Pedido de exceção por escrito (previsto na própria 4.A): docs/4a-exception-request.md.
• Conta de teste para revisores: joao@teste.com / 123456 (dados de amostra).

Contribuindo

Veja CONTRIBUTING.md — fork, branch feat/..., npm run build e PR com path validado no backend. Ao contribuir você licencia sob BUSL-1.1.

Licença

Source-available BUSL-1.1 — uso com o CDF Finance, pessoal, acadêmico e contribuições são livres. Proibido uso em produção como produto concorrente de gestão financeira (hosted/managed). Converte para Apache-2.0 em 2030-09-01.

Dúvidas comerciais: support@cdf.finance.

---