ClaudeにPlaid MCPをつないで連携の不具合を調べる手順

Plaid MCPでClaudeに何を調べさせられるか

PlaidのDashboard MCPサーバーは、Plaidが運営するリモートMCPサーバーです。Production環境の診断と分析のツールを備えており、Itemのデバッグ、Linkの転換データの確認、利用量の確認をClaudeの会話から頼めます。

Claudeのコネクタ一覧には「Plaid Developer Tools」の名前で載っています。開発元はPlaidで、Anthropic verifiedの表示があり、追加時期は2025年11月、サインインは必須です。説明文は「Monitor, debug, and optimize your Plaid integration」。Plaidを組み込んだアプリを運用する開発者向けの道具で、銀行口座をつなぐエンドユーザーが使うものではありません。

たとえば次のような依頼が想定できます。

• 特定のItemがなぜ更新に失敗しているかを調べてほしい
• 先週のLinkの開始から完了までの転換を日別に出してほしい
• 今月のAPIリクエスト量を製品別に知りたい

Connector全般の仕組みはClaudeのコネクタとはで説明しています。ここでは、Plaid側の前提条件と接続方法、5つのツールの使い分けに絞ります。

接続前に確認する条件

Dashboard MCPサーバーはProductionのデータだけを扱います。Sandboxのデータは見られません。使うには、チームがPlaidの少なくとも1つの製品でProductionアクセスの承認を受けている必要があります。

もう1つ見落としやすいのが開発状況です。Plaidのドキュメントは、このサーバーを「active development」と明記し、破壊的変更が入りうること、サポートは現時点で限定的であることを述べています。業務の手順に固定で組み込む前に、ツール名や返り値が変わりうる前提で使うことになります。

Sandbox向けには、別の仕組みがあります。PlaidのAI coding toolkitに含まれるローカルMCPサーバーで、モックデータの生成、ドキュメント検索、Sandboxトークン、Webhookのシミュレーションを担当します。Claudeを含むMCPクライアントのサブプロセスとして動くもので、本稿のDashboard MCPとは役割が違います。

ClaudeのWebとDesktopから接続する手順

Plaidのドキュメントは、Claude.aiのようなホスト型アシスタントには「MCPクライアントの設定にサーバーURLを追加する」方法を案内しています。

カスタムコネクタの一般的な追加手順は、Claudeのサポート記事「Get started with custom connectors using remote MCP」にまとまっています。

ディレクトリと公式ドキュメントの食い違い

Plaidのドキュメントとコネクタのディレクトリで、書かれていることが一致しない点が2つあります。手でURLを入れる場合は、どちらを信じるかを先に決めておきます。

URLの末尾が /mcp/ か /mcp/sse かは、トランスポートの違いを示唆します。ただしどちらの資料も、その理由を説明していません。ディレクトリの「Add to Claude」から入れる場合はURLが自動で設定されるので、気にする必要はありません。迷うのは手入力のときだけで、その場合はPlaid側のドキュメントにある /mcp/ とStreamable HTTPの組み合わせが、記載のある案内です。

ツール数の差も同じ性質です。ドキュメントには plaid_get_tools_introduction という、ツールの使い方を返すツールが載っていますが、ディレクトリの一覧には出ていません。開発中のサーバーなので、差が出てもおかしくありません。実際に何が見えるかは、接続後にClaudeへツール一覧を尋ねるのが確実です。

5つのツールの使い分け

ドキュメントに載っているツールは次の5つです。

実際の調査では、まず plaid_list_teams でチームを特定し、その team_id を他のツールに渡す流れになります。ドキュメントの例でも、plaid_get_link_analytics を呼ぶ前にチーム一覧の取得が走っています。

不具合の切り分けに使うなら

連携の不具合を調べる場面では、見る順番を決めておくと会話が無駄に長くなりません。次の順は、ツールの用途から組んだ一例です。

1. 利用量(plaid_get_usages)で、リクエスト量が急に増減していないかを見る
2. Link(plaid_get_link_analytics)で、どの段階で離脱やエラーが増えたかを見る
3. 特定のユーザーの問題なら、該当Itemを plaid_debug_item で診断する

依頼文は、期間と対象を明示します。ドキュメントの例では、「2025-05-01から2025-05-08までのLink analyticsを取得し、Linkの開始数、金融機関の選択数、ハンドオフ数を返す」という頼み方をしていました。その例のサンプル出力は次のとおりで、Link opens 58、Institution selections 29、Handoffs 18と返っています。これはドキュメント上の例示であり、自分のチームの数値ではありません。

Claude Codeから使う

Claude Codeでは、リモートHTTPサーバーとして追加します。コマンドの形式は、Claude Codeのドキュメントにある claude mcp add --transport http <name> <url> です。

claude mcp add --transport http plaid \
  https://api.dashboard.plaid.com/mcp/

追加後はClaude Code内で /mcp を開き、認証が必要なサーバーの認証を進めます。OAuth 2.0が必要なリモートサーバーの認証には /mcp を使う、とClaude Codeのドキュメントにあります。Plaidのサーバーで、この対話認証が通るかどうかはPlaidのドキュメントに記載がありません。通らない場合は、次節のトークン方式が使えます。

スコープの扱いは、チームで共有するかどうかで変わります。自分だけなら既定のローカルスコープ、チームで共有するなら --scope project で .mcp.json に入れる形です。ただしPlaidの本番データを見られる設定を、リポジトリに入れて全員に配る前には、権限の範囲を確認しておきたいところです。

APIから使う場合のOAuthトークン

自前のアプリがモデルのAPIを呼び、その呼び出しの中でDashboard MCPのツールを使わせる方法もあります。この場合、バックエンドでPlaidのOAuthトークンを作り、モデルAPIにサーバーURLと一緒に渡します。

トークンは mcp:dashboard スコープと client_credentials グラントで、/oauth/token を呼んで作ります。

curl -X POST https://production.plaid.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "client_secret": "YOUR_PRODUCTION_SECRET",
    "grant_type": "client_credentials",
    "scope": "mcp:dashboard"
  }'

レスポンスには、MCPリクエスト用の access_token と、新しいトークンを得るための refresh_token が入ります。MCPサーバーを直接呼ぶときは、Authorization: Bearer ヘッダーにこの access_token を載せます。モデルAPI経由では、渡すフィールド名が提供元ごとに違い、OpenAIは authorization、Anthropicは authorization_token です。Anthropic側の仕組みはMessages APIのMCPコネクタとして提供されています。

トークンは15分で失効する

アクセストークンの有効期間は15分です。切れると、MCPリクエストは 401 か、提供元固有の認証エラーで失敗します。直し方は2つで、新しいトークンを作り直すか、refresh_token で更新します。

curl -X POST https://production.plaid.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "client_secret": "YOUR_PRODUCTION_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "grant_type": "refresh_token"
  }'

15分という短さは、運用に直接響きます。Claude Codeの --header に取得したトークンを貼り付けて固定する使い方では、15分で 401 になります。トークンを使う方式は、実行のたびにトークンを作るバックエンドのコード向きです。ドキュメントのPythonの例も、実行ごとに新しいトークンを作る書き方でした。

シークレットの扱い

client_secret はProductionのシークレットです。会話に貼らず、環境変数から読み込みます。ドキュメントの例も PLAID_CLIENT_ID と PLAID_PRODUCTION_SECRET を環境変数で渡しています。Claudeに「このシークレットでトークンを作って」と値ごと渡す使い方は避け、作成はバックエンドのコードに任せるのが無難です。

つまずいたときの切り分け

接続や実行で止まったとき、症状から原因を絞るための早見表です。原因はいずれもPlaidのドキュメントに書かれた条件から導けるものに限っています。

導入前に決めておきたいこと

最後に、導入を決める前の判断材料を並べます。

Dashboard MCPが扱うのはProductionの診断と分析で、読む作業が中心です。ツール名を見る限り、更新や削除をするものは含まれていません。ただしドキュメントの用途説明に基づく読みで、書き込みの可否を明言した記述はありません。

向いているのは、Plaidを組み込んだアプリの不具合調査を、ダッシュボードを開かずに素早く済ませたい開発者です。反対に、サポートが限定的で破壊的変更もありうるサーバーなので、障害対応の唯一の手段にするのは避けたいところです。ダッシュボードで同じ数字を確認できる状態を残しつつ、会話での調査を補助として使う形が現実的です。

Claudeに任せる範囲を決めるときは、ClaudeのAWS MCPサーバー連携のように、認証方式と権限の線引きを先に決めた記事が参考になります。本番データに触れる連携という点で、考え方が共通します。