<!-- cmdz — Connect Claude Code, Codex or Cursor to cmdz over MCP. Source: https://www.cmdz.com/blog/connect-claude-code-codex-cursor-over-mcp -->
# Connect Claude Code, Codex or Cursor to cmdz over MCP
> The configuration for each client, what the authorisation flow actually does, how to pick a profile, and how to tell whether it is working.

The configuration for each client, what the authorisation flow actually does, how to pick a profile, and how to tell whether it is working.

1 Jul 2026 · 3 min read · cmdz

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

```bash
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

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

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

## Codex

```toml
[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`:

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

```json
"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:

```bash
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.

## Set your limit and start.

One click with a passkey, then you verify a payment method once to start your 14-day free trial (€ 10 of credit). After that it is prepaid pay-as-you-go — you only ever spend credit you have already bought, and no invoice ever arrives above the amount you set.

- [Create account](https://app.cmdz.com/signup)
- [Read the docs](https://docs.cmdz.com)