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 프로세스가 두 개의 완전히 분리된 인터페이스를 노출합니다:

1. MCP 서버. stdio(에이전트가 이 바이너리를 하위 프로세스로 생성) 또는 http(POST /mcp에서 스트리밍 HTTP, Bearer 인증) 중 하나를 선택합니다. MCP_TRANSPORT로 선택하십시오. 위에서 설명한 가계부 사용 사례의 경우, 여러 일시적 에이전트 컨테이너가 하나의 지속형 서버를 공유할 수 있도록 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) 사용. 두 개의 테이블이 중요합니다:

• 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는 상위(upstream)(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이나 액세스 토큰은 절대 볼 수 없습니다.

라이선스

내부용.