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)

No agente financeiro (agente-3-financeiro-afvrech.yaml), em mcp_servers, use: { type: url, name: pluggy, url: "https://SEU-HOST/mcp" }.
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.)
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)

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).
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$).