cargo-mcp

Cargo — ホスト型 MCP サーバー

Cargo には 2 つの利用面があります。このバンドルの残りの部分では CLI について説明します。ここでは https://mcp.getcargo.io/mcp と、より重要な点として、どちらをいつ使うべきかを説明します。

ここには MCP と呼ばれるものが 3 つあります。 このスキルは、クライアントの接続先となる、Cargo が運用するホスト型サーバーです。独自のワークスペースから厳選したサーバーを公開する場合（ai mcp-server create、続いて stdio 経由の cargo-ai mcp）と、ほかの人のサーバーを Cargo エージェントに接続する場合（release update-draft --mcp-clients）は、どちらも cargo-ai の範囲です。回答する前に、ユーザーがどれを指しているのか確認してください。呼び方は同じですが、答えに共通点はありません。

どちらを使うか

作業	利用面
1 つのアクションを実行する、または複数レコードに対して 1 つのアクションを実行する	どちらでも可。MCP がすでに接続されている場合は MCP
Cargo でできることと、その費用を調べる	どちらでも可（search_actions は MCP 側の機能です）
モデルからレコードを読み取る	どちらでも可
モデルに対して 1 つの SELECT を実行する（集計、結合）、最大 50 行	どちらでも可（query_models は MCP 側の機能です）
完全な SQL 結果セット、エクスポート	CLI (cargo-storage)
複数ステップのワークフロー、ツール、プレイの作成や編集	CLI (cargo-orchestration)
GTM as Code：プロジェクト計画とデプロイ	CLI (cargo-project)
メールボックスのプロビジョニング、ウォームアップ、送信	CLI (cargo-mailbox-management)
セグメント、コネクター、コンテンツライブラリ、アラート、ホスティング、請求管理	CLI
シェルがまったく使えない場合（ChatGPT、Claude Desktop、claude.ai、n8n）	MCP。対応範囲外のことは明確に伝えてください

表の背後にあるルールは、MCP はランタイムであり、CLI はプラットフォームです。 17 個のツールで、アクションの発見、実行、完了の確認、データの読み戻し、ワークスペースのコンテキストの読み取りを行えます。再利用可能なものを構築する機能はすべて CLI 専用です。両方を使えるエージェントは、ユーザーが再実行またはバージョン管理するものには CLI を、会話内での一度限りの実行には MCP を優先してください。

作業で CLI を使う場合、初期設定はこれだけです。

npm install -g @cargo-ai/cli
cargo-ai login --email [email protected]   # emailed code, no browser; creates the account on first use
cargo-ai whoami                          # confirm the workspace before anything that spends

接続

エンドポイントは Streamable HTTP の https://mcp.getcargo.io/mcp です。認証されていないリクエストは、resource_metadata を含む WWW-Authenticate チャレンジとともに 401 を返します。そのため、OAuth 対応クライアントは認可サーバーを検出して登録し、URL 以外の設定なしでユーザーにプロンプトを表示します。初回接続時の 401 はハンドシェイクであり、障害ではありません。

claude mcp add --transport http cargo https://mcp.getcargo.io/mcp

JSON ブロックを受け取るクライアント（Claude Desktop、Cursor、プロジェクトの .mcp.json）の場合：

{
  "mcpServers": {
    "cargo": {
      "type": "http",
      "url": "https://mcp.getcargo.io/mcp"
    }
  }
}

CI、ヘッドレスエージェント、または OAuth 非対応のクライアントでは、代わりに Settings > API から取得したワークスペーススコープの API トークンを渡してください。環境変数から読み取り、値を直接記述しないでください。

{
  "mcpServers": {
    "cargo": {
      "type": "http",
      "url": "https://mcp.getcargo.io/mcp",
      "headers": { "Authorization": "Bearer ${CARGO_API_TOKEN}" }
    }
  }
}

このエンドポイントが提供するのはプラットフォームツールのみです。 ワークスペースが defineMcpServer で公開した厳選サーバーは別のエンドポイントであり、独自の /v1/ai/mcpServers/<uuid>/mcp URL を使用します。ここではすべてのトークンから同じプラットフォームツールが見えます。どの呼び出しが成功し、search_actions がどのアクションを返すかは、トークンの権限によって決まります。

この柱

whoami                 → which workspace am I in, how many credits
search_actions         → find the action, and read its cost
get_action_schema      → what inputs it takes
autocomplete_action    → resolve a field needing a picked id (HubSpot object type, Slack channel)
execute_action         │ one record
execute_action_batch   │ many records
get_run / get_batch    → poll while outcome is "executing"

データを扱う場合は、list_models → describe_model → query_models の順に実行します。ワークスペースのコンテキスト（読み取り専用）には、map_context、search_context、browse_context、read_context を使います。さらに、list_runs で直近のアドホック実行を一覧表示し、get_usage で過去 7 日間のクレジット消費量をインテグレーション別に確認できます。

セッションは必ず whoami から開始してください。 トークンによってセッションは単一のワークスペースに紐付けられ、上書きするフラグはありません。誤ったワークスペースを指定したセッションは、もっともらしく、自信に満ちた誤った読み取り結果を返します。モデルもレコードも実在しますが、別のユーザーのものです。何かを実行する前に、ワークスペース名をユーザーに伝えて確認してください。

search_actions を使って、実行前に作業の費用を確認してください。 各結果には、下流のすべての処理にそのまま渡す action オブジェクトと並んで、credits[].cost が含まれています。

{
  "name": "Enrich person & find email",
  "credits": [{ "cost": 0.1, "type": "fixed" }],
  "action": {
    "kind": "connector",
    "integrationSlug": "aiArk",
    "actionSlug": "enrichPerson",
    "connectorUuid": "7bb944ec-0254-44bc-b0e4-8a56378e80cf"
  }
}

action オブジェクトは、config キーを付けずに、返されたとおりそのまま渡してください。 入力は data（単一）または records（バッチ）に指定します。config に指定してはいけません。これは ノード の設定であり、トップレベルのアクションには意味がありません。ここに誤って指定された入力は、config を名指しするエラーなしに取り除かれます。必須入力があるアクションは不足フィールドを理由に拒否され、必須入力がないアクションは何も実行せずに終わります。そのため、理由の分からない空の結果が返った場合は、まずこの点を確認してください。data 内またはバッチレコード内のキーのスペルを間違えると、実行前に拒否されます（invalidData、Unknown field: <key>）。ツールアクションは検証されません。

get_action_schema に渡す引数も同じペアです。アクションと、任意の data です。出力が入力に依存するアクションでは、HubSpot のオブジェクトタイプや対象シートによって返されるフィールドが決まります。CLI の orchestration action get-output-schema も同様に動作します。

返される kind 値は 4 種類です。connector（サードパーティのインテグレーション）、native（組み込みのプラットフォーム操作）、tool（このワークスペースに保存されたワークフロー）、agent（このワークスペースの AI エージェント）です。結果の多いカタログは、kind フィルターと integrationSlug フィルターで絞り込んでください。

うまくいかない 3 つの方法

execute_action をレコードごとに実行すること。 レコードごとに 1 回呼び出すと、処理が遅くなり、費用も増え、その後に確認できるものも残りません。execute_action_batch は同じ action と records 配列を受け取り、1 つのバッチオブジェクトを生成します。バッチが完了すると、出力 CSV の 1 ページ分が data.text に返されます（出力列には output_ が付き、行数は 100 行です。truncated が true の間は、次の offset を指定して get_batch を呼び出してください）。URL を取得せず、data.text を読み取ってください。ツールの説明にループしないよう書かれている場合は、その指示に文字どおり従ってください。

見積もりの前に費用をかけること。 まず 10～20 件のレコードで実行してください（execute_action_batch の limit を指定すると、先頭の N 件だけが送信されます）。実測費用とヒット率を報告してから、全 レコード数とクレジットの見積もりを提示し、ユーザーの承認を得てください。人物データのヒット率は 40～70 パーセントなので、有効な 1 行あたりの費用は表示価格とは異なり、サンプルなしでは分かりません。費用管理の全手順については、../cargo-gtm/references/cost-discipline.md を参照してください。

query_models から行をページングして取得すること。 このツールは、dataset.model 参照（describe_model から正確な参照を取得してください）に対して、読み取り専用の SQL SELECT を 1 回実行します。結合と集計は許可されており、最大 50 行（デフォルトは 20 行）を返します。「件数はいくつか」「グループ別ではどうか」「何に結合されているか」には、行を取得して自分で数えるのではなく、SQL の集計で回答してください。行を取得して数えると、上限で結果が黙って切り捨てられます。完全な結果セットが必要な場合は、CLI ジョブを使ってください（cargo-storage）。

人に関わるあらゆること

接点が変わっても、同意に関するルールが緩和されることはありません。誰かの情報を取得、拡充、または連絡するすべての段階で、適法な根拠、配信停止の確認、その人の職務との関連性が条件となります。大量の未承諾メッセージ、購入またはスクレイピングしたリスト、消費者を対象としたターゲティングは拒否されます。全文は ../cargo-gtm/references/acceptable-use.mdにあります。兄弟スキルがインストールされていない場合は、上記の段落が単独で適用されます。

結果の報告

内容を説明し要約してください。生の JSON をユーザーに貼り付けてはいけません。バッチ処理の後は、レコード数、ヒット率、実際に消費したクレジット数、ダウンロードの順に伝えてください。