carto-basics

carto-basics

CARTO には並行する 2 つのアクセス経路があり、多くのエージェント設定ではいずれか一方、または両方を使用します。

• CARTO MCP Server — Claude.ai、Claude Desktop、ChatGPT などの MCP クライアントを使うチャットベースのエージェントホストで、会話内の作業を行うための主要な経路です。接続すると、データの探索、Builder マップの作成と編集、Workflows の作成と実行、SQL の実行、インポート／エクスポート、組織管理など、幅広く統合されたツール群を利用できます。MCP Apps に対応するホストではマップをインラインでレンダリングし、ユーザーが公開した Workflows を MCP ツールとして動的に登録します。対話形式でのリクエストの大半に対応します。
• CARTO CLI（@carto/carto-cli） — スクリプト、CI/CD、ヘッドレス環境、一括操作や組織をまたぐ操作、詳細な管理や監査（使用状況ログへの SQL 実行など）、および最も充実したコマンド群を利用するための経路です。このカタログにある多くのプラットフォームスキルで使用され、MCP サーバーが接続されていない場合のフォールバックとなります。

他の CARTO スキルを使う前に、このスキルを使用してください。2 つのアクセス経路を検出して使い分ける方法に加え、CLI のインストール、認証、プロファイル、および CLI を使用するスキルが前提とするグローバルフラグを扱います。

このスキルを使用する場面

• 新しいマシンで初めて CLI をセットアップするとき。
• ユーザーから認証エラー（auth status の失敗やトークンの期限切れ）が報告されたとき。
• 組織や環境を切り替えたいとき。
• 後続のスキルで --profile、--json、--token、または --base-url が必要だが、それらの使い方がわからないとき。

事前確認 — CLI 操作の前に実行

CLI を使用するスキルでは、carto CLI が正常に動作し、認証済みであることが前提となります。接続済みの MCP サーバー でリクエストに対応できる場合（データの探索、マップの作成、チャットホストでの Workflows の実行など）は、CLI は不要です。MCP を使ってください。最初の CLI 呼び出しの前に以下の確認を実行し、各タスクの開始時にも再実行してください。一時的なサンドボックス（Claude Code Cowork のタスクなど）では、タスク間で CLI が消去されます。一方、接続済みの MCP サーバーはアカウントレベルで維持されます（下記を参照）。

1. CLI が存在するか？ carto --version を実行します。command not found が表示された場合は、自分でインストールしてください。ユーザーにインストールすることを伝えてから実行し、「ご自身のマシンで実行してください」と突き放してはいけません。npm コマンドと、サンドボックスで必要となる EACCES／書き込み可能なプレフィックスを使うフォールバックについては、references/installation.md を参照してください。
2. 認証済みか？ carto auth status を実行します。認証されていない場合は、ヘッドレスフローの carto auth login --no-launch-browser を使用します。エージェントはブラウザー OAuth を完了できません。ブラウザーを開いたり、そのまま待ったりすることは絶対にしないでください。また、代わりに M2M／API トークンをユーザーに求めることも絶対にしないでください（references/authentication.md）。

インストールまたは認証を完了できない場合は、その旨を伝えて停止してください。Python／SQL／deck.gl など、CARTO 以外のツールに黙ってフォールバックしてはいけません。

このスキルの内容

トピック	リファレンス
CLI のインストール（npm、バージョンの確認）	references/installation.md
認証：ブラウザー、ヘッドレス --no-launch-browser、API トークン、SSO	references/authentication.md
プロファイル：複数の組織／環境の管理	references/profiles.md
グローバルフラグ：--json、--debug、--yes、--token、--base-url、--profile、環境変数	references/global-options.md
アクセス経路：CLI と MCP の使い分け、検出、ホストの対応状況	references/access-paths.md

アクセス方法：MCP サーバーと CLI

MCP サーバーと CLI は異なる目的に対応しており、両方を連携させるフローもあります。MCP サーバーが接続されている場合は、対話型のリクエスト（データの探索、マップの作成と編集、Workflow の構築と実行）には MCP サーバーを優先してください。スクリプト作成、CI/CD、ヘッドレス実行、大量処理や複数組織にまたがる作業、より高度な管理や監査（使用ログのクエリなど）、またはサーバーが接続されていない場合は CLI を使用してください。目的に MCP が適していても、サーバーが接続されていない（またはホストが MCP Apps を表示できない）場合は、該当する場合は CLI に切り替えるか、その不足を明示してください。独自に作成したマップに黙って切り替えてはいけません。CLI は一時的なサンドボックスではタスクごとに初期化されますが、接続された MCP サーバーはアカウントレベルで維持されます。完全なルーティング表、検出シグナル、認証に応じたツールの利用可否については、references/access-paths.md を参照してください。

常時適用されるガイダンス

• 黙って機能を劣化させてはいけません。 CARTO に関するリクエストには CARTO のツールで回答してください。CLI をインストールまたは認証できない場合（あるいは必要な MCP ルートが接続されていない場合）は、障害要因を明示して停止してください。Python、SQL、deck.gl などの汎用的な地理空間処理で代替してはいけません。また、carto auth login --no-launch-browser の代わりに M2M トークンを求めてはいけません。
• 機械可読な出力が必要な場合は、必ず --json を渡してください。 CLI のテキスト出力は人間向けであり、変更される可能性があります。
• マップ URL では、汎用的なワークスペース URL ではなく、auth status のテナントドメインを使用してください。非公開マップは https://{tenant_domain}/builder/{map_id}、公開／共有マップは https://{tenant_domain}/map/{map_id} にあります。マップに対して workspace-{region}.app.carto.com の URL を組み立ててはいけません。ホスト型アプリ（carto app deploy）だけは例外で、https://workspace-{tenant_id}.app.carto.com/app/{slug}/ からのみ配信され、テナントドメイン上の同じパスは機能しません。carto-develop-app を参照してください。
• API ベース URL は https://{tenant_id}.api.carto.com です。auth status --json の tenant_id はリージョン（例：gcp-us-east1）です。tenant_domain にはリージョンが含まれません。
• 確認プロンプト：maps delete などの破壊的なコマンドでは、文字列「delete」の入力を求められます。非対話型で使用する場合は、--yes（または --json）を渡してください。
• 非同期ジョブ：import と sql job は、デフォルトで完了するまでポーリングします。すぐに返すには（対応している場合）、--async を渡して別途ポーリングしてください。