コンテンツにスキップ

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

最も手早く接続する方法は、PlaidCloud の中から行うことです。アバター(ユーザー)メニューを開いて AIを接続を選び、使用するクライアントを選択して、表示される手順に従います。ワークスペースの MCP サーバーの URL も、すでに入力された状態で表示されます。これは、ワークスペースで AI の使用権限が有効になっている場合に利用できます。このページの残りの部分と、これに続くクライアント別のページは、引き続きリファレンスとして利用できます。Web UI を使っていない場合や、認証とサーバーが公開する内容の全体像を知りたい場合は、読み進めてください。

Model Context Protocol は、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 を指定すると、結果セットを取得せずにそのサイズを調べられます。

不明なフィールドは拒否される

Section titled “不明なフィールドは拒否される”

project_upsert や workflow_upsert のようなツールが受け取る spec は、一覧にあるフィールドだけを受け付けます。認識できないフィールドは、無視されて何も起きなかったことにあとで気づく、という状況にはならず、そのフィールド名を示すエラーで拒否されます。名前を修正して、リクエストをもう一度送信してください。workflow_upsert は、ワークフローの説明を memo として受け取り、description も別名として受け付けます。

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 を使用します。

ネイティブステップでワークフローを構築する

Section titled “ネイティブステップでワークフローを構築する”

データが PlaidCloud に入ったら、エージェントは、SQL抽出ステップではなく、ネイティブのテーブルステップ(Table Extract、結合ステップ、Table Melt、Table Union All、Table Lookup の各ステップ)で各変換を構築するよう誘導されます。ネイティブステップは、フィルターと式の中の変数を値に置き換え、PlaidCloud はその SQL をプロジェクトのウェアハウス向けに生成します。SQL抽出ステップは、クエリを記述どおりにウェアハウスへ送ります。変数は置き換えられず、SQL は 1 つのウェアハウス向けに記述されます。

エージェントは、query_run(mode='config') で Table Extract の設定を試し、ステップを保存する前に行を確認できます。この設定は、step_upsert で保存する設定と同じです。SQL抽出ステップを保存すると、step_upsert は、代わりに使うネイティブステップを示す prefer_native_steps エントリを config_warnings に返し、describe_step_operation にも同じ注記が含まれます。SQL抽出は、どのネイティブステップでも表現できないものに引き続き使用できます。

サーバーには、よく依頼されるタスクのための小さなスターターのセットが付属しています。MCP プロンプトをサポートするクライアントでは、それらが一覧表示され、メニューとして提示されます。どこに表示されるかは、お使いのクライアントのドキュメントを確認してください。これにより、ツール呼び出しの手順を説明するのではなく、タスクを選ぶだけで済みます。

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

それぞれは、コマンドではなく最初のメッセージです。エージェントはそれを読み、そこからツールを自分で操作するため、編集したり、そこから会話を続けたりできます。

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

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

インポートのスターターは、最も手間を省きます。単純な方法では、ドキュメントアカウントを見つける、ファイルまで移動する、ターゲットのテーブルを作成する、インポートを実行する、という 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 に解決し、ファイルを見つけ、ファイル自体から読み取った列と型でテーブルを作成して、ロードします。そのため、アカウント 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"}]
}

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

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

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

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

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

このページは、エージェントの MCP 構成に貼り付けられる JSON スニペットを返します。スニペットはワークスペースごとに異なります。

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

このセクションの残りでは、特定の 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 のカスタムコネクタの接続。
  • トラブルシューティング — よくあるエラーと、その解決方法。