Update to Cargo CLI

{
  "name": "cargo-mcp",
  "description": "Drive Cargo from its hosted MCP server at https://mcp.getcargo.io/mcp — connect a client, discover and price an action, run it over one record or a batch, poll it, and read workspace models, with no CLI install. Also when to call an MCP tool instead of shelling out to `cargo-ai`. Triggers: \"connect Cargo to Claude Desktop\", \"add Cargo to ChatGPT\", \"Cargo MCP server\", \"mcp.getcargo.io\", \"use Cargo without installing anything\", \"which Cargo tool do I call\", \"search_actions\", \"execute_action_batch\", \"MCP server is showing the wrong workspace\". Tools: whoami, search_actions, get_action_schema, execute_action, execute_action_batch, get_run, query_models. Skip when: you have a shell and the job is a workflow, a CDK deploy, or warehouse SQL — use the CLI skills; when publishing an MCP server out of your own workspace or attaching one to a Cargo agent — use cargo-ai.",
  "included_files": [
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 426
    }
  ],
  "skill_md_contents": "---\nname: cargo-mcp\ndescription: \"Drive Cargo from its hosted MCP server at https://mcp.getcargo.io/mcp — connect a client, discover and price an action, run it over one record or a batch, poll it, and read workspace models, with no CLI install. Also when to call an MCP tool instead of shelling out to `cargo-ai`. Triggers: \\\"connect Cargo to Claude Desktop\\\", \\\"add Cargo to ChatGPT\\\", \\\"Cargo MCP server\\\", \\\"mcp.getcargo.io\\\", \\\"use Cargo without installing anything\\\", \\\"which Cargo tool do I call\\\", \\\"search_actions\\\", \\\"execute_action_batch\\\", \\\"MCP server is showing the wrong workspace\\\". Tools: whoami, search_actions, get_action_schema, execute_action, execute_action_batch, get_run, query_models. Skip when: you have a shell and the job is a workflow, a CDK deploy, or warehouse SQL — use the CLI skills; when publishing an MCP server out of your own workspace or attaching one to a Cargo agent — use cargo-ai.\"\nversion: \"1.0.1\"\ncompatibility: Requires the hosted Cargo MCP server at https://mcp.getcargo.io/mcp — OAuth (discovered from the 401 challenge) or a workspace-scoped API token as a bearer. The CLI is needed only for the jobs this skill routes away\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo — the hosted MCP server\n\nCargo has two surfaces. The rest of this bundle documents the CLI. This one\ndocuments `https://mcp.getcargo.io/mcp`, and, more usefully, **when to reach for\nwhich.**\n\n> **Three different things here are called MCP.** This skill is the **hosted\n> server Cargo runs**, which you point a client at. Publishing a curated server\n> *out of* your own workspace (`ai mcp-server create`, then `cargo-ai mcp` over\n> stdio) and attaching somebody else's server *to* a Cargo agent\n> (`release update-draft --mcp-clients`) are both\n> [`cargo-ai`](../cargo-ai/SKILL.md). Check which one the user means before\n> answering: the words are identical and the answers share nothing.\n\n## Which surface\n\n| The job | Surface |\n| --- | --- |\n| Run one action, or one action over many records | either; MCP if it is already connected |\n| Find what Cargo can do, and what it costs | either (`search_actions` is the MCP half) |\n| Read records off a model | either |\n| Warehouse SQL, aggregates, joins | **CLI** ([`cargo-storage`](../cargo-storage/SKILL.md)) |\n| Build or edit a multi-step workflow, tool, or play | **CLI** ([`cargo-orchestration`](../cargo-orchestration/SKILL.md)) |\n| Workspace as code, plan and deploy | **CLI** ([`cargo-cdk`](../cargo-cdk/SKILL.md)) |\n| Segments, connectors, content libraries, alerts, hosting, billing admin | **CLI** |\n| No shell at all (ChatGPT, Claude Desktop, claude.ai, n8n) | **MCP**, and say plainly what is out of reach |\n\nThe rule underneath the table: **MCP is the runtime, the CLI is the platform.**\nThirteen tools cover discovering an action, running it, watching it finish, and\nreading data back. Everything that *builds* something reusable is CLI only. An\nagent holding both should prefer the CLI for anything the user will want to\nre-run or version, and MCP for one-shot execution inside a conversation.\n\nWhen the job routes to the CLI, this is the whole bootstrap:\n\n```bash\nnpm install -g @cargo-ai/cli\ncargo-ai login --email you@company.com   # emailed code, no browser; creates the account on first use\ncargo-ai whoami                          # confirm the workspace before anything that spends\n```\n\n## Connect\n\nThe endpoint is `https://mcp.getcargo.io/mcp`, Streamable HTTP. An\nunauthenticated request returns `401` with a `WWW-Authenticate` challenge\ncarrying `resource_metadata`, so an OAuth-capable client discovers the\nauthorization server, registers, and prompts the user with no configuration\nbeyond the URL. A `401` on first connect is the handshake, not a fault.\n\n```bash\nclaude mcp add --transport http cargo https://mcp.getcargo.io/mcp\n```\n\nAny client taking a JSON block (Claude Desktop, Cursor, a project `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"cargo\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.getcargo.io/mcp\"\n    }\n  }\n}\n```\n\nFor CI, a headless agent, or a client with no OAuth, pass a workspace-scoped API\ntoken from **Settings > API** instead. Read it from the environment; never inline\nthe value:\n\n```json\n{\n  \"mcpServers\": {\n    \"cargo\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.getcargo.io/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer ${CARGO_API_TOKEN}\" }\n    }\n  }\n}\n```\n\n**The tool list is not fixed.** The endpoint serves the platform tools below\nplus whatever that workspace published with `defineMcpServer`, so two tokens can\nsee two different lists. Read the list you actually got rather than the one\ndocumented here.\n\n## The spine\n\n```\nwhoami                 → which workspace am I in, how many credits\nsearch_actions         → find the action, and read its cost\nget_action_schema      → what inputs it takes\nautocomplete_action    → resolve a field needing a picked id (HubSpot object type, Slack channel)\nexecute_action         │ one record\nexecute_action_batch   │ many records\nget_run / get_batch    → poll while outcome is \"executing\"\n```\n\nFor data: `list_models` → `describe_model` → `query_models`. Alongside,\n`list_runs` lists recent ad-hoc runs, and `get_usage` breaks the last 7 days of\ncredit spend down by integration.\n\n**Open every session with `whoami`.** The token binds the session to exactly one\nworkspace and there is no flag to override it. A session pointed at the wrong\nworkspace returns plausible, confidently wrong reads: the models are real and\nthe records are real, they just belong to somebody else. Name the workspace back\nto the user before acting on anything.\n\n**`search_actions` prices the work before you do it.** Each result carries\n`credits[].cost` beside the `action` object you pass verbatim to everything\ndownstream:\n\n```json\n{\n  \"name\": \"Enrich person & find email\",\n  \"credits\": [{ \"cost\": 0.1, \"type\": \"fixed\" }],\n  \"action\": {\n    \"kind\": \"connector\",\n    \"integrationSlug\": \"aiArk\",\n    \"actionSlug\": \"enrichPerson\",\n    \"connectorUuid\": \"7bb944ec-0254-44bc-b0e4-8a56378e80cf\"\n  }\n}\n```\n\n**Pass that `action` object exactly as it comes, with no `config` key.** Inputs\nbelong in `data` (single) or `records` (batch); this surface never wants a\n`config`, and `get_action_schema` supplies the empty one the backend needs on\nyour behalf. That is one place MCP is *safer* than the CLI, where the sibling\ncommand `orchestration action get-output-schema` still rejects a config-less\naction with a `400`. Inputs misplaced into `config` are silently dropped and the\naction runs with none, so an unexplained empty result is worth checking here\nfirst.\n\nFour `kind` values come back: `connector` (a third-party integration), `native`\n(a built-in platform operation), `tool` (a saved workflow in this workspace),\nand `agent` (an AI agent in this workspace). Narrow a noisy catalog with the\n`kind` and `integrationSlug` filters.\n\n## Three ways this goes wrong\n\n**Fanning out `execute_action`.** One call per record is slower, bills more, and\nleaves nothing to inspect afterwards. `execute_action_batch` takes the same\n`action` plus a `records` array, produces one batch object, and a finished batch\ncarries a download for its output CSV. The tool description says never to loop\nit: take that literally.\n\n**Spending before quoting.** Run **10–20 records** first, report the observed\ncost and hit rate, then quote the full **record count** and **credit estimate**\nand let the user approve. Hit rates on people data run 40 to 70 percent, so cost\nper *usable* row is not the sticker price and is not knowable without the\nsample. Full discipline:\n[`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md).\n\n**`query_models` mistaken for SQL.** It lists records off one model with a limit\nand an offset. It does not aggregate, join, or filter by expression. Any\nquestion shaped like \"how many\", \"grouped by\", or \"joined to\" is a CLI question\n([`cargo-storage`](../cargo-storage/SKILL.md)). Say so, rather than pulling rows\nand counting them yourself, which silently truncates at the limit.\n\n## Anything that touches a person\n\nThe consent rules do not relax because the surface changed. A lawful basis, a\nsuppression check, and relevance to that person's job gate every step that\nsources, enriches, or contacts someone. Bulk unsolicited messaging, purchased or\nscraped lists, and consumer targeting are refused. The full text is\n[`../cargo-gtm/references/acceptable-use.md`](../cargo-gtm/references/acceptable-use.md);\nwhere no sibling skill is installed, the paragraph above binds on its own.\n\n## Reporting back\n\nNarrate and summarize; never paste raw JSON at a user. After a batch, give the\nrecord count, the hit rate, the credits actually spent, and the download, in\nthat order.\n"
}