cargo-mcp

Cargo — 托管式 MCP 服务

Cargo 有两个使用界面。本套文档的其余部分介绍 CLI。本文介绍 https://mcp.getcargo.io/mcp，更重要的是，说明何时该使用哪一个。

这里有三种不同的东西都叫 MCP。 本技能介绍的是 Cargo 运行的托管式服务，客户端连接到它即可。将精选服务从你自己的工作区发布出去（ai mcp-server create，然后通过 stdio 运行 cargo-ai mcp），以及将其他人的服务接入 Cargo Agent（release update-draft --mcp-clients），都属于 cargo-ai。回答前请先确认用户指的是哪一种：它们的叫法完全相同，但答案毫无关联。

选择使用界面

任务	使用界面
执行一项操作，或对多条记录执行同一操作	两者皆可；如果已连接 MCP，则使用 MCP
查找 Cargo 能做什么以及费用	两者皆可（search_actions 是 MCP 对应的工具）
读取模型中的记录	两者皆可
对模型执行一次 SELECT（聚合、联接），最多 50 行	两者皆可（query_models 是 MCP 对应的工具）
完整 SQL 结果集、导出	CLI（cargo-storage）
构建或编辑多步骤工作流、工具或 play	CLI（cargo-orchestration）
以代码管理 GTM：项目计划和部署	CLI（cargo-project）
配置邮箱、预热、发送	CLI（cargo-mailbox-management）
细分受众群、连接器、内容库、警报、托管、账单管理	CLI
完全没有 shell（ChatGPT、Claude Desktop、claude.ai、n8n）	MCP，并明确说明哪些事项无法处理

这张表背后的原则是：MCP 是运行时，CLI 是平台。 十七个工具涵盖发现操作、执行操作、查看操作完成情况、读取数据，以及读取工作区上下文。所有用于构建可复用内容的功能都只能通过 CLI 使用。同时持有两者的 Agent，应优先使用 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

连接

端点是 https://mcp.getcargo.io/mcp，使用 Streamable HTTP。未通过身份验证的请求会返回带有 resource_metadata 的 401 响应和 WWW-Authenticate 挑战，因此支持 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、无头 Agent 或不支持 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 会在执行前为工作估算成本。 每个结果都包含 credits[].cost，位于你传给所有下游操作的 action 对象旁边：

{
  "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 是节点的配置，对顶层 action 毫无意义。放错位置的输入会被移除，且不会报错指出 config：如果 action 有必填输入，会因缺少字段而被拒绝；如果没有必填输入，则会空跑。因此，遇到原因不明的空结果时，值得先检查这一点。data 中拼错的键或批次记录中的拼错键，会在执行前被拒绝（invalidData、Unknown field: <key>）；工具 action 不会经过此项检查。

get_action_schema 接收同样的一对参数：action，以及可选的 data，用于那些输出取决于输入的 action——HubSpot 对象类型或目标工作表会决定返回哪些字段。CLI 的 orchestration action get-output-schema 行为完全相同。

返回结果中有 4 种 kind 值：connector（第三方集成）、native（内置平台操作）、tool（此工作区中已保存的工作流）和 agent（此工作区中的 AI Agent）。若目录结果太多，可用 kind 和 integrationSlug 筛选。

容易出错的三种做法

对 execute_action 扇出调用。 每条记录调用一次会更慢、费用更高，而且事后无从检查。execute_action_batch 接收相同的 action 和一个 records 数组，生成一个批次对象；批次完成后，会在 data.text 中返回一页输出 CSV（输出列以 output_ 为前缀，每页 100 行；只要 truncated 为 true，就用下一个 offset 调用 get_batch）。读取 data.text，不要获取 URL。工具说明明确要求绝不要循环调用，请照做。

报价前先花费额度。 先运行 10–20 条记录（execute_action_batch 接收一个 limit，只会提交前 N 条），报告实际成本和命中率，然后根据完整的记录数和额度估算报价，并让用户批准。人员数据的命中率通常为 40% 到 70%，因此每条可用记录的成本既不是标价，也无法在未抽样前得知。完整规范见： ../cargo-gtm/references/cost-discipline.md。

从 query_models 分页取出行。 它会对 dataset.model 引用执行一条只读 SQL SELECT（使用 describe_model 返回的确切引用），可以进行联接和聚合，最多返回 50 行（默认 20 行）。对于“有多少”“按什么分组”或“与什么联接”等问题，应在 SQL 中使用聚合来回答，绝不要取出行后自行计数，因为结果会在达到上限时静默截断。若要获取完整结果集，请使用 CLI 作业（cargo-storage）。

任何涉及个人的操作

无论接触面如何变化，同意规则都不会放宽。对于所有搜集、丰富或联系某人的步骤，都必须先确认存在合法依据、已检查抑制名单，且操作与该人员的工作相关。拒绝群发未经请求的信息、使用购买或抓取的名单，以及面向消费者的定向营销。完整文本见 ../cargo-gtm/references/acceptable-use.md； 若未安装相关的同级技能，则以上段落本身即具有约束力。

汇报结果

用文字叙述并总结，绝不要向用户粘贴原始 JSON。每批处理完成后，依次提供记录数、命中率、实际花费的积分和下载内容。