トラブルシューティング

Cursor（またはその他の厳格なクライアント）がまったく接続できない

症状：Claude Codeでは同じワークスペースが動作するのに、Cursorなどの厳格なクライアントではサーバーがセッションを確立しません。

原因：サーバーURLの末尾のスラッシュです。https://<your-workspace>.plaid.cloud/mcpを使用してください。.../mcp/ではありません。厳格なクライアントは末尾にスラッシュのあるURLを拒否します（または古いパスが発行していたリダイレクトに従いません）。一方、Claude Codeのような寛容なクライアントは許容します。

対処：設定内のurlから末尾のスラッシュを削除し、再接続します。これらのガイドのすべての例は、スラッシュなしの形式を使用しています。

「failed to Connect」／「session Not Found」

症状：クライアントの設定は正しいように見えるのに、クライアントのMCPステータスパネルでサーバーが失敗と表示されます。サーバーログには404 Session not foundエラーが記録されます。

原因：一部のMCPクライアント（特に、静的なAuthorizationヘッダーを使用するClaude Code 2.1.111）に既知のバグがあり、連続するHTTPリクエスト間でmcp-session-idが保持されません。PlaidCloudのMCPサーバーは、これを回避するためにステートレスHTTPモードで動作します。修正後に再デプロイされていないテナントでこの問題が発生している場合は、管理者に再デプロイを依頼してください。

再デプロイが完了するまでは、クライアント内で別のコードパスを使用するため、OAuthフロー（静的なAuthorizationヘッダーなし）は引き続き動作します。

「application Access Request」ページ

症状：OAuth認可中にPlaidCloudへサインインすると、アプリケーションとリダイレクトURIが表示されるApplication Access Requestというタイトルのページが表示され、フローを続行するには承認をクリックする必要があります。

原因：これは想定どおりの動作です。PlaidCloudのMCPサーバー経由のすべてのOAuth認可で、このページが表示されます。トークンが発行される前に、接続しようとしているものを確認できるようにするためです。このページには、要求元のアプリケーションと、認証情報の送信先となるリダイレクトURIが表示されます。どちらも実際に接続しようとしているクライアントと一致することを確認し、自分で開始していないリクエストは承認しないでください。

すでに接続済みのクライアントでは、トークンの更新時にこのページは再表示されません。再表示されるのは、新たな認可（初回接続、または更新トークンの期限切れや失効の後）のときだけです。

対処：修正すべき点はありません。ページを承認して続行してください。あるブラウザー（またはプロファイル）で認可を開始し、別のブラウザーでページが表示されている場合は、完了しません。同意は、フローを開始したブラウザーに紐付けられているためです。PlaidCloudにサインインしているのと同じブラウザーから認可をやり直してください。

Claude Codeのログイン中に「oauth Flow is Not in Progress」と表示される

症状：ブラウザーで認可し、コールバックURLをClaude Codeに貼り付けると、進行中のフローがないと表示されます。

原因：ブリッジのメモリ内のOAuth状態はポートごとに保持され、authenticateとcomplete_authenticationのツール呼び出しの間に失われることがあります。特に、ブラウザーのコールバックがlocalhostに到達できないリモート／SSHセッションで発生します。

対処：静的Bearerフローに切り替えます。PlaidCloudにサインインしているブラウザーでhttps://<your-workspace>.plaid.cloud/mcp/setup/tokenを開き、スニペットを.mcp.jsonにコピーして、Claude Codeを再起動します。

トークンの期限切れ

症状：昨日まで動作していたツールが401 Unauthorizedを返すようになります。

原因：静的Bearerトークンは、Keycloakレルムのアクセストークン有効期間ポリシー（通常は数時間から1日）に従います。

対処：https://<your-workspace>.plaid.cloud/mcp/setup/tokenを再読み込みして新しいトークンを発行し、設定に貼り付けます。長期間のセッションにはOAuthをお勧めします。OAuthに対応しているクライアントは、トークンを自動的に更新します。

「no access_token in Session」

症状：PlaidCloudにサインインしているにもかかわらず、/mcp/setup/tokenを開くと「Sign-in required」または「No access_token in session」と表示されます。

原因：Keycloakトークンをキャッシュしないサインイン経路でセッションが確立されました（まれですが、起こり得ます）。

対処：PlaidCloudからサインアウトし、標準のログインページから再度サインインします。新しいセッションにはアクセストークンが含まれます。

ツールが見つからない、またはカタログが不完全

症状：mcp_introspectが想定より少ないツールしか返さない、または必要な特定のツールがありません。

原因1（スコープ）：ツールには特定のPlaidCloudスコープ（例：analyze.workflow.write）が必要です。アカウントにスコープがない場合、ツールは実行を拒否します。mcp_introspect(name='<tool>')を実行してrequired_scopesを確認してください。ワークスペースの管理者にスコープの付与を依頼するか、そのスコープを持つアカウントで操作を実行してください。

原因2（バージョンの不一致）：古いデプロイメントには、最新のドキュメントに記載されているすべてのツールが含まれていない場合があります。mcp_introspect()のツール数を現在のバージョンのリリースノートと比較し、必要に応じて再デプロイを依頼してください。

マルチテナント：エージェントはどのテナントにアクセスしたか

症状：複数のPlaidCloudテナントを設定していて、エージェントの応答がどのテナントから返されたものか判別できません。

対処：プロンプトにテナントを明示します（「devテナントで、ワークフローを一覧表示して…」など）。設定で付けたMCPサーバー名（例：plaidcloud-prod、plaidcloud-dev）も、モデルが区別するための識別子として機能します。重要な操作では、実際に必要になるまで、コネクターピッカーで本番をオフにしておいてください。

レート制限とクォータ

PlaidCloudのREST APIは、UIの前段にあるのと同じミドルウェアによって、1分あたりのリクエスト数でレート制限されています。MCP呼び出しもこの制限を共有します。エージェントがfind呼び出しを大量に連続して送信すると（たとえば、すべてのプロジェクト、ワークフロー、ステップを列挙しようとした場合）、制限に達することがあります。サイズの確認には、結果セット全体を取得する代わりに、ページネーション（cursor、limit）とcount_only=Trueを使用してください。

findはデフォルトで1ページあたり25行を返す（step_findは50行）ため、大きなセットを列挙するには、以前より多くの呼び出しが必要になります。意図的に全件を調べる場合は、デフォルトのままページングするのではなく、limitを引き上げてください。逆に、何度も制限に達する場合は、count_only=Trueとより絞り込んだfields=[...]による射影を使えば、全件を調べる必要がなかったことが多いでしょう。

リストが短い、またはエージェントが「これで全部です」と言う

症状：findが想定より少ない行しか返さなかった、またはプロジェクトに300個のテーブルがあるのに、エージェントが25個だと結論付けました。

対処：エンベロープを確認します。ページが上限で切り捨てられた場合はnext_cursorが設定され、findツールは切り捨てられたリストをtruncatedにも示します。どちらも、取得すべき続きがあることを意味します。totalは常に全件数を報告するため、取得した行数と比較してください。エージェントにカーソルでページングするよう依頼するか、より大きなlimitで再実行してください。

結果が{"_fmt": "cols", ...}のように見える

症状：ツールが、想定していたオブジェクトのリストではなく、{"_fmt": "cols", "cols": [...], "rows": [[...]]}を返しました。

これは、すべての行が同じフィールドを持つ大きな結果に対する想定どおりの形式です。フィールド名は行ごとに繰り返されず、1回だけ送信されます。行iはdict(zip(cols, rows[i]))です。エージェントには接続時にこの形式が通知されるため、プロンプトなしで処理されます。これらの応答を自分のコードで読み取る場合は、小規模なものや不揃いなものは従来どおりオブジェクトの配列で返されるため、両方の形式をデコードしてください。エンベロープのその他の部分は変わらず、値も変更されません。AIコーディングエージェントを始めるを参照してください。

ヘルプの利用

認証の失敗、原因が不明なエラーを返すツール、ツールの欠落といったサーバー側の問題については、まずレスポンスのerrorエンベロープを確認してください。すべての失敗にはcode、retryable、messageが含まれ、多くの場合hintも含まれます。ヒントだけでは解決しない場合は、PlaidCloudの管理者に連絡するか、リクエストID（X-Request-Idレスポンスヘッダーで返されます）を添えてサポートチケットを作成してください。