Connect over MCP
HeyCMO runs a remote MCP server. Your agent can read the brand kit, start jobs, read drafts and ask to publish them. A person approves every piece on app.heycmo.ai with a passkey (Face ID, fingerprint or your phone) before it goes out.
The server
| URL | https://mcp.heycmo.ai/mcp |
|---|---|
| Transport | Streamable HTTP. The server keeps no session, so each request stands alone. |
| Sign-in | OAuth 2.1 with PKCE (S256) on https://auth.heycmo.ai |
| Resource metadata | https://mcp.heycmo.ai/.well-known/oauth-protected-resource/mcp (RFC 9728) |
| Scopes | runs:read, runs:write, artifacts:read, approvals:read, brand:read, autonomy:read, autonomy:lower |
Add the server to your client
Most clients need only the URL. For a client that reads a JSON configuration file, add an entry like this one:
{
"mcpServers": {
"heycmo": {
"type": "http",
"url": "https://mcp.heycmo.ai/mcp"
}
}
}
For Claude Code, run this command:
claude mcp add --transport http heycmo https://mcp.heycmo.ai/mcp
The names of the fields change from client to client. Look in your client's docs for "remote MCP server" or "Streamable HTTP".
Sign in
- Your client calls the server with no token. The server answers
401with aWWW-Authenticateheader that points to the resource metadata. - The metadata names
https://auth.heycmo.aias the only authorization server. Your client registers there: with a Client ID Metadata Document (its client ID is the https URL of that document), or by Dynamic Client Registration. - A browser window opens. The person signs in to HeyCMO and agrees to the access your client asks for.
- Your client gets a token for the resource
https://mcp.heycmo.ai/mcpand sends it on each request. A token made for another resource, such as the REST API, is refused here.
The token holds agent scopes only. HeyCMO caps every MCP sign-in at level L2 (Ask first) and never lets it pay. So no tool can approve, raise a level, connect a platform or spend money.
Which workspace the sign-in uses
On the first request after sign-in, HeyCMO connects your client to one workspace:
- The workspace your client names, in the
HeyCMO-Workspaceheader or as?workspace=on the server URL. The person must be a member of it. - Else the person's only workspace.
- Else, for a person with no workspace, a new workspace with the person as its owner. Until Apr 26, 2027 this needs an invite code: send it in the
HeyCMO-Inviteheader (or?invite=), and the site the code is for inHeyCMO-Domain(or?domain=). Without a valid code the answer isinvite_required.
A header wins over the URL. When the person is a member of more than one workspace and the client names none, the first request answers invalid_request. The answer does not list the workspaces. The person copies the workspace ID from app.heycmo.ai, and the client sends it in HeyCMO-Workspace. Later, when one client holds access to more than one workspace, a tool that gets no header answers invalid_request with the list of those workspaces.
A workspace owner sees each connected client on app.heycmo.ai and can revoke it. After a revoke, the same client gets unauthenticated, and a new sign-in does not connect it again. HeyCMO support can restore it.
With an API key instead
A client that cannot open a browser, such as a CI job, can send an API key (it starts with hc_live_) as the bearer token. Only a workspace owner can make a key, on app.heycmo.ai. Keep it in your secret store, never in a prompt or a repository.
The 14 tools
Each tool calls the REST API with your token, so each call passes the same access checks, pause and rate limits. A tool marked read-only changes nothing.
| Tool | What it does | Scope |
|---|---|---|
audit_site | Runs the free site audit for a domain: the score, the top fixes, an AI visibility snapshot and the score page URL. Read-only. | runs:read |
get_brand_kit | Reads the approved brand kit: voice, customers, claims, competitors and version. Read-only. | brand:read |
get_autonomy | Each action class with its level, the level in effect and the ceiling, and whether the workspace is paused. Read-only. | autonomy:read |
lower_autonomy | Lowers one class to a lower level, or pauses everything. A raise is refused. | autonomy:lower |
estimate_cost | What a job uses from the plan, for example 1 of your 8 new pages, and if a person must approve it. Read-only. | runs:read |
start_run | Starts a job and returns its run ID at once. Send idempotency_key so a retry starts one run. | runs:write |
get_run | The status, steps, latest events, artifacts and approvals of one run. Read-only. | runs:read |
list_runs | Runs, newest first, with next_cursor. Read-only. | runs:read |
get_artifact | One draft or report, as JSON or Markdown. Read-only. | artifacts:read |
list_approvals | Approvals, with next_cursor. Read-only. | approvals:read |
get_approval | The preview, diff, expiry and the approval URL a person opens to decide. Read-only. | approvals:read |
list_connections | Connected platforms with ID, platform, account and status. Read-only. | runs:read |
get_action | The status, publish time, cancel reason, last check and result link of one write. Read-only. | runs:read |
request_publish | Asks to publish an artifact, or a draft you send inline, to a connection. With publish_at it goes on the calendar as a proposed time. The result holds the approval URL for a person. | runs:write |
The v1 jobs are knowledge_base, brand_kit, strategy_plan (the content plan), seo_article, article_refresh, x_post, linkedin_post, ai_search_tracking and weekly_plan_review. The jobs://catalog resource lists them. A job that is off answers feature_not_enabled.
A draft you send inline with request_publish is saved as an agent draft. It always waits for a person, and the approval page says your agent wrote it. Every claim in it needs a current source in the knowledge base, else the answer is claims_unsupported.
Prompts and resources
| Name | Kind | What it gives your agent |
|---|---|---|
seo-brief | Prompt | Plans one search page from the brand kit, estimates it, and starts the article as a draft when the person agrees. Takes topic, and optional format and competitor. |
weekly-review | Prompt | Reviews the week: runs, pieces that wait for a person with their links, and up to three next jobs. |
brand://kit | Resource | The approved brand kit, as JSON. |
artifact://{id} | Resource | One draft or report, as Markdown when it has Markdown. |
jobs://catalog | Resource | The jobs you can start. |
When a tool fails
A refused call returns a tool error. Its JSON text holds the problem code from the API, a plain message and, for a held write, the approval link. Examples are approval_pending and workspace_paused. Each code, with what to do next, is on the error codes page. Do not retry a code whose retry column says No.
The tool error keeps the approval link but not hint, action_url or connect_url. Three codes come from the MCP server itself: upstream_error (the API gave an answer that is not a problem), invalid_response (the API answer did not match the tool's output schema) and internal_error (the tool failed). Try those once more later.
What only a person can do
No MCP tool can do these things. When your agent needs one, give the person the approval link from the tool's answer, or send them to app.heycmo.ai. They act on app.heycmo.ai, most often with a passkey.
- Approve or reject a piece, or a week of pieces.
get_approvalgives the link. - Stop a scheduled post.
- Raise a level or resume a paused workspace. Your agent may lower a level or pause.
- Connect GitHub, Webflow or X, or reconnect an expired connection.
- State a fact, mark a fact wrong, or change the tracked questions.
- Revoke a connected client or an API key.
- Anything about the plan, invoices or members.