pluggy-mcp-server

Servidor MCP remoto (streamable HTTP), somente leitura que conecta contas do Pluggy (Open Finance Brasil) a um agente Claude (Managed Agents). Expõe contas, saldos, transações e investimentos — e nenhuma operação de pagamento/transferência.

Segurança (leia primeiro)

• Credenciais só via variáveis de ambiente. Nada de segredo no código.
• Endpoint protegido por bearer token (MCP_AUTH_TOKEN): o /mcp recusa requisições sem Authorization: Bearer <token>.
• Somente leitura: todas as tools têm readOnlyHint: true. O servidor não implementa pagamentos.
• Números de conta são retornados mascarados (só os 4 últimos dígitos).

Variáveis de ambiente

Variável	Obrigatória	O que é
PLUGGY_CLIENT_ID	sim	Client ID da sua aplicação Pluggy (Dashboard → Aplicações).
PLUGGY_CLIENT_SECRET	sim	Client Secret da aplicação Pluggy.
PLUGGY_ITEM_IDS	recomendado	UUIDs das conexões (items) já criadas, separados por vírgula.
MCP_AUTH_TOKEN	sim	Token que protege o /mcp. Gere forte: openssl rand -hex 32.
PORT	não	Porta HTTP (default 3000).
PLUGGY_BASE_URL	não	Default https://api.pluggy.ai.

Onde pego os PLUGGY_ITEM_IDS? Cada "item" é uma conexão bancária criada via Pluggy Connect (widget) ou pelo item demo/sandbox do Dashboard. O itemId aparece no Dashboard (Dados Financeiros) e no retorno do Connect. A API do Pluggy não lista todos os items por segurança — por isso você informa os IDs aqui.

Rodar localmente

npm install
npm run build
MCP_AUTH_TOKEN=teste PLUGGY_CLIENT_ID=... PLUGGY_CLIENT_SECRET=... PLUGGY_ITEM_IDS=uuid1,uuid2 npm start
# valida:
curl localhost:3000/health

Deploy (precisa de HTTPS público — o Managed Agents só conecta em URL remota)

Escolha um. Em todos, defina as variáveis de ambiente do quadro acima.

• Docker (incluí Dockerfile):

  docker build -t pluggy-mcp .
  docker run -p 3000:3000 --env-file .env pluggy-mcp
  

• Render / Railway / Fly.io: aponte para este repositório, runtime Node 20 (ou o Dockerfile), build npm install && npm run build, start npm start, e cadastre as env vars no painel. A plataforma te dá uma URL https://.... Seu endpoint MCP será https://SEU-HOST/mcp.

Conectar no Claude (Managed Agents)

1. No agente financeiro (agente-3-financeiro-afvrech.yaml), em mcp_servers, use: { type: url, name: pluggy, url: "https://SEU-HOST/mcp" }.
2. Crie um Cofre de credenciais (Vault) no Console → adicione uma credencial bearer estático amarrada à URL https://SEU-HOST/mcp, com valor = seu MCP_AUTH_TOKEN. (Você digita o token no Console; eu não manuseio segredos.)
3. Ao Iniciar sessão, referencie o vault (vault_ids). O Console injeta o header Authorization: Bearer <token> a cada chamada — que o servidor valida.

Tools expostas (todas read-only)

• pluggy_list_items — conexões configuradas (conector, status, última atualização).
• pluggy_list_accounts — contas e saldos (+ total por moeda). Aceita item_id opcional.
• pluggy_get_realtime_balance — saldo em tempo real de uma conta (account_id).
• pluggy_list_transactions — transações de uma conta por período (account_id, from, to).
• pluggy_list_investments — investimentos de um item.

⚠️ Limitações importantes (do seu setup atual)

1. Conta Pluggy em trial/sandbox. Para ler contas reais da AFVrech é preciso liberar "dados reais" e completar a due diligence no Dashboard (aprovação do Pluggy). Enquanto isso, dá para testar tudo com o conector Sandbox (dados fictícios).
2. Portugal/€ não é coberto pelo Pluggy (é Open Finance Brasil). O lado em euros da AFVrech não virá por aqui — a decisão de câmbio €×R$ precisará do saldo PT por outra fonte (entrada manual ou um agregador europeu). Este MCP cobre o lado Brasil (R$).