Skip to content

Account

API & MCP

Connect claude.ai, ChatGPT, Claude Code, Codex, Cursor or your own scripts to your Codz account, for your usage, your issues and your Cloud machines.

codz.com has an MCP server and a REST API for your account. An app you connect can read the usage your Macs sync, read the issues they sync and file changes to them, and see your Codz Cloud machines. Both need Codz Pro.

Your chats, projects, scripts and development servers stay on your Mac, so codz.com can’t reach them. For those, add codz mcp to the apps on that Mac.

Connect an app

The server’s address is https://codz.com/api/mcp. An app connects by signing in with your Codz account, and codz.com asks you what it may do before it can read or change anything. API & MCP in your dashboard has the address and each app’s command, ready to copy.

  • claude.ai: Settings ▸ Connectors ▸ Add custom connector, then paste the address.
  • ChatGPT and other MCP clients: add the address as a custom connector or a remote MCP server.
  • Claude Code: run the command below, then sign in from /mcp.
  • Codex: run the command below, then codex mcp login codz.
  • Cursor: add the server to ~/.cursor/mcp.json.
claude mcp add --transport http codz https://codz.com/api/mcp
codex mcp add codz --url https://codz.com/api/mcp
{
  "mcpServers": {
    "codz": {
      "url": "https://codz.com/api/mcp"
    }
  }
}

Every app you connect is listed under Connected apps on API & MCP, with what it may do and when it was last used. Disconnect ends its access at once. An app asks you again each time it connects, and a name codz.com can’t confirm shows Name not verified.

What apps can do

Each permission is one line on the sign-in page and one box on an API key.

PermissionToolsWhat they do
Read your usage and plan limitsget_usageTokens and estimated cost for a day or a range of days, by provider, model or day, from what your Macs synced
Read your projects’ issueslist_trackers, list_issues, get_issue, get_issue_operationYour trackers and their issues, and how a change an app filed went
File, change and comment on issuescreate_issue, update_issue, comment_on_issue, link_issues, add_issue_linkChanges that Codz makes on the Mac that owns the tracker
See your Cloud machineslist_cloud_machinesYour Codz Cloud machines, the first one first, with what each is doing
Delete your Cloud machines, with their disks and backupsdelete_cloud_machineDeleting a machine for good. API keys only

Usage figures are estimates at each provider’s API list prices, not what a subscription bills. codz mcp on your Mac also sees minutes that haven’t synced yet, so the two can differ for a few minutes.

Issues

Issues reach codz.com only from a Mac with Settings ▸ Account ▸ Sync issues turned on. It is off until you turn it on. Titles, descriptions and comments are stored on codz.com; folder paths and chats stay on your Mac.

Your Mac stays in charge of its trackers. A change from an app waits on codz.com until Codz on the Mac that owns the tracker applies it, with the checks and history an agent’s change gets. When that Mac is awake, the app usually hears back within seconds. Otherwise the change is queued for up to seven days, and get_issue_operation tells the app how it went. Apps can never delete an issue or start work on one.

Cloud machines

list_cloud_machines shows the same machines as Settings ▸ Cloud ▸ Machines on your Mac. delete_cloud_machine deletes one by its id or its name. The machine’s disk, everything on it and its backups are erased and can’t be recovered.

Your first machine can’t be deleted, and neither can one a chat is running on.

API keys

A key gives a script, or an app that can’t sign in, access to your account. Create one on API & MCP:

  1. Give it a Name you will recognise.
  2. Under Can, tick only what it needs.
  3. Choose when it Expires: in 30 days, in 90 days or in a year.
  4. Click Create key, then copy it. Codz shows it only once.

Send the key as Authorization: Bearer with the MCP server or the REST API. Revoke ends a key at once. codz.com keeps only a fingerprint of each key, never the key itself.

REST API

The REST API is at https://codz.com/api/v1 and takes API keys only. Its schema is at codz.com/api/v1/openapi.json.

RequestWhat it does
GET /meThe account and the key’s permissions
GET /usageYour synced usage
GET /trackers, GET /issues, GET /issues/{ref}Your trackers and issues
POST /issues, PATCH /issues/{ref}File or change an issue
POST /issues/{ref}/comments, /relations, /linksComment on an issue, link two issues, add a web link
GET /issue-operations/{id}How a change went
GET /machinesYour Cloud machines
DELETE /machines/{machine}Delete a Cloud machine, named by its id or its URL-encoded name
curl https://codz.com/api/v1/machines \
  -H "Authorization: Bearer $CODZ_API_KEY"

An issue change answers 200 once the Mac applied it, 422 when the Mac refused it or it expired, and 202 with a Location to check while it waits. Send Prefer: respond-async to skip the wait. Errors come back as { "error": "…", "message": "…" }, and 402 means the account doesn’t have Codz Pro.

Retry a change safely

If an answer might get lost, give the change a key of your own before you send it the first time, and send the same key and the same input on every retry. A retry then answers with the first attempt’s result instead of making the change twice. Without a key, every attempt is a new change.

  • REST: the Idempotency-Key header.
  • MCP: codz.com/idempotency-key in the call’s _meta, outside the tool’s arguments.
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "comment_on_issue",
    "arguments": { "project": "COD", "id": "COD-12", "body": "Verified the fix." },
    "_meta": { "codz.com/idempotency-key": "verify-COD-12-20261121" }
  }
}

A key is 8 to 150 letters, digits, _, : or -, and is remembered for 30 days. Using it again with different input answers 409 idempotency_conflict; pick a new key for a new change. A repeated machine deletion answers with replayed: true. Keys work for the issue changes and for delete_cloud_machine.

Limits

  • Codz Pro: creating a key and connecting an app need it, and every request checks it again. Without it, the REST API answers 402 and the MCP server answers each tool with an error that says so.
  • Issue changes: 60 an hour for your account, and at most 200 waiting for one Mac.
  • Synced issues: 200 trackers and 20 Macs per account.