Skip to content

CLI

MCP server

Let Claude Code, Claude Desktop, Cursor and Codex use Codz on your Mac, from your usage and plan limits to your chats, projects and scripts, through codz mcp.

codz mcp is an MCP server for the other apps on your Mac. Add it to Claude Code, Claude Desktop, Cursor or Codex, and they can read your usage and plan limits, start and follow Codz chats with any agent you have set up, and see your projects, the agents working right now, your development servers and your scripts.

It talks to the Codz that is running, so it can do only what Codz itself does. Every edit and command a chat wants still waits for your approval in Codz.

Add Codz to an app

Open Settings ▸ Connections. Under Apps on this Mac:

  • Claude Code and Codex: Add… opens Agent integrations with the app’s own command filled in. Nothing runs until you select Run.
  • Cursor and Claude Desktop: Copy copies the server entry. Paste it into the app’s MCP configuration: ~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop.

From a terminal, with the codz command set up:

claude mcp add -s user codz -- ~/.local/bin/codz mcp
codex mcp add codz -- ~/.local/bin/codz mcp

The entry for Cursor and Claude Desktop names the full path, because those apps do not expand ~:

{
  "mcpServers": {
    "codz": {
      "args": ["mcp"],
      "command": "/Users/you/.local/bin/codz"
    }
  }
}

What other apps can do

ToolsWhat they do
get_usageTokens and estimated cost for a day or a range of days, by provider, model or day. The free plan reads the last seven days; older days are Codz Pro.
get_plan_limitsHow much of Claude’s 5-hour and 7-day windows, Codex’s windows and Cursor’s billing cycle is used, when each resets, and where the current pace leads
list_chats, read_chatYour Codz chats, newest first, and resumable pages of a chat’s history. Lists page with limit and offset; a reply with next_offset continues there
start_chat, send_message, wait_for_chat, stop_chatStart a chat with an agent set up in Codz, message it, wait for its answer, and stop its turn
list_accounts, set_chat_accountEach provider’s logins on this Mac, which one new chats start on and whether a Claude subscription is out of usage, and moving a chat to another of them. start_chat takes account too
list_projects, list_agents, list_portsYour projects, the agents working on this Mac in Codz or not, and your development servers
get_local_mutationRecover a keyed change in the same MCP connection without submitting it again
list_scripts, run_script, get_script_run, stop_scriptA project’s scripts, run as they would be from the Scripts panel

Costs are estimates at each provider’s API list prices, not what a subscription bills, except where a provider states its own charge.

Read a long chat

Start with read_chat using a chat ID. It returns the latest three turns by default. Set turns up to 20 and max_chars from 1,000 to 40,000 to choose the page size. Use detail: "full" to include tool output and reasoning alongside prompts and answers.

When the response has next_cursor, pass it back as continuation with the same chat ID. Repeat until no cursor remains. This recovers the rest of an oversized turn before moving to older turns. Omit detail to keep the previous choice, and do not combine continuation with before.

Every Mac tool declares an outputSchema and returns structuredContent alongside its text. Usage, plans, agents, ports, transcript reads and waits expose their report fields directly; list responses use chats, projects or scripts. Script-run reads and mutations use resource. These contracts describe the Mac server; hosted tools may return different results.

Responses are bounded to 1 MiB on the wire, including the JSON-RPC envelope and newline. The tool result budget is 1,000,000 encoded JSON bytes, counting text and structured content together. If only the text rendering is too large, the complete structured result remains. output.truncated and output.omitted identify what was omitted. The list tools page inside the budget instead of refusing: they return fewer entries with a next_offset, and passing it back as offset reads the rest. Any other oversized read returns response_too_large without a partial record: narrow its filters or reduce read_chat's max_chars. An oversized mutation result keeps its outcome and retry identity; it never resubmits the operation or changes a committed outcome into not_dispatched. Resource details may be omitted, with the whole ID retained where it fits. JSON-RPC IDs and progress tokens must each fit in 1,024 encoded bytes.

For transcript integrations, structuredContent.items supplies turn IDs, content revisions and text offsets so pages can be reconstructed without duplicates. If a streaming turn changes during paging, transcript_changed asks the caller to reread and replace that turn. These pagination features were introduced in control API level 5; list paging arrived at level 8 and account choice at level 9. The current MCP server requires a matching Codz host with API level 9; update the running app if it reports an older version.

If a change times out

A timeout does not mean the chat or script stopped. Check read_chat, list_chats or get_script_run before sending the change again.

Mutation replies include structuredContent.mutation: not_dispatched means this attempt did not reach the mutating service; committed means Codz accepted it, while its chat or script may still be working; uncertain means its effect is unknown. A refused retry does not undo an earlier accepted change. replayed: true marks a recovered host receipt.

The server does not automatically resend a change after losing its reply. Repeating an MCP request ID is not a retry guarantee, and cancelling an MCP call does not stop work already accepted by Codz. Use the chat or script stop tool when you intend to stop that work.

Recover a change with a key

If an integration may need to recover a change, give it a unique key before its first call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stop_chat",
    "arguments": { "id": "chat-id" },
    "_meta": { "codz.com/idempotency-key": "stop-chat-20261030-001" }
  }
}

Keys work on start_chat, send_message, stop_chat, run_script and stop_script. Use 8–150 ASCII letters, digits, _, : or -. A JSON-RPC ID only matches a response to a call; it is not a recovery key. Reuse the explicit key only with the same tool and exact input. Changing a selector or argument returns idempotency_conflict.

To check the attempt, call get_local_mutation with { "idempotency_key": "stop-chat-20261030-001" } in the same MCP server process. Repeating the original keyed call also only checks it. Neither path resubmits the change. The structured result reports:

  • pending: the attempt is preparing or executing; check this key again.
  • completed: the original host receipt is available, including its mutation outcome and chat or script-run ID when one was returned. mutation_succeeded and original_error describe the original operation; the lookup itself can succeed even when that operation failed.
  • prevented: this attempt did not dispatch; its key remains consumed.
  • unavailable: the receipt is unknown or expired. This does not prove nothing happened.

Completed host receipts remain for ten minutes; pending host receipts do not expire. Each MCP server remembers up to 1,024 keys for its lifetime and refuses new keys at capacity. It never makes an old key executable again. Recovery still checks the Apps on this Mac switch and current target permissions. A restarted Codz host returns owner_changed; a new MCP server cannot recover its predecessor's keys. These keys are not durable across crashes or reconnections. Inspect the target before intentionally starting fresh work under a new key.

Cancellation suppresses the original response but leaves its keyed attempt recoverable while these limits hold. It cannot interrupt a blocking host call or undo accepted work.

What stays with you

  • Approvals and questions. Only you answer them: in Codz, on your phone, or with codz in your own terminal. No app can, and neither can an agent working in a Codz chat.
  • What a chat may change. A chat an app starts begins in ask mode, which answers without changing files. In agent mode it runs at Reviewed, so every edit and command waits for you. An app can message or stop chats that cannot change anything without asking, including chats it started; a chat you set to edit or run on its own is yours to steer.
  • Where it works. Apps start chats only in a project’s folder or one that already has chats, never in your home folder, and never on OpenRouter or DeepSeek, which are billed per token through a key Codz holds.
  • Which account. An app can start a chat on one of your logins or move a chat to another, but never onto an API key billed per token. Without an account named, a new Claude chat starts where it would in Codz: your default, or another of your subscriptions while that one is out of usage. A chat is never moved between accounts unless you or the app asks.
  • How much. One app starts at most twelve chats an hour, and apps have at most four working at once.
  • The switch. Turn off Let other apps use Codz and Codz refuses every app at once.

A chat an app starts appears in your sidebar like any other, and its first message says which app sent it.

When Codz is not running

codz mcp needs Codz. The installed app starts its background host when an app first calls a tool. Codz Development must be open first, and a tool call answers with what to open until it is.