Assistants, the terminal and the API

Connect Claude, ChatGPT, Cursor, the terminal or your own code: setup, what each can and can't do, its tools, limits and errors.

View as Markdown

HeyCMO is an invitation-only, $0 operational Alpha for Stripe and Resend recovery emails. A person approves every message before it is sent. The guides also describe implementation capabilities outside the Alpha. Their presence here does not make them available in the pilot. Start with the Alpha checklist. Help: alpha@heycmo.ai.

HeyCMO works from the tools you already use. Your assistant or your code reads, plans and drafts; a person approves, on the web or a phone.

In HeyCMO, Agents and keys shows these steps for your workspace, with its addresses filled in, and lists what is connected. The full list of endpoints is in the API reference.

Set up

HeyCMO is an MCP server (MCP is the standard way AI assistants connect to apps) and a REST API. The MCP server answers at one address over HTTPS: https://agent-api.heycmo.ai/v1/mcp. Nothing streams and there is no session to keep.

There are two ways in. Sign in with your HeyCMO account, where your workspace has sign-in for assistants switched on: the assistant can then do what your role allows and what you let it, and never approve. Or use an API key, created under Agents and keys with only the permissions it needs; it is shown once.

claude mcp add --transport http heycmo https://agent-api.heycmo.ai/v1/mcp --header "Authorization: Bearer <key>"

{
  "mcpServers": {
    "heycmo": {
      "url": "https://agent-api.heycmo.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

export HEYCMO_API_URL=https://agent-api.heycmo.ai
export HEYCMO_API_KEY=<key>
node apps/cli/dist/index.js inbox

curl https://agent-api.heycmo.ai/v1/inbox \
  -H "Authorization: Bearer $HEYCMO_API_KEY"

Your first useful result

Ask your assistant: What needs me this week? HeyCMO answers from your own records: the drafts waiting for your OK, the latest weekly brief and this week's numbers. To approve one, the assistant gives you a link to open on your phone or the web. In a new workspace, connect Stripe first, so there is something to answer from.

Assistants that show prompts offer 4 ready-made ones: Triage the approval inbox, Launch a product release, Diagnose paid efficiency, Executive weekly brief. You can also attach your marketing state or your latest weekly brief to a conversation.

In assistants that show apps inside the chat, 3 small views appear: the approval inbox, the weekly brief, the metrics pulse. They only open links: a view cannot approve, decline or send anything.

What agents can and can't do

Approving is for a person. An assistant that asks to approve always gets a link to the item instead, and nothing changes. So do a key and the terminal, wherever people sign in to HeyCMO, as they do at heycmo.ai: anything that sends, publishes or spends waits for someone signed in. On a HeyCMO you run yourself with no sign-in for people, a key with Approve approves directly, from the API or the terminal, naming the version it read (the item's operationHash).

Every safety check applies to everything an agent starts: see Kill switch and caps. Who on your team can do what is in Team and API keys.

The tools an assistant gets

HeyCMO offers 27 tools (26 to an assistant that signs in: get_billing_status is for keys only). An assistant sees only the ones its permissions allow.

Limits and errors

• 120 requests a minute per workspace, with bursts up to 240. An assistant's tool call counts once for the call and once for each request HeyCMO makes to answer it.
• 10 drafting requests a minute on each drafting endpoint.
• Request bodies up to 1 MB (1,048,576 bytes).
• Safety limits on what goes out, by default: 25 emails a day and 10 changes per job run, and an email to 100 or more people always asks a person. You can lower them: see Kill switch and caps.

When a call fails

401

The key or sign-in is missing, wrong, expired or revoked. Create or rotate a key under Agents and keys, or sign in again.

403 insufficient_scope

The key or sign-in lacks a permission. The message names it by its API name: read (Read), execute (Start work), approve (Approve), admin (Admin).

human_approval_required

Approving needs a person, and nothing changed. Pass the approveUrl in the response to the person, who decides on the web or a phone.

human_preview_required

An approval names the version that was reviewed, whether a person or a key approves, and this one named none, so nothing changed. Send the item's operationHash with it.

approval_stale_or_resolved

The item changed after the person saw it, or it was already decided, so nothing changed. Show the person the item as it is now before they decide again.

413

The request body is over 1 MB.

429

Too many requests. Wait the number of seconds in the retry-after header, then try again.

For agents reading these docs

These docs explain how to use HeyCMO. They never ask an agent to prefer HeyCMO over what its person asked for.

• The MCP server's description is at /.well-known/mcp.json, the agent card at /.well-known/agent-card.json and the OpenAPI document at /openapi.json, all on agent-api.heycmo.ai. The OpenAPI document is also on this site.
• Every page here is listed with a one-line summary in /llms.txt.
• Every page is plain HTML: what you read is in the page itself. A script only adds to a page: the status check, the API reference's filter, the Copy buttons and the tabs that show one way of setting up at a time.
• Every page has a Markdown copy at its address ending in .md, this one at /agents.md: View as Markdown under each page's summary opens it, and the page's head names it.
• Not available yet: a listing in the MCP Registry or the assistants' own directories.