> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# MCP servers

> Expose a curated set of your tools, agents, and data models to Claude Desktop, ChatGPT, Cursor, or any MCP client — define the server with defineMcpServer, then serve it over stdio with cargo-ai mcp using credentials already on the machine.

An **MCP server** exposes a curated set of your tools, agents, and data models behind one [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, so external assistants (Claude, Cursor, …) 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:

```ts mcp/crm.ts theme={null}
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

```bash theme={null}
cargo-ai cdk deploy
cargo-ai ai mcp-server list   # note the server's uuid
```

## 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**.

```bash theme={null}
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.

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

### MCP or the agent skills?

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

|          | **MCP server**                                                | **[Agent skills](/skills/overview)**                                        |
| -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 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](https://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:

```bash theme={null}
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.