cargo-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo — the hosted MCP server

Cargo — 托管式MCP服务器

Cargo has two surfaces. The rest of this bundle documents the CLI. This one documents

https://mcp.getcargo.io/mcp

, and, more usefully, when to reach for which.

Three different things here are called MCP. This skill is the hosted server Cargo runs, which you point a client at. Publishing a curated server out of your own workspace (
ai mcp-server create
, then
cargo-ai mcp
over stdio) and attaching somebody else's server to a Cargo agent (
release update-draft --mcp-clients
) are both
cargo-ai
. Check which one the user means before answering: the words are identical and the answers share nothing.

Cargo有两种使用方式。该技能包的其余部分记录了CLI的使用方法，而本文档则介绍

https://mcp.getcargo.io/mcp

，更重要的是介绍何时选择哪种方式。

这里有三种不同的事物都被称为MCP。本技能指的是Cargo运行的托管服务器，你可以将客户端指向该服务器。从自己的工作区发布精选服务器（
ai mcp-server create
，然后通过标准输入输出使用
cargo-ai mcp
），以及为Cargo agent附加他人的服务器（
release update-draft --mcp-clients
），这些操作都属于
cargo-ai
的范畴。在回答前请确认用户所指的是哪一种，因为术语完全相同，但答案毫无关联。

Which surface

选择哪种使用方式

The job	Surface
Run one action, or one action over many records	either; MCP if it is already connected
Find what Cargo can do, and what it costs	either ( `search_actions` is the MCP half)
Read records off a model	either
Warehouse SQL, aggregates, joins	CLI ( `cargo-storage` )
Build or edit a multi-step workflow, tool, or play	CLI ( `cargo-orchestration` )
Workspace as code, plan and deploy	CLI ( `cargo-cdk` )
Provision mailboxes, warm up, send	CLI ( `cargo-mailbox-management` )
Segments, connectors, content libraries, alerts, hosting, billing admin	CLI
No shell at all (ChatGPT, Claude Desktop, claude.ai, n8n)	MCP, and say plainly what is out of reach

The rule underneath the table: MCP is the runtime, the CLI is the platform. Thirteen tools cover discovering an action, running it, watching it finish, and reading data back. Everything that builds something reusable is CLI only. An agent holding both should prefer the CLI for anything the user will want to re-run or version, and MCP for one-shot execution inside a conversation.

When the job routes to the CLI, this is the whole bootstrap:

bash

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

任务类型	使用方式
运行单个操作，或在多条记录上运行单个操作	两者均可；若已连接MCP则优先使用MCP
查找Cargo可执行的操作及对应的成本	两者均可（ `search_actions` 是MCP端的对应操作）
从模型中读取记录	两者均可
数据仓库SQL、聚合、关联操作	CLI（ `cargo-storage` ）
构建或编辑多步骤工作流、工具或剧本	CLI（ `cargo-orchestration` ）
工作区即代码、规划与部署	CLI（ `cargo-cdk` ）
配置邮箱、预热、发送邮件	CLI（ `cargo-mailbox-management` ）
细分、连接器、内容库、告警、托管、账单管理	CLI
完全没有Shell环境（ChatGPT、Claude Desktop、claude.ai、n8n）	MCP，并明确说明无法实现的功能

表格背后的规则：**MCP是运行时，CLI是平台。**有13个工具涵盖了发现操作、运行操作、监控完成状态以及读取返回数据。所有用于构建可复用内容的操作仅支持CLI。同时持有两种方式权限的agent，对于用户希望重新运行或版本化的任务应优先选择CLI，而对话中的一次性执行任务则选择MCP。

当任务需要使用CLI时，以下是完整的引导流程：

bash

npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com   # 邮件发送验证码，无需浏览器；首次使用时创建账户
cargo-ai whoami                          # 在执行任何会消耗资源的操作前确认工作区

Connect

连接服务器

The endpoint is

https://mcp.getcargo.io/mcp

, Streamable HTTP. An unauthenticated request returns

with a

WWW-Authenticate

challenge carrying

resource_metadata

, so an OAuth-capable client discovers the authorization server, registers, and prompts the user with no configuration beyond the URL. A

on first connect is the handshake, not a fault.

bash

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

Any client taking a JSON block (Claude Desktop, Cursor, a project

.mcp.json

json

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

For CI, a headless agent, or a client with no OAuth, pass a workspace-scoped API token from Settings > API instead. Read it from the environment; never inline the value:

json

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

The tool list is not fixed. The endpoint serves the platform tools below plus whatever that workspace published with

defineMcpServer

, so two tokens can see two different lists. Read the list you actually got rather than the one documented here.

端点为

https://mcp.getcargo.io/mcp

，支持流式HTTP请求。未经过身份验证的请求会返回

状态码，并携带包含

resource_metadata

的

WWW-Authenticate

挑战信息，因此支持OAuth的客户端无需额外配置，仅需通过该URL即可发现授权服务器、完成注册并提示用户进行验证。首次连接时返回

是握手流程，而非错误。

bash

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

任何接受JSON配置块的客户端（Claude Desktop、Cursor、项目

.mcp.json

文件）均可使用以下配置：

json

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

对于CI环境、无头agent或不支持OAuth的客户端，可以使用从Settings > API获取的工作区范围API令牌替代。请从环境变量中读取令牌值，切勿直接硬编码：

json

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

**工具列表并非固定不变。**该端点会提供下文列出的平台工具，以及该工作区通过

defineMcpServer

发布的所有工具，因此不同令牌可能看到不同的工具列表。请以实际获取到的列表为准，而非本文档记录的内容。

The spine

核心流程

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"

For data:

list_models

→

describe_model

→

query_models

. Alongside,

list_runs

lists recent ad-hoc runs, and

get_usage

breaks the last 7 days of credit spend down by integration.

Open every session with
whoami
. The token binds the session to exactly one workspace and there is no flag to override it. A session pointed at the wrong workspace returns plausible, confidently wrong reads: the models are real and the records are real, they just belong to somebody else. Name the workspace back to the user before acting on anything.

search_actions
prices the work before you do it. Each result carries

credits[].cost

beside the

action

object you pass verbatim to everything downstream:

json

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

Four

kind

values come back:

connector

(a third-party integration),

native

(a built-in platform operation),

tool

(a saved workflow in this workspace), and

agent

(an AI agent in this workspace). Narrow a noisy catalog with the

kind

and

integrationSlug

filters.

whoami                 → 查看当前所在工作区及可用积分数量
search_actions         → 查找操作并查看其成本
get_action_schema      → 查看操作所需的输入参数
autocomplete_action    → 解析需要选择ID的字段（如HubSpot对象类型、Slack频道）
execute_action         │ 单条记录执行
execute_action_batch   │ 多条记录批量执行
get_run / get_batch    → 轮询操作状态，直到结果变为"executing"之外的状态

数据相关操作流程：

list_models

→

describe_model

→

query_models

。此外，

list_runs

可列出最近的临时运行记录，

get_usage

可按集成类型拆分最近7天的积分消耗情况。

**每次会话开始时先执行

whoami

。**令牌会将会话绑定到唯一的工作区，且无法通过参数覆盖。若会话指向错误的工作区，返回的结果看似合理实则完全错误：模型和记录都是真实存在的，但它们属于其他用户。在执行任何操作前，请向用户确认当前工作区名称。

search_actions

会在执行操作前计算成本。**每个结果都会在

action

对象旁携带

credits[].cost

字段，该

action

对象可直接用于后续所有操作：

json

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

返回结果包含四种

kind

值：

connector

（第三方集成）、

native

（内置平台操作）、

tool

（当前工作区中保存的工作流）、

agent

（当前工作区中的AI agent）。可通过

kind

和

integrationSlug

过滤器缩小工具范围，避免结果过于繁杂。

Three ways this goes wrong

常见错误场景

Fanning out
execute_action
. One call per record is slower, bills more, and leaves nothing to inspect afterwards.

execute_action_batch

takes the same

action

plus a

records

array, produces one batch object, and a finished batch carries a download for its output CSV. The tool description says never to loop it: take that literally.

Spending before quoting. Run 10–20 records first, report the observed cost and hit rate, then quote the full record count and credit estimate and let the user approve. Hit rates on people data run 40 to 70 percent, so cost per usable row is not the sticker price and is not knowable without the sample. Full discipline:

../cargo-gtm/references/cost-discipline.md

query_models
mistaken for SQL. It lists records off one model with a limit and an offset. It does not aggregate, join, or filter by expression. Any question shaped like "how many", "grouped by", or "joined to" is a CLI question (

cargo-storage

). Say so, rather than pulling rows and counting them yourself, which silently truncates at the limit.

**循环调用

execute_action

。**每条记录单独调用一次速度更慢、成本更高，且无法事后查看执行记录。

execute_action_batch

接受相同的

action

参数以及

records

数组，会生成一个批量操作对象，完成后的批量操作会提供输出CSV的下载链接。工具描述明确禁止循环调用

execute_action

，请严格遵守。

未报价即消耗资源。先运行10–20条记录，报告实际成本和命中率，然后根据完整的记录数量和积分估算值进行报价，等待用户确认。人员数据的命中率通常在40%至70%之间，因此可用行的实际成本并非标价，且无法提前得知，必须通过样本测试获取。完整的成本规范请参考：

../cargo-gtm/references/cost-discipline.md

。

**将

query_models

误认为SQL。**该操作仅能列出单个模型中的记录，并支持限制数量和偏移量。它不支持聚合、关联或表达式过滤。任何形如“有多少”“按...分组”或“关联到...”的问题都属于CLI范畴（

cargo-storage

）。请直接告知用户，不要自行提取记录并计数，因为这样会被限制条数截断，导致结果不准确。

Anything that touches a person

涉及人员数据的操作

The consent rules do not relax because the surface changed. A lawful basis, a suppression check, and relevance to that person's job gate every step that sources, enriches, or contacts someone. Bulk unsolicited messaging, purchased or scraped lists, and consumer targeting are refused. The full text is

../cargo-gtm/references/acceptable-use.md

; where no sibling skill is installed, the paragraph above binds on its own.

即使使用方式不同，合规规则也不会放宽。在获取、丰富或联系人员数据的每一步，都必须具备合法依据、完成抑制检查，且操作需与该人员的工作相关。批量发送未经请求的消息、购买或抓取的列表、针对消费者的定向操作均被禁止。完整文本请参考

../cargo-gtm/references/acceptable-use.md

；若未安装相关技能包，则以上段落即为合规约束。

Reporting back

结果反馈

Narrate and summarize; never paste raw JSON at a user. After a batch, give the record count, the hit rate, the credits actually spent, and the download, in that order.

请进行叙述和总结，切勿直接向用户粘贴原始JSON。批量操作完成后，请按以下顺序反馈：记录数量、命中率、实际消耗积分、下载链接。