MCP servers

Cargo speaks Model Context Protocol in two ways:

	Platform MCP	Curated MCP server
URL	`https://mcp.getcargo.io/mcp`	`https://mcp.getcargo.io/v1/ai/mcpServers/<uuid>/mcp`
Who can use it	Every workspace member, no setup	Whoever you share that server with
Surface	Search/execute actions, query models	Only the tools, agents, models, and capabilities you listed
Best for	“Connect Cargo” in ChatGPT / Claude / Cursor	A named, blessed picker for one client or use case

The UUID path is Cargo’s address for a workspace resource — not an MCP protocol requirement. Linear and Notion use /mcp the same way the platform server does. Keep curated servers on the UUID path; OAuth tokens are audience-bound to that exact URL. Agent skills over the cargo-ai CLI stay the right surface for building: project deploys, schema changes, and large batches.

Connect the platform MCP

Hosted clients that speak HTTP (ChatGPT custom connectors, Claude.ai, Cursor over HTTP) connect to:

https://mcp.getcargo.io/mcp

The client discovers Cargo’s authorization server, opens a browser for you to sign in, and then calls the server with a short-lived access token. If you belong to more than one workspace, the consent screen asks which one to bind. Workspace API tokens still work as Authorization: Bearer. On the MCP servers page, Connect Cargo shows this URL and the live OAuth grants against it.

What it can do

The platform server is a small, stable tool list. It does not dump every CLI command or every workspace tool into the client’s picker.

whoami / get_usage — signed-in user, workspace, and recent credit usage
search_actions — search connector, native, tool, and agent actions
get_action_schema — input and output JSON schemas for those actions, without running anything
execute_action / execute_action_batch — run one input or a batch (credits apply)
get_run / get_batch / list_runs — poll a run or batch; get_run returns the last node output (not computed configs or traces); a finished batch carries a time-limited download URL for its output CSV
list_models / describe_model / query_models — the model catalog, one model’s columns and its dataset.model reference, and one read-only SQL SELECT over them (joins and aggregates allowed; small row cap, so aggregate rather than page)
map_context / search_context / browse_context / read_context — read the workspace’s context: map_context lists every indexed file with its title and summary, search_context returns matching lines, read_context returns a line range. Read-only — the platform server never writes to the context

config on a top-level action must be {}. Inputs go in data (single) or records (batch). Never fan execute_action out record-by-record — that is what execute_action_batch is for.

Connect a coding agent

cargo-ai mcp serves the platform server over stdio with the credentials the CLI already has:

claude mcp add cargo -- cargo-ai mcp

Pass --server <uuid> to bridge a curated server instead. With no --server, the bridge uses CARGO_MCP_SERVER_UUID if set, otherwise the platform /mcp.

stdout carries the MCP protocol and every log goes to stderr, so nothing else may write to stdout around the bridge.

Define a curated MCP server

Each member is passed by handle — the same rich refs an agent accepts:

mcp/crm.ts

import { defineMcpServer } from "@cargo-ai/cdk";
import { sdr } from "../agents/sdr";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";

export const crmServer = defineMcpServer("crm", {
  description: "CRM tools and data for assistants.",
  // One array — tools, agents, and data models (same surface as an agent):
  uses: [enrich, sdr, { ref: contacts, readOnly: true }],
  capabilities: [
    "webSearch",
    { slug: "context", config: { isReadOnly: true } },
  ],
});

Deploy

cargo-ai project deploy
cargo-ai ai mcp-server list   # note the server's uuid

Connect a remote MCP client

https://mcp.getcargo.io/v1/ai/mcpServers/<uuid>/mcp

OAuth accepts any https callback, plus loopback for local clients. On the MCP server page, Connected apps lists each live OAuth grant. Revoke a grant to sign that client out; it will need to authorize again.

MCP or the agent skills?

	MCP	Agent skills
Surface	Platform: operate the workspace. Curated: only what you exposed	The whole `cargo-ai` CLI
Reaches	Any MCP client, including ones with no skills support	Claude Code, Cursor, Codex, and other skills.sh agents
Best for	In-conversation calls against a workspace	Batches, workflows, schema changes, deploys, anything with a cost gate

Rule of thumb: more than a handful of records, or anything worth re-running, belongs in the CLI. Never fan an MCP tool out record-by-record over a list — that is what a batch is for, and it is cheaper and observable.

From the CLI

Servers can also be created and edited without a project:

cargo-ai ai mcp-server create --name "GTM tools" \
  --actions '[{"slug":"<tool-or-agent-uuid>","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}]'
cargo-ai ai mcp-server update --uuid <uuid> --name "GTM tools"

Actions take kind: "tool" or kind: "agent" — an agent can be exposed as a callable MCP tool. update replaces the --actions, --resources, and --capabilities arrays wholesale rather than merging, so read the current server first and pass the full array back. Capabilities such as webSearch and context become MCP tools on the server.

The action and model capabilities reach the whole workspace rather than what you exposed, so adding them to a curated server gives its clients the platform surface too. Leave them off when the point of the server is that a client sees exactly what you listed and nothing else.

Get started

Resources

Deploy

CLI

Skills

Reference

Connect the platform MCP

What it can do

Connect a coding agent

Define a curated MCP server

Deploy

Connect a remote MCP client

MCP or the agent skills?

From the CLI

​Connect the platform MCP

​What it can do

​Connect a coding agent

​Define a curated MCP server

​Deploy

​Connect a remote MCP client

​MCP or the agent skills?

​From the CLI

Connect the platform MCP

What it can do

Connect a coding agent

Define a curated MCP server

Deploy

Connect a remote MCP client

MCP or the agent skills?

From the CLI