HeyCMO

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

URLhttps://mcp.heycmo.ai/mcp
TransportStreamable HTTP. The server keeps no session, so each request stands alone.
Sign-inOAuth 2.1 with PKCE (S256) on https://auth.heycmo.ai
Resource metadatahttps://mcp.heycmo.ai/.well-known/oauth-protected-resource/mcp (RFC 9728)
Scopesruns: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

  1. Your client calls the server with no token. The server answers 401 with a WWW-Authenticate header that points to the resource metadata.
  2. The metadata names https://auth.heycmo.ai as 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.
  3. A browser window opens. The person signs in to HeyCMO and agrees to the access your client asks for.
  4. Your client gets a token for the resource https://mcp.heycmo.ai/mcp and 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:

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.

ToolWhat it doesScope
audit_siteRuns 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_kitReads the approved brand kit: voice, customers, claims, competitors and version. Read-only.brand:read
get_autonomyEach action class with its level, the level in effect and the ceiling, and whether the workspace is paused. Read-only.autonomy:read
lower_autonomyLowers one class to a lower level, or pauses everything. A raise is refused.autonomy:lower
estimate_costWhat 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_runStarts a job and returns its run ID at once. Send idempotency_key so a retry starts one run.runs:write
get_runThe status, steps, latest events, artifacts and approvals of one run. Read-only.runs:read
list_runsRuns, newest first, with next_cursor. Read-only.runs:read
get_artifactOne draft or report, as JSON or Markdown. Read-only.artifacts:read
list_approvalsApprovals, with next_cursor. Read-only.approvals:read
get_approvalThe preview, diff, expiry and the approval URL a person opens to decide. Read-only.approvals:read
list_connectionsConnected platforms with ID, platform, account and status. Read-only.runs:read
get_actionThe status, publish time, cancel reason, last check and result link of one write. Read-only.runs:read
request_publishAsks 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

NameKindWhat it gives your agent
seo-briefPromptPlans 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-reviewPromptReviews the week: runs, pieces that wait for a person with their links, and up to three next jobs.
brand://kitResourceThe approved brand kit, as JSON.
artifact://{id}ResourceOne draft or report, as Markdown when it has Markdown.
jobs://catalogResourceThe 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.