Connect Claude Code, Codex or Cursor to cmdz over MCP

Four clients, four snippets, one endpoint. Then the part nobody documents: how to tell whether it actually worked.

The endpoint

https://mcp.cmdz.com/v1

Streamable HTTP, protocol version 2025-06-18. POST for client-to-server messages, GET for the SSE stream the server uses to push progress on long operations. There is no stdio server to install and nothing to keep running on your machine.

Claude Code

claude mcp add --transport http cmdz https://mcp.cmdz.com/v1

That is the whole configuration. The first tool call triggers the authorisation flow.

Claude Desktop

{
  "mcpServers": {
    "cmdz": {
      "url": "https://mcp.cmdz.com/v1"
    }
  }
}

Cursor

Same shape, in .cursor/mcp.json for a single project or in the global settings for all of them:

{
  "mcpServers": {
    "cmdz": {
      "url": "https://mcp.cmdz.com/v1"
    }
  }
}

Codex

[mcp_servers.cmdz]
url = "https://mcp.cmdz.com/v1"

Clients that only speak stdio

Some older clients cannot do remote MCP servers. Bridge with mcp-remote:

{
  "mcpServers": {
    "cmdz": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.cmdz.com/v1"]
    }
  }
}

Prefer the direct HTTP route where your client supports it — fewer moving parts, and the bridge is one more process that can be out of date.

What the authorisation flow actually does

The first tool call gets a 401 with a pointer to our protected-resource metadata. Your client discovers the authorisation server, generates a PKCE challenge and opens your browser.

In that browser you:

1. Log in with a passkey. No password exists to phish.
2. Choose the organisation, if you belong to more than one.
3. Choose a profile — read, build or full, or customise the scopes.
4. Confirm with a step-up passkey check.

The token that comes back is bound to https://mcp.cmdz.com as its audience. It does not work against the REST API directly, which means a leaked agent token cannot simply be replayed somewhere else.

Your role limits what you can grant. A viewer who tries to authorise full is told, in the consent screen, that their role does not carry that profile.

Picking a profile

Start on read for a day if you have not done this before. Watch what it looks up and what it concludes; it costs nothing and it is genuinely informative about how a model reasons about infrastructure.

Move to build when you want it to actually do things. This is the default, and its defining property is that all three delete scopes are missing — an agent on build can create anything and destroy nothing.

Take full only when you have a reason, and know that destructive tools still need a confirmation token from your own interface.

Telling whether it worked

Ask it something read-only:

> what is my cmdz spend cap right now?

A working connection answers with real numbers, because cmdz_get_spend_cap returned them. A broken one produces a plausible-sounding paragraph with no numbers in it, which is the failure mode worth learning to recognise.

Then check the envelope. Every response carries this, on all 47 tools:

"spend_cap": { "used": "12.40", "cap": "20.00", "state": "healthy" },
"budget":    { "actions_today": 3, "actions_max": 400 }

If your client shows raw tool results, you will see it. If it does not, ask the agent what your remaining headroom is — it read it, whether or not it mentioned it.

When something goes wrong

cmdz --debug is the fastest path. Every CLI command takes --json and returns exactly the same JSON as the identically named MCP tool, so you can reproduce what the agent saw without the agent in the way:

cmdz apps list --json

If that works and the MCP call does not, the problem is in the client or the token, not in the platform. That equivalence is deliberate — it is also why an agent with no MCP support at all loses nothing by driving the CLI instead.

A first task worth giving it

> deploy this repo to cmdz, give it a postgres database,
  and tell me what it will cost per month

It will create the project, quote the database before creating it, deploy, wait for the health check, and report the run rate against your ceiling. If any of that would cross the limit, it stops and tells you it cannot raise it.

That last sentence is the entire reason this is safe to try.