> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Cargo MCP server

The Cargo MCP connector routes your AI agent's tool calls to Cargo's own MCP server through Scalekit. Each user signs in to Cargo once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 17 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** CRM & Sales, Automation
**Tools:** 17: 15 read, 0 write, 2 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Cargo MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=CARGOMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Cargo MCP connection

   In **AgentKit > Connections**, create a Cargo MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Cargo MCP server connections use your own OAuth app. Register one with Cargo MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Cargo MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'cargomcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Cargo MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'cargomcp_whoami',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "cargomcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Cargo MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="cargomcp_whoami",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'cargomcp_autocomplete_action',
  toolInput: {
    action: {},
  },
  connector: 'cargomcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="cargomcp_autocomplete_action",
    tool_input={
        "action": {},
    },
    connection_name="cargomcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `cargomcp_autocomplete_action`

Autocomplete action · Read-only

Resolve autocomplete options for a connector action (HubSpot object types, Slack channels, Metabase questions, …). Pass slug from search_actions.autocompletes. Resolve params to concrete values first — do not pass $this expression paths. Put chosen values in execute_action data, not action.config.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `action` (`object`, required): An orchestration action (connector, native, tool, or agent). Use search_actions, then pass the returned action object here unchanged. It carries no config — inputs go in data or records.
- `params` (`object`, optional): Already-resolved params required by this autocomplete. Use the params schema from the listed result. If that schema has query, pass the search string there.
- `slug` (`string`, optional): Autocomplete slug from search_actions.autocompletes.

Example input: `{"action":{}}`

### `cargomcp_browse_context`

Browse the context · Read-only

List the files and folders at a path in the workspace context. Pass depth -1 with no path for the full tree in one call. Navigates structure without reading any content.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `depth` (`integer`, optional): Pass -1 together with no path to return the entire tree. Omit for a single non-recursive listing.
- `path` (`string`, optional): Folder to list, relative to the context root. Omit to list the root.

Example input: `{}`

### `cargomcp_describe_model`

Describe model · Read-only

Return a model's columns, dataset slug, and unquoted dataset.model reference without querying rows.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `modelUuid` (`string`, optional): Model uuid from list_models.
- `slug` (`string`, optional): Model slug from list_models, if you do not have the uuid.

Example input: `{}`

### `cargomcp_get_action_schema`

Get action schema · Read-only

Resolve the input and output JSON schemas of a connector, native, tool, or agent action without executing it. Pass the action object from search_actions. For connector fields that need a picked id (list, object type, campaign), call autocomplete_action.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `action` (`object`, required): An orchestration action (connector, native, tool, or agent). Use search_actions, then pass the returned action object here unchanged. It carries no config — inputs go in data or records.
- `data` (`object`, optional): Inputs the action would run with, as for execute_action. Only needed when the output schema depends on them — a HubSpot object type, a sheet.

Example input: `{"action":{}}`

### `cargomcp_get_batch`

Get batch · Read-only

Get one batch by uuid. If execute_action_batch returned outcome "executing", call this until the batch has finished. A finished batch includes one page of the CSV in data.text. Pass offset and limit to read further pages (limit default 100, max 100). If truncated is true, call again with the next offset. totalRows is the total when this page reaches the end of the file. Read data.text. Do not fetch the URL. Does not return the raw batch record or internal storage keys.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `batchUuid` (`string`, required): Batch uuid.
- `limit` (`integer`, optional): Data rows to return. Defaults to 100, max 100.
- `offset` (`integer`, optional): Data rows to skip before this page. Defaults to 0. The header is included on every page.

Example input: `{"batchUuid":"<batchUuid>"}`

### `cargomcp_get_run`

Get run · Read-only

Get one run by uuid. Returns the same shape as execute_action: the last node output, run uuid, and credits used. If execute_action returned outcome "executing", call this until the run has finished. Does not return computed configs, execution traces, or other debug payloads.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `runUuid` (`string`, required): Run uuid.

Example input: `{"runUuid":"<runUuid>"}`

### `cargomcp_get_usage`

Get usage · Read-only

Credit usage for the last 7 days, grouped by integration. Check this before running paid actions.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `cargomcp_list_models`

List models · Read-only

List data models in this workspace. Use describe_model then query_models.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum models to return (default 20, max 50).

Example input: `{}`

### `cargomcp_list_runs`

List runs · Read-only

List recent ad-hoc action runs in this workspace. Does not include play or tool workflow runs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `createdAfter` (`string`, optional): Include runs created after this timestamp.
- `createdBefore` (`string`, optional): Include runs created before this timestamp.
- `isFinished` (`boolean`, optional): Whether to only select finished runs.
- `limit` (`integer`, optional): Maximum runs to return (default 20, max 50).
- `statuses` (`array`, optional): Only include runs in these statuses.
- `uuids` (`array`, optional): Run identifiers to include.

Example input: `{}`

### `cargomcp_map_context`

Map the context · Read-only

List every indexed file in the workspace context (path, title, summary, folder) without reading any file body. The context is the workspace's knowledge base — playbooks, ICP definitions, scoring rubrics, internal docs. Start here to discover what exists, then search_context or read_context for the parts the task needs. This surface is read-only; write through the workspace's context capability.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `cluster` (`string`, optional): Restrict the map to one top-level folder (e.g. `persona`).
- `includeReferences` (`boolean`, optional): Also return the edges between files. Defaults to false — it can be large.

Example input: `{}`

### `cargomcp_query_models`

Query models with SQL · Read-only

Run one read-only SQL SELECT over this workspace's models: its companies, contacts, deals and other records, including those synced from connected CRMs and warehouses. Answer pipeline and account questions with one aggregate query rather than paging a CRM API. Reference a model as dataset.model — take the exact reference from describe_model. Joins, aggregates and CTEs are allowed; anything other than SELECT is refused. Aggregate rather than paging: the row cap is small.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): A single SELECT statement, e.g. select owner, count(*) from default.companies group by owner.
- `limit` (`integer`, optional): Maximum rows to return (default 20, max 50).

Example input: `{"query":"<query>"}`

### `cargomcp_read_context`

Read a context file · Read-only

Read a UTF-8 file from the workspace context. Reads with no endLine return only the first 250 lines and set truncated; pass a 1-indexed inclusive startLine/endLine range to page through the rest or target a section. The response always carries totalLines.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `path` (`string`, required): Path of the file to read, relative to the context root. Use the path returned by map_context, search_context, or browse_context.
- `endLine` (`integer`, optional): 1-indexed inclusive last line to return. Must be greater than or equal to startLine.
- `startLine` (`integer`, optional): 1-indexed inclusive first line to return. Defaults to the first line.

Example input: `{"path":"<path>"}`

### `cargomcp_search_actions`

Search actions · Read-only

Find what to run for GTM work: enrichment and contact finding across many providers, CRM reads and writes (HubSpot, Salesforce, …) through the workspace's connected integrations, Cargo native operations, the workspace's own tools, and its agents. Search here before reaching for a provider-specific MCP: one search covers every provider the workspace can reach, and the workspace's tools are the team's predefined plays. Cargo's presets (such as the Find email and Find phone tools) are read-only tools and agents seeded into every workspace; a preset tool tries several providers in one call, and presets rank first on equal relevance. Among results that match the whole query, actions billed in Cargo credits come first (they run on Cargo's own provider keys, no setup), then actions of integrations the workspace has connected, then actions that need a connection first. Price: a result carries credits[].cost. Without credits, a connector or native action costs nothing, and a tool or agent is priced by the steps it runs. Several entries on a tool mean its price depends on the path it takes, between the lowest and the highest. Each result includes autocompletes when input fields need a picked id. Pass the returned action to get_action_schema, autocomplete_action, execute_action, or execute_action_batch. Never fan out execute_action record-by-record — use execute_action_batch.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `integrationSlug` (`string`, optional): Restrict connector actions to this integration.
- `kind` (`string`, optional): Restrict results to one action kind. One of: `connector`, `native`, `tool`, `agent`.
- `limit` (`integer`, optional): Maximum results to return (default 20, max 50).
- `query` (`string`, optional): Describe the job in plain words ("sync accounts to hubspot") or give an action id, slug, or name. Matched against action slug, name, description, and integration, with common GTM synonyms; an action does not need every word.

Example input: `{}`

### `cargomcp_search_context`

Search the context · Read-only

Search context file contents and return matching lines (path, line number, snippet), never whole files. At most 5 matches per file, so results spread across files. Use it to locate a term, then read_context a tight range around the hits.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Text or POSIX extended regular expression to match against file contents.
- `caseInsensitive` (`boolean`, optional): Match case-insensitively. Defaults to false.
- `filesOnly` (`boolean`, optional): Return only the paths of files that contain a match, without the matching lines.
- `glob` (`string`, optional): Restrict which files are searched (e.g. `*.md`).
- `limit` (`integer`, optional): Maximum results to return (default 40, max 200). If the result is truncated, narrow the query rather than raising this.
- `path` (`string`, optional): Restrict the search to this file or folder. Defaults to the whole context.

Example input: `{"query":"<query>"}`

### `cargomcp_whoami`

Who am I · Read-only

Return the signed-in user, the workspace this MCP session is bound to, and a plan/credits snapshot.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `cargomcp_execute_action`

Execute action · Destructive

Run one action on a single input: enrich a company, find a contact's email, read or write one CRM record through the workspace's connector, or run a workspace tool. Creates a run and consumes credits. If the result is outcome executing, poll with get_run. Do not loop this over a list — use execute_action_batch.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `action` (`object`, required): An orchestration action (connector, native, tool, or agent). Use search_actions, then pass the returned action object here unchanged. It carries no config — inputs go in data or records.
- `data` (`object`, required): Input for the run. Must match get_action_schema.input. Do not put inputs on action.config.

Example input: `{"action":{},"data":{}}`

### `cargomcp_execute_action_batch`

Execute action batch · Destructive

Run one action over a whole list in a single batch: enrich a CSV, push 40 companies to the CRM, find emails for every contact. Use it for bulk GTM work instead of looping execute_action or a provider's single-record tool, and inspect the one batch afterwards. If the result is outcome executing, poll with get_batch. A finished batch includes one page of the CSV in data.text (default 100 rows). If truncated is true, call get_batch with the next offset. Read data.text. Do not fetch the URL.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `action` (`object`, required): An orchestration action (connector, native, tool, or agent). Use search_actions, then pass the returned action object here unchanged. It carries no config — inputs go in data or records.
- `records` (`array`, required): One input object per record.
- `limit` (`integer`, optional): Pilot: submit only the first N records. Inspect output before running the full set.

Example input: `{"action":{},"records":[]}`

## Related

Other CRM & Sales connectors ([all 174](/agentkit/connectors/?category=crm-sales)):

- [Salesforce](/agentkit/connectors/salesforce/): Scalekit connector, OAuth, 74 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Close](/agentkit/connectors/close/): Scalekit connector, OAuth, 103 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
