plaid-mcp

Persistent Plaid MCP server for an AI assistant (Elowen) running in an ephemeral container.

plaid-mcp is a long-lived, externally hosted service that owns the Plaid secret and the encrypted access tokens for every linked institution. The assistant calls mcp__plaid__* tools at runtime; it never sees the raw access tokens, only opaque item_id and account_id values that Plaid already considers public.

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

Surfaces

A single Node.js process exposes two completely separate surfaces:

1. MCP server. Either stdio (the agent spawns this binary as a subprocess) or http (Streamable HTTP at POST /mcp, bearer-gated). Choose with MCP_TRANSPORT. For the family-budget use case described above, you want http so a fleet of ephemeral agent containers can share one persistent server.

2. HTTPS link mini-app at /link/*. Used only during the one-time bank link flow — the user opens a URL the assistant gives them, logs into their bank inside Plaid Link, and is done. After that the browser is never needed again for that institution.

Related MCP server: plaid-mcp

MCP tools

All tool responses are JSON inside a single text content item (works on every MCP client, including ones that don't surface structuredContent).

One-time link flow

1. Elowen calls initiate_link({ institution_hint: "Chase" }). The server:

   • calls Plaid /link/token/create,

   • stores a link_sessions row (status pending),

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

2. Elowen sends the URL to the user.

3. The user opens it in a browser. The page loads Plaid Link JS from the official CDN with that link_token and presents an "Open Plaid Link" button.

4. Plaid Link's onSuccess POSTs { public_token, institution } plus the signed session id back to /link/callback.

5. /link/callback exchanges public_token → access_token + item_id, AES-256-GCM-encrypts the access token, persists it, and marks the session succeeded.

6. Elowen polls link_status(session_id), sees succeeded with the item_id, and proceeds.

The signed URL params (s, sig) are HMAC-SHA256-keyed by LINK_SESSION_SECRET. The DB row is the source of truth — the HMAC just cheaply rejects garbage requests before we touch SQLite.

Configuration

All config is via environment variables (loaded from .env).

Generate secrets with:

make keys

Storage

SQLite (better-sqlite3) at $DB_PATH. Two tables matter:

• items — item_id PK, encrypted access_token_blob BLOB, institution name/id, status, consent expiration.

• link_sessions — short-lived, expire automatically when read after their expires_at and during a 60s background sweep.

Access tokens are stored as [1-byte version][12-byte IV][16-byte GCM tag][N-byte ciphertext]. Decryption fails closed if the GCM tag doesn't verify.

Security model

• The MCP HTTP transport requires Authorization: Bearer $MCP_BEARER_TOKEN on every request. Without it the agent fleet would expose every linked bank account to the internet.

• The browser-facing /link/* routes are signed (HMAC) and bound to a short-lived DB-backed session.

• TLS is expected to terminate upstream (at nanoclaw / Caddy / whatever your edge is). The container speaks plain HTTP internally; expose it only through the proxy.

• Every Plaid token is encrypted at rest. Even with the SQLite file in hand, an attacker without PLAID_ENCRYPTION_KEY cannot use the tokens.

• The MCP tools never return access tokens to the agent. Only opaque item_id / account_id strings cross the MCP boundary.

Local development

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

For local link testing you'll need an HTTPS tunnel (Plaid Link onSuccess won't fire from http://localhost). cloudflared, ngrok, or a real Caddy reverse proxy all work; whatever public hostname they give you goes into LINK_BASE_URL.

Docker

make build
make up
make logs

The compose file mounts ./data:/data so the SQLite DB survives restarts. In a nanoclaw deployment, replace that bind-mount with the cluster-managed persistent volume.

Wiring the agent to a hosted instance

Inside the agent container's MCP client config:

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

The agent gets the bearer token through whatever secret-injection mechanism nanoclaw already uses for its other agent secrets. It does not ever see PLAID_SECRET or any access token.

License

Internal.