AIコーディングエージェントを使い始める

最も簡単な接続方法は、PlaidCloud 内で行う方法です。ヘッダーのツールバーでライト／ダークテーマの切り替えのすぐ左にある AIを接続 をクリックし、使用するクライアントを選んで、表示される手順に従ってください。ワークスペースのMCPサーバーのURLは、あらかじめ入力された状態で表示されます。このボタンは、ワークスペースでAI機能が有効になっている場合に利用できます。このページと、続くクライアント別のページは引き続きリファレンスとして使えます。Web UIを使っていない場合や、認証とサーバーが公開する機能の全体像を知りたい場合は、このまま読み進めてください。

MCPサーバーとは

Model Context Protocol（MCP）は、AIエージェントが外部のツールやデータとやり取りするためのオープン標準です。PlaidCloud はすべてのワークスペースでMCPサーバーを実行しています。このサーバーは REST API と同じコアヘルパーをラップし、意図（find、describe、upsert、run、organize）ごとにまとめているため、エージェントは1,000を超える低レベルのRPCメソッド名を読み込まなくても操作できます。

サーバーは次の場所にあります。

https://<your-workspace>.plaid.cloud/mcp

<your-workspace> は、ワークスペースのサブドメイン（PlaidCloud UIへのログインに使っているもの）に置き換えてください。

公開される機能

カタログは、エージェントが日常的に必要とする操作の大部分をカバーしています。

• プロジェクト、ワークフロー、ステップ — 検索、詳細取得、アップサート、実行、整理。ステップ単位の再実行やバージョン履歴にも対応しています。
• テーブル、ビュー、クエリ — スキーマの確認、クエリの実行、エクスポート、スナップショット、ブランチ。ビューは、テーブルエクスプローラーで作成したものでもワークフローが作成したものでも、PlaidCloud で表示されるものと同じです。
• ディメンション — 詳細取得、検索、アップサート、バージョン管理、ノード／エイリアス／プロパティの管理。
• 接続 — 外部システムへの接続の検索、アップサート、テスト。
• Lakehouse — ブランチ、スナップショット、最適化／バキューム操作。
• ID — メンバー、グループ、セッション、配布リスト。
• ドキュメント、ダッシュボード、UDF、エディター、エージェント、公開 — ドメイン固有のツール。
• ワークフローの移行 — ドキュメントにステージングされたAlteryx（alteryx_convert）、KNIME（knime_convert）、Prophecy（prophecy_convert）、Savant（savant_convert）のエクスポートをPlaidCloudのワークフローに変換し、ポートフォリオ移行作業を調整します。
• PlaidCloudのドキュメント — docs_search はキーワードでPlaidCloudのドキュメントのページを検索し、docs_fetch はページ全体を読み取ります。エージェントは、機能を使って構築する前にその仕組みを確認できます。
• ワークフローのログと実行の追跡 — workflow_logs、workflow_run_status、workflow_job_track。

すべてのツールは統一されたエンベロープ {ok, data, next_cursor?, total?} を返します。失敗時は {ok: false, error: {code, retryable, message, hint?}} を使います。変更操作は dry_run=True を受け付け、書き込みを行わずに計画だけを検証できます。

結果を小さく保つ

ツールの結果はエージェントのコンテキストの中で最大の消費要因であるため、検索ツールと詳細取得ツールはデフォルトで控えめな範囲だけを返し、必要に応じて広げられるようになっています。

• 行。 検索は1ページあたり25件を返します（step_find は50件）。上限で切られたページには next_cursor が設定され、検索ツールはさらに切り詰められたリストの名前を truncated に示します。どちらも「まだ続きがある」ことを意味し、「これですべて」という意味ではありません。total は常に全件数を報告します。limit を増やすか、カーソルでページを送ってください。
• 列。 fields=['id', 'name', 'update_time'] を渡すと、それらの列だけが返されます。どのレコードにも存在しないフィールド名はエラーとなり、利用可能なフィールドが一覧表示されます。黙って結果が減るのではなく、入力ミスがはっきり失敗として表れます。厳選されたセットを提供するツールは field_set='minimal' | 'default' | 'full' も受け付けます。各ツールが受け付けるパラメーターは mcp_introspect を呼び出して確認してください。
• 件数。 count_only=True を指定すると、結果セットを取得せずにその大きさだけを調べられます。

リクエストのバッチ処理

mcp_batch は、複数のツール呼び出しを1つのリクエストにまとめます。最大100件の呼び出しを受け付け、同時に実行する数には上限があります。別の mcp_batch やレシピの中に入れ子にすることはできません。代わりに呼び出しを1つのフラットなバッチに並べてください。送信コストは変わりません。上限を超えたバッチは、黙って切り詰められずに、その旨を示すメッセージとともに拒否されます。この上限は1回のリクエストが開始できる処理量を制限するもので、実行できる処理の総量を制限するものではないため、大きなジョブは複数のバッチに分割してください。

paginate_through_listing レシピは、max_pages にいくら大きな値を渡しても200ページで停止し、途中で停止した場合は partial: true を報告します。この上限と max_items の上限により、1回のページ送り呼び出しは必ず終了します。

レシピは、認識できない params キーを拒否し、そのレシピが受け付けるキーをメッセージに一覧表示します。そのため、オプションのパラメーターを綴り間違えても黙って無視されることはなく、意図した質問とは別の質問に答えてしまう事態を防げます。各レシピが受け取るキーは mcp_recipes(name=...) を呼び出して確認してください。

列指向の結果

すべての行が同じフィールドを持つ大きな結果は、オブジェクトのリストではなく列指向で返されます。そのため、フィールド名は行ごとではなく1回だけ送信されます。

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

i 行目は dict(zip(cols, rows[i])) です。小さな結果や、行のフィールド構成が完全には一致しない結果は通常のオブジェクトの配列のままなので、どちらの形式も現れます。これらのレスポンスを直接読み取るコードは、両方を処理する必要があります。外側のエンベロープは変わらず、値が変換されたり丸められたりすることもありません。エージェントは接続時にこの形式について通知され、ユーザーが何も指示しなくても読み取れます。一般的な一覧のやり取りでは、文字数でおよそ30%、エージェントの読み取り予算でおよそ15%が節約され、その分のコンテキストを本来の質問に使えます。（2つの数値が異なるのは、繰り返されるフィールド名がモデルにとって読み取りやすいためで、文字数の節約は常に大きくなります。）

最新のカタログを確認するには、エージェントをサーバーに向けて mcp_introspect（引数なし）を呼び出してください。現在のツール数、ドメインごとの概要、パラメーターのシグネチャが返されます。複数のツールを組み合わせる定番の手順（大きなリストのページ送り、スナップショットしてから変更、失敗したステップの再実行など）には mcp_recipes を使ってください。

ラベルとビュー

ラベルを設定するすべてのアップサートツール（テーブル、ワークフロー、ステップ、プロジェクト、ディメンション、ビュー、エディター、UDF、接続、ウェアハウス）は、2つのパラメーターを受け付けます。labels はラベルを追加し、remove_labels はラベルを削除します。オブジェクトに付いているそのほかのラベルは残ります。削除は追加より先に適用されるため、1回の呼び出しでラベルの名前を変更できます。

{"remove_labels": ["01"], "labels": ["001"]}

オブジェクトが持っていないラベルを削除しても、何も起こりません。

ビューツールは、PlaidCloud で表示されるビューを操作します。

• view_find はビューを一覧表示し、view_describe はIDまたは名前でビューを1つ返します。
• view_upsert はビューを作成するか、既存のビューをその場で更新します。更新してもビューのIDとラベルは保持され、クエリを再送せずにラベルだけを変更することもできます。
• view_organize はビューの削除、名前の変更、複製、移動を行います。
• クエリパラメーターは %(name)s のプレースホルダーとして記述します。

ビューはテーブルのフォルダーツリーを共有しているため、そのフォルダーの管理には table_organize を使ってください。

タスクスターター

サーバーには、よく名前を挙げて依頼されるタスク向けの小さなスターターのセットが付属しています。MCPプロンプトに対応するクライアントはそれらを一覧表示し、メニューとして提供します。表示される場所はクライアントのドキュメントで確認してください。ツール呼び出しの手順を自分で説明する代わりに、タスクを選ぶだけで済みます。

スターター	渡す内容
CSVファイルをテーブルにインポートする	ファイル。必要に応じて、プロジェクト、ファイルのあるフォルダー、新しいテーブルの名前
コストの変動を説明する	結果テーブル。必要に応じて、プロジェクトと比較する2つの期間
失敗したワークフローをデバッグする	ワークフロー。必要に応じて、プロジェクト
プロジェクトのデータを調べる	探している内容。必要に応じて、プロジェクト

それぞれは命令ではなく開始メッセージです。エージェントがそれを読み、ツールを自分で操作するため、メッセージを編集することも、そこから会話を続けることもできます。

オブジェクトモデルを知らなくてもファイルをインポートする

インポートのスターターは、最も手間を省いてくれます。素朴な方法では、ドキュメントアカウントを探し、ファイルまで移動し、ターゲットテーブルを作成し、最後にインポートを実行するという4つのツールを正しい順序で使う必要があり、どれか1つでも推測を誤ると、数回の呼び出しを経たところで流れが止まってしまうからです。

読み取れるのは、CSV、TSVなどの区切りテキストです。ExcelのブックやParquetファイルは、誤って読み取られることなく拒否されます。それらは、ワークフローで対応するインポートステップを使って取り込んでください。

そこで bulk_import_csv プレイブックは、アカウントを名前で、ファイルを名前またはパスで受け取ります。

mcp_recipe_run(name='bulk_import_csv', params={
    'project_id': '<project>',
    'document_path': 'sales_2026.csv',
    'document_account': 'Demo Data',
})

プレイブックはアカウントを識別子に解決し、ファイルを見つけ、ファイル自体から読み取った列と型でテーブルを作成して読み込みます。そのため、アカウントIDも列の仕様も指定する必要がありません。table_name のデフォルトは拡張子を除いたファイル名で、table_path のデフォルトはプロジェクトのルートです。

フォルダーがわかっている場合は 'document_path': 'raw/sales_2026.csv' のように指定してください。検索はそのフォルダー内に限定されます。フォルダーを指定したファイルはそのフォルダー内だけで照合され、さらに下の階層にある同名のファイルは、代わりにインポートされるのではなく、選択肢として提示されます。

引数があいまいな場合、結果は推測せずに質問を返します。

{
  "needs_choice": "document_account",
  "question": "More than one document account is named 'Archive'. Which one?",
  "candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]
}

候補を支援している相手に提示し、その回答を、渡されたとおりそのままの形で候補として渡して、プレイブックをもう一度呼び出してください。ファイルが見つからない場合、返信には最も近い名前が一覧表示され、検索したファイルの数も報告されるため、「そこにない」ことと「探した場所にない」ことを区別できます。

ノート

ファイル名だけを指定した場合は、すべてのアカウントタイプが検索対象になり、フォルダーで絞り込まないとアカウント全体が検索されます。オブジェクトストアのアカウント（S3、Wasabi、GCS）では、一覧取得が1回で済みます。OneDrive、SFTP、Azure Blobでは、最初の一覧取得が1階層分しかカバーしないため、検索はより深い階層に対して2回目のパスを実行します。フォルダーやフルパスがわかっている場合は、必ず指定してください。数万件のファイルを持つアカウントでは、ファイル名だけの検索は著しく遅くなります。

認証

PlaidCloud のMCPサーバーは、2つの認証方法を受け付けます。

1. 動的クライアント登録（DCR）によるOAuth 2.1 + PKCE。 これは Claude.ai のカスタムコネクターUIが使用する方法で、Claude Code のMCPブリッジでもデフォルトです。クライアントが自分自身を登録し、PlaidCloud の Keycloak ログインにリダイレクトします。サインイン後、PlaidCloud は、アプリケーション名と、認証情報の送信先となるリダイレクトURIを示す アプリケーションアクセスのリクエスト ページを表示します。認可ごとに1回承認してトークンを取得してください。これは形式的なものではなく、セキュリティ上の制御です。アプリケーション名とリダイレクトURIが実際に接続しようとしているクライアントと一致していることを確認し、自分で開始していないリクエストは承認しないでください。
2. Authorization ヘッダーの静的ベアラートークン。 利用可能なブラウザーのリダイレクトがないエージェントランタイムや、設定ファイルに長期間有効なトークンを置きたい場合に使います。PlaidCloud は、トークンを発行するヘルパーページを提供しています（後述）。

静的ベアラートークンを取得する

PlaidCloud にすでにサインインしているブラウザーのタブで、次のURLを開きます。

https://<your-workspace>.plaid.cloud/mcp/setup/token

ページには、エージェントのMCP設定にそのまま貼り付けられるJSONスニペットが表示されます。スニペットはワークスペースごとに異なります。

トークンの有効期間は、Keycloak レルムのアクセストークン有効期間のポリシーによって決まります（通常は数時間から1日）。更新するには同じURLを再読み込みしてください。ブラウザーのセッションによってトークンが自動的に再発行されます。

ノート

この方法は、使い始めの段階や、OAuthのリダイレクトを完了できないクライアント向けです。本番環境での長期的なエージェントアクセス（サービスアカウント、CIランナー、スケジュールされたジョブなど）には、クライアントが対応している場合はOAuthを使用してください。パーソナルアクセストークンは計画中ですが、まだ一般提供されていません。

クライアントを選ぶ

このセクションの以降のページでは、特定のAIエージェントクライアントの設定手順を説明します。

• Claude Code — Anthropic のコーディングエージェント（CLI、VSCode拡張機能、JetBrainsプラグイン）。
• Claude Desktop と Claude.ai — 「カスタムコネクター」を使用する、コンシューマー向けの Claude アプリ（デスクトップ）とWeb（claude.ai）。
• Cursor — AIネイティブのコードエディター。
• GitHub Copilot — VSCode の Copilot エージェントモード。
• Google Gemini CLI — gemini-cli と Gemini Code Assist。
• ChatGPT — 現在のサポート状況と推奨される回避策。
• Grok — Grok のカスタムコネクターの接続。
• トラブルシューティング — よくあるエラーとその対処方法。