MCP servers

An MCP server exposes a curated set of your tools, agents, and data models behind one Model Context Protocol endpoint, so external assistants (Claude, Cursor, ChatGPT, …) can discover and call them. You define one with defineMcpServer.

Define an 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 }],
});

Deploy

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

Connect a remote MCP client

Hosted clients that speak HTTP (ChatGPT custom connectors, Claude.ai, Cursor over HTTP) connect to the Streamable HTTP URL and sign in with OAuth — there is no token to paste:

https://mcp.getcargo.io/v1/ai/mcpServers/<uuid>/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. Workspace API tokens still work as Authorization: Bearer if you need them. Hosted callbacks are allowlisted for ChatGPT, Claude, and Cursor. 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.

Connect a coding agent

cargo-ai mcp serves a deployed server to any stdio MCP client, using the credentials the CLI already has — there is no token to copy into client config.

claude mcp add cargo -- cargo-ai mcp --server <uuid>

The same command is the server entry for Claude Desktop, Cursor, Windsurf, and any other stdio MCP client. With no --server, the bridge falls back to CARGO_MCP_SERVER_UUID, or to the workspace’s only MCP server when there is exactly one.

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

MCP or the agent skills?

Both let a coding agent operate Cargo, and they are not interchangeable:

	MCP server	Agent skills
Surface	Only the tools, agents, and models 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	Curated in-conversation calls a workspace has already blessed	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 the CDK:

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 and --resources arrays wholesale rather than merging, so read the current server first and pass the full array back.

Get started

Resources

Deploy

CLI

Skills

Reference

Define an MCP server

Deploy

Connect a remote MCP client

Connect a coding agent

MCP or the agent skills?

From the CLI

​Define an MCP server

​Deploy

​Connect a remote MCP client

​Connect a coding agent

​MCP or the agent skills?

​From the CLI

Define an MCP server

Deploy

Connect a remote MCP client

Connect a coding agent

MCP or the agent skills?

From the CLI