---
type: how-to
title: Use the MCP server
summary: Connect an AI agent to Caputchin through the MCP server, authenticate it with an access token, and drive the management API in natural language, with a worked example.
---

The Caputchin MCP server lets an AI agent (Claude, Cursor, or any [Model Context Protocol](https://modelcontextprotocol.io) client) manage your account by calling the same [management API](/docs/automation/management-api) the dashboard uses. The server is a thin transport-and-auth shell: it exposes one MCP tool per management operation and proxies each call to the API. So the agent can do anything you can, short of billing, in natural language.

## Mint an access token [#mint-an-access-token]

The server authenticates with an access token from the `CAPUTCHIN_TOKEN` environment variable. Either kind works (see [API authentication](/docs/automation/management-api#mint-an-access-token)):

- a [personal access token](/docs/account-management/personal-access-token) for full-account control, or
- a [troop access token](/docs/troops/tokens) to scope the agent to certain troops with least privilege, which is the safer default when handing access to an autonomous agent.

Copy the token at creation; it is shown once.

## Two ways to connect

There are two transports, and they expose the **same tools** backed by the same management API. Pick by how your client connects:

| | Local (stdio) | Hosted (HTTP) |
|---|---|---|
| What it is | The `@caputchin/mcp` package, run on your machine | A remote endpoint at `api.caputchin.com/mcp` |
| Client needs | To spawn a local process (stdio) | To connect to a remote MCP server (HTTP) |
| Auth | `CAPUTCHIN_TOKEN` in the process environment | `Authorization: Bearer` header on the connection |
| Best when | Local dev, a desktop client, no inbound network | A hosted agent, no local process to spawn |

### Local: the npx server (stdio)

The server is published as `@caputchin/mcp` on npm. You usually do not run it by hand; you wire it into your MCP client's config and it is spawned over stdio, with the token in its environment:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

To check it runs, launch it directly; it speaks MCP over stdio and exits with an error if the token is missing:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### Hosted: the HTTP endpoint

For clients that connect to a remote MCP server instead of spawning a local one, Caputchin hosts the same server at:

```
https://api.caputchin.com/mcp
```

It authenticates with your token as a `Bearer` header on the connection (the same credential, just passed over HTTP rather than the environment):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

The exact config shape depends on your MCP client; what matters is the URL and the `Authorization: Bearer` header. Nothing to install, and no local process; the tradeoff is that the token travels to the hosted endpoint per request rather than staying in a local process environment.

## The tools

Every tool is named `caputchin_<verb>_<noun>` and maps to one management operation, for example `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. The agent discovers the full set and each tool's parameters automatically over MCP, so you describe the goal and the agent picks the tools.

## A worked example

With the server wired into your client, you can ask the agent in plain language:

> "Create a site key called shop-frontend in my shop-team troop, then turn on the game gate for it."

The agent resolves that to a sequence of tool calls: `caputchin_list_troops` to find the troop id, `caputchin_create_site` with that `troop_id`, then `caputchin_update_site_security` to require a game. Each call hits the management API under your token, and on Apex each one lands in your [audit log](/docs/audit-logs/overview) attributed to the token, so an agent's actions are as traceable as a person's.

Because the agent acts with your token's full reach, prefer a scoped troop token when you can, and revoke it the moment the task is done.

## The full reference

For the complete list of tools, each with a one-line description and the permission its token must hold, see the [MCP tools reference](/docs/automation/mcp-tools). The tools mirror the management API one-for-one, so the [interactive API reference](/docs/api-reference) is the authoritative description of every operation's parameters and response: read a tool's MCP description for the agent-facing summary, and the API reference for the exact schema.

## See also

- [MCP tools reference](/docs/automation/mcp-tools): every tool, its description, and the permission it needs.
- [Manage Caputchin from the API](/docs/automation/management-api): the HTTP API every tool calls.
- [Use Terraform or OpenTofu](/docs/automation/terraform): the infrastructure-as-code surface.
- [Personal access token](/docs/account-management/personal-access-token) and [troop tokens](/docs/troops/tokens): the credentials the server uses.