# 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
```bash
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`):
  ```bash
  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$)**.