plaid-mcp

エフェメラル（一時的）なコンテナで実行されるAIアシスタント（Elowen）のための、常駐型Plaid MCPサーバーです。

plaid-mcpは、Plaidのシークレットと、リンクされたすべての金融機関の暗号化されたアクセストークンを保持する、長期間稼働する外部ホスト型サービスです。アシスタントは実行時に mcp__plaid__* ツールを呼び出しますが、生のアクセストークンを見ることはありません。Plaidがすでに公開情報とみなしている不透明な item_id および account_id の値のみを扱います。

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

サーフェス

単一のNode.jsプロセスが、完全に分離された2つのサーフェスを公開します。

1. MCPサーバー。 stdio（エージェントがこのバイナリをサブプロセスとして起動する）または http（POST /mcp でのストリーミングHTTP、Bearer認証付き）のいずれか。MCP_TRANSPORT で選択します。前述の家計管理のユースケースでは、エフェメラルなエージェントコンテナの群れが1つの常駐サーバーを共有できるように http を推奨します。

2. HTTPSリンクミニアプリ (/link/*)。銀行リンクの初回フロー時のみ使用されます。ユーザーはアシスタントから提供されたURLを開き、Plaid Link内で銀行にログインして完了します。その後、その金融機関のためにブラウザが必要になることはありません。

Related MCP server: plaid-mcp

MCPツール

すべてのツール応答は、単一の text コンテンツアイテム内のJSONです（structuredContent を表示しないクライアントを含む、すべてのMCPクライアントで動作します）。

初回リンクフロー

1. Elowenが initiate_link({ institution_hint: "Chase" }) を呼び出します。サーバーは以下の処理を行います。

   • Plaidの /link/token/create を呼び出す。

   • link_sessions 行を保存する（ステータスは pending）。

   • { url: "https://<LINK_BASE_URL>/link/start?s=<uuid>&sig=<hmac>", session_id, expires_at } を返す。

2. ElowenがユーザーにURLを送信します。

3. ユーザーがブラウザでURLを開きます。ページは公式CDNから link_token を使用してPlaid Link JSを読み込み、「Open Plaid Link」ボタンを表示します。

4. Plaid Linkの onSuccess が { public_token, institution } と署名済みセッションIDを /link/callback にPOSTします。

5. /link/callback が public_token を access_token + item_id に交換し、アクセストークンをAES-256-GCMで暗号化して保存し、セッションを succeeded とマークします。

6. Elowenが link_status(session_id) をポーリングし、item_id を伴う succeeded を確認して処理を続行します。

署名付きURLパラメータ (s, sig) は LINK_SESSION_SECRET によってHMAC-SHA256でキー化されています。DB行が信頼の源泉であり、HMACはSQLiteに触れる前に不正なリクエストを安価に拒否するためのものです。

設定

すべての設定は環境変数（.env から読み込み）で行います。

シークレットの生成方法:

make keys

ストレージ

$DB_PATH にSQLite (better-sqlite3) を使用します。重要なテーブルは2つです。

• items — item_id (PK)、暗号化された access_token_blob (BLOB)、金融機関名/ID、ステータス、同意有効期限。

• link_sessions — 短命なセッション。expires_at を過ぎた後の読み取り時、および60秒ごとのバックグラウンドスイープで自動的に期限切れになります。

アクセストークンは [1バイトのバージョン][12バイトのIV][16バイトのGCMタグ][Nバイトの暗号文] として保存されます。GCMタグが検証できない場合、復号は失敗します。

セキュリティモデル

• MCP HTTPトランスポートは、すべてのリクエストで Authorization: Bearer $MCP_BEARER_TOKEN を要求します。これがないと、エージェント群がリンクされたすべての銀行口座をインターネットに公開することになります。

• ブラウザ向けの /link/* ルートは署名（HMAC）されており、短命なDBベースのセッションにバインドされています。

• TLSは**上位（nanoclaw / Caddy / エッジ環境）**で終端されることを想定しています。コンテナ内部はプレーンなHTTPで通信するため、プロキシ経由でのみ公開してください。

• すべてのPlaidトークンは保存時に暗号化されます。SQLiteファイルが流出したとしても、PLAID_ENCRYPTION_KEY を持たない攻撃者はトークンを使用できません。

• MCPツールはアクセストークンをエージェントに返しません。不透明な item_id / account_id 文字列のみがMCP境界を越えます。

ローカル開発

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

ローカルでのリンクテストにはHTTPSトンネルが必要です（Plaid Linkの onSuccess は http://localhost からは発火しません）。cloudflared、ngrok、または実際のCaddyリバースプロキシなどが使用可能です。取得した公開ホスト名を LINK_BASE_URL に設定してください。

Docker

make build
make up
make logs

Composeファイルは ./data:/data をマウントしているため、SQLite DBは再起動後も保持されます。nanoclaw環境では、そのバインドマウントをクラスター管理の永続ボリュームに置き換えてください。

ホスト型インスタンスへのエージェントの接続

エージェントコンテナのMCPクライアント設定内:

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

エージェントは、nanoclawが他のエージェントシークレットに使用しているシークレット注入メカニズムを通じてBearerトークンを取得します。PLAID_SECRET やアクセストークンを直接見ることはありません。

ライセンス

内部利用。