Use the MCP server

The Caputchin MCP server lets an AI agent (Claude, Cursor, or any Model Context Protocol client) manage your account by calling the same 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

The server authenticates with an access token from the CAPUTCHIN_TOKEN environment variable. Either kind works (see API authentication):

a personal access token for full-account control, or
a troop access token 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 `caputchin.com/api/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:

{
  "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:

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://caputchin.com/api/mcp

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

{
  "mcpServers": {
    "caputchin": {
      "url": "https://caputchin.com/api/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 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. The tools mirror the management API one-for-one, so the interactive 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.