plaid-mcp

Persistenter Plaid-MCP-Server für einen KI-Assistenten (Elowen), der in einem ephemeren Container läuft.

plaid-mcp ist ein langlebiger, extern gehosteter Dienst, der das Plaid- Geheimnis und die verschlüsselten Zugriffstoken für jede verknüpfte Institution besitzt. Der Assistent ruft zur Laufzeit mcp__plaid__*-Tools auf; er sieht niemals die rohen Zugriffstoken, sondern nur undurchsichtige item_id- und account_id-Werte, die Plaid bereits als öffentlich betrachtet.

Elowen (ephemeral container)
  └─ calls mcp__plaid__* tools
        └─ plaid-mcp (persistent, nanoclaw-hosted)
              ├─ Plaid SDK + PLAID_SECRET (never leaves this service)
              ├─ access_token store (SQLite, AES-256-GCM at rest)
              └─ /link/start, /link/callback (HTTPS, browser-facing)
                    └─ Plaid REST API / Plaid Link JS

Oberflächen

Ein einzelner Node.js-Prozess stellt zwei völlig getrennte Oberflächen bereit:

1. MCP-Server. Entweder stdio (der Agent startet diese Binärdatei als Subprozess) oder http (Streamable HTTP unter POST /mcp, mit Bearer-Token-Schutz). Wählen Sie dies mit MCP_TRANSPORT. Für den oben beschriebenen Anwendungsfall des Familienbudgets wollen Sie http, damit eine Flotte ephemerer Agenten-Container einen persistente Server gemeinsam nutzen kann.

2. HTTPS-Link-Mini-App unter /link/*. Wird nur während des einmaligen Bankverknüpfungsprozesses verwendet — der Benutzer öffnet eine URL, die der Assistent ihm gibt, meldet sich innerhalb von Plaid Link bei seiner Bank an und ist fertig. Danach wird der Browser für diese Institution nie wieder benötigt.

Related MCP server: plaid-mcp

MCP-Tools

Alle Tool-Antworten sind JSON innerhalb eines einzelnen text-Inhaltselements (funktioniert auf jedem MCP-Client, einschließlich solcher, die structuredContent nicht anzeigen).

Einmaliger Verknüpfungsprozess

1. Elowen ruft initiate_link({ institution_hint: "Chase" }) auf. Der Server:

   • ruft Plaid /link/token/create auf,

   • speichert eine link_sessions-Zeile (Status pending),

   • gibt { url: "https://<LINK_BASE_URL>/link/start?s=<uuid>&sig=<hmac>", session_id, expires_at } zurück.

2. Elowen sendet die URL an den Benutzer.

3. Der Benutzer öffnet sie in einem Browser. Die Seite lädt Plaid Link JS vom offiziellen CDN mit diesem link_token und präsentiert einen "Open Plaid Link"-Button.

4. Plaid Links onSuccess sendet { public_token, institution } plus die signierte Session-ID per POST zurück an /link/callback.

5. /link/callback tauscht public_token → access_token + item_id aus, verschlüsselt das Zugriffstoken mit AES-256-GCM, speichert es dauerhaft und markiert die Session als succeeded.

6. Elowen fragt link_status(session_id) ab, sieht succeeded mit der item_id und fährt fort.

Die signierten URL-Parameter (s, sig) sind HMAC-SHA256-geschlüsselt durch LINK_SESSION_SECRET. Die DB-Zeile ist die Quelle der Wahrheit — der HMAC lehnt einfach und kostengünstig fehlerhafte Anfragen ab, bevor wir SQLite berühren.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen (geladen aus .env).

Generieren Sie Geheimnisse mit:

make keys

Speicherung

SQLite (better-sqlite3) unter $DB_PATH. Zwei Tabellen sind wichtig:

• items — item_id PK, verschlüsseltes access_token_blob BLOB, Institution Name/ID, Status, Ablauf der Zustimmung.

• link_sessions — kurzlebig, laufen automatisch ab, wenn sie nach ihrem expires_at und während eines 60-sekündigen Hintergrund-Sweeps gelesen werden.

Zugriffstoken werden gespeichert als [1-Byte Version][12-Byte IV][16-Byte GCM Tag][N-Byte Ciphertext]. Die Entschlüsselung schlägt fehl, wenn das GCM-Tag nicht verifiziert werden kann.

Sicherheitsmodell

• Der MCP-HTTP-Transport erfordert Authorization: Bearer $MCP_BEARER_TOKEN bei jeder Anfrage. Ohne dies würde die Agentenflotte jedes verknüpfte Bankkonto dem Internet preisgeben.

• Die browserseitigen /link/*-Routen sind signiert (HMAC) und an eine kurzlebige, DB-gestützte Session gebunden.

• TLS wird erwartet, vorgelagert (bei nanoclaw / Caddy / was auch immer Ihr Edge ist) zu terminieren. Der Container spricht intern einfaches HTTP; stellen Sie ihn nur über den Proxy bereit.

• Jedes Plaid-Token ist im Ruhezustand verschlüsselt. Selbst mit der SQLite-Datei in der Hand kann ein Angreifer ohne PLAID_ENCRYPTION_KEY die Token nicht verwenden.

• Die MCP-Tools geben niemals Zugriffstoken an den Agenten zurück. Nur undurchsichtige item_id / account_id-Strings überschreiten die MCP-Grenze.

Lokale Entwicklung

npm install
make setup           # creates .env from env.example
make keys >> .env    # append fresh PLAID_ENCRYPTION_KEY / LINK_SESSION_SECRET / MCP_BEARER_TOKEN
# edit .env: PLAID_CLIENT_ID, PLAID_SECRET, LINK_BASE_URL
npm run dev          # tsx with hot reload

Für lokale Link-Tests benötigen Sie einen HTTPS-Tunnel (Plaid Link onSuccess funktioniert nicht von http://localhost). cloudflared, ngrok oder ein echter Caddy-Reverse-Proxy funktionieren alle; welcher öffentliche Hostname auch immer Ihnen gegeben wird, kommt in LINK_BASE_URL.

Docker

make build
make up
make logs

Die Compose-Datei mountet ./data:/data, damit die SQLite-DB Neustarts überlebt. Ersetzen Sie in einer nanoclaw-Bereitstellung diesen Bind-Mount durch das cluster-verwaltete persistente Volume.

Anbindung des Agenten an eine gehostete Instanz

Innerhalb der MCP-Client-Konfiguration des Agenten-Containers:

{
  "mcpServers": {
    "plaid": {
      "url": "https://plaid-mcp.your-domain.example/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_BEARER_TOKEN>"
      }
    }
  }
}

Der Agent erhält das Bearer-Token über den Mechanismus zur Geheimnis-Injektion, den nanoclaw bereits für seine anderen Agenten-Geheimnisse verwendet. Er sieht niemals PLAID_SECRET oder irgendein Zugriffstoken.

Lizenz

Intern.