A local router for every coding agent you use

My Claude Code is a local server that speaks four protocols at once — Anthropic's Messages API, OpenAI's Chat Completions and Responses APIs, and Google's Gemini API. Whichever one your agent already speaks, it believes it is talking to that vendor. This proxy receives the request, forwards it to whichever provider you configured, and translates the reply back into the wire format the agent asked in. Streaming, tool use, reasoning and image input all keep working.

The 16 mcc-* launchers — Claude Code, Codex, OpenCode, Gemini CLI, Crush, Cline, Goose, Aider, Kimi Code, Qwen Code, Command Code, Droid, Pi, Kilo, Roo Code, Antigravity — and the desktop apps beside them all point at one address and share this one control panel. Claude Code is one first-class client here, not the frame around everything else; it leads the walkthroughs below only because it is the one most readers arrive with.

Three things follow from that:

• The server must stay running. It is a daemon, not a library.
• Your agent's model picker can list this catalog, not the vendor's. Choosing Sonnet routes to whatever you mapped Sonnet to. Codex and Pi's pickers always do this; Claude Code's needs model discovery on (see the Claude Code section below).
• Provider keys never leave the machine. Your agent only holds a token that authenticates it to this proxy.

Three steps to working: add a provider key, map the model tiers, point your agent at http://127.0.0.1:8082.

First run, end to end

Eight steps, in order, from nothing installed to a request you can read in the log. Everything after this section is a single topic in depth; this is the path through all of them. It is written with Claude Code as the client because that is the most common arrival, and every step except the one that writes its settings.json is the same for Codex, Gemini CLI, Aider or any other agent — the “Point another CLI here” section swaps that one step out.

1. Install. In the Windows Command Prompt, curl -fsSL -o "%TEMP%\install-mcc.cmd" https://raw.githubusercontent.com/FiredMosquito831/my-claude-code/main/scripts/install.cmd && "%TEMP%\install-mcc.cmd" — it fetches the same installer and runs it with the execution policy bypassed, so PowerShell can never refuse it. In PowerShell, & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/FiredMosquito831/my-claude-code/main/scripts/install.ps1"))); in WSL, Linux or macOS, curl -fsSL "https://raw.githubusercontent.com/FiredMosquito831/my-claude-code/main/scripts/install.sh" | sh. On any platform with Node, npm install -g @firedmosquito831/my-claude-code is the same thing through a third door: the package is a wrapper that runs the digest-verified installer above with the desktop flag, so it leaves you the server, every mcc-* command and the desktop app, plus mcc as an alias (npx @firedmosquito831/my-claude-code runs it without installing globally, and installs nothing until you ask for a server). Pick one environment and stay in it — PowerShell and WSL keep separate config directories (C:\Users\<you>\.mcc and ~/.mcc inside WSL), and installing in both is the usual way to end up editing the config your server is not reading. There is a second way in on every platform: download the desktop app from the latest release — MyClaudeCode-Setup-windows-x86_64.exe, MyClaudeCode-linux-x86_64.deb (or the .tar.gz), or MyClaudeCode-macos-universal.dmg — and run it. That installs the desktop app only — no Python, no server, no admin rights — and the app runs the command above for you, in its own window, the first time you launch it. The macOS image is unsigned, so after dragging the app into Applications run xattr -d com.apple.quarantine "/Applications/My Claude Code.app" once; installing with the command above and running mcc-desktop avoids that step entirely.
2. Reopen the terminal, then start the server: mcc-server. It is a daemon and must stay running; close it and every agent pointed at it stops working. The startup log prints the admin URL.
3. Open the dashboard at http://127.0.0.1:8082/admin. The Get Started page is a live checklist — each step is ticked because the thing is really configured, not because you clicked something. Work down it and you have done this walkthrough.
4. Add a provider. Two ways, and both end on the same card:
   • A provider MCC already knows: on Providers, type its name into Search providers — the box matches the variable name too, so GROQ_API_KEY finds Groq. Press Configure, paste the key into Add key, press it.
   • Anything else with an OpenAI-compatible endpoint: press Add custom provider, give it a base URL and a key, and press Add provider. MCC probes the host once to learn which dialect it speaks and records what came back.
   Either way, press Refresh models and watch the model count change. That is the only proof the key works; a card can look healthy on a key that cannot list models. A fresh install can skip this step for Claude Code's big tiers: since 7.78.0 Mythos, Fable, Opus and Sonnet start on OpenCode Zen's free model, which needs no key (the OpenCode Zen card says Free models ready). Haiku and the Default Model still need one.
5. Look at what you actually got on the Models page. Every model the provider offered is here, each with where its facts came from and which tiers it is eligible for. If a model you expected is missing, it was missing from the provider's own /models answer — press Refresh models on the card rather than editing anything here.
6. Set the tiers on Model Config. Default Model is the only required one: it answers anything you have not mapped. Map the small tier to something cheap and fast before you map anything else — agents hit it constantly for bookkeeping, and it governs how quick the whole session feels. Press Apply.
7. Launch an agent from Coding agents. The page lists every CLI this proxy can launch and says whether each binary is on your PATH. Copy a command from a card you have installed — mcc-codex, mcc-opencode, mcc-crush, mcc-gemini and the rest — and run it. The launcher hands that CLI a config file this server already wrote; nothing of yours is edited.
8. Read the request on Analytics. Ask the agent anything, then refresh. The row names the model that answered, the agent that asked, and what it cost. If nothing appears at all, the agent never reached MCC — the request went straight to a vendor instead, and the fix is in that agent's configuration, not here.

A tick on Get Started is a measurement, not a memory. Every required step is recomputed from live configuration each time the page loads, so a step un-ticks itself if you later remove the key it was reporting. The two optional steps that cannot be measured — reading this Guide, and opening the Coding agents page — are done because you went there.

Add a provider

On the Providers tab, type the provider's name into Search providers — it also matches the variable name, so GROQ_API_KEY finds Groq. Press Configure to open that provider's key pool, paste your key into Add key and press it. Keys save immediately; Apply is not needed for them.

A provider holds a pool of keys rather than one value. Paste several separated by commas to add them together, give each its own Remove, and pick a Rotation policy when you have more than one (that one does need Apply, and takes effect on the next request without a restart). Then press Refresh models: it makes a real API call, so a model count means the key works and My Claude Code can read that provider's catalog. Choose the model itself on Model Config.

OpenCode Zen needs no key for its free models. They go out on OpenCode's own anonymous credential (7.34.0), so with no key the OpenCode Zen card says Free models ready and “Configured by default” (7.78.0). A key is needed only for its paid models and for OpenCode Go, which shares it; the OpenCode Go card says Missing key until you add one. Switching OpenCode free-tier credential to key turns the anonymous credential off, and the Zen card then says Missing key too, because nothing can be served.

OpenCode Zen and OpenCode Go read who is calling. Both gateways take a set of identity headers off every request — which program, which version, which project, which conversation, which call. Before 6.69.0 My Claude Code sent none of them, and on 2026-09-10 the Zen free tier was measured answering such a request 400 MissingSessionID, “OpenCode's free tier can only be used in OpenCode”. The same request carrying the five headers was answered 200. So 6.69.0 sends them, and by default it sends the values the official OpenCode client sends. It is not the OpenCode client, so that is a claim made on your account's behalf: the OpenCode Client Identity field on the OpenCode Zen card switches it to mcc, which sends my-claude-code and this version instead. The conversation header — the one the host was measured acting on — goes either way, and the header naming your coding agent never leaves this machine. If the host later benches you on its daily free quota, the 429 that resets at midnight UTC is recorded against the provider and shown on Models.

OpenCode Go's Chat endpoint preserves earlier thinking in its native reasoning_content field. A requested max is sent as max when the existing model checks permit it; xhigh still maps to high. Updating an existing conversation can lose a prefix-cache hit once because earlier thinking is no longer replayed as tagged answer text.

What changed in 7.92.2 and 7.92.3. From 2026-10-13 the Zen free tier refused every request MCC sent with 403 FreeTierError: it reads a creation time out of the conversation id in x-opencode-session, and MCC's ids read weeks old. Since 7.92.2 MCC mints that id the way OpenCode does — the clock at the moment MCC first sees the conversation, then random characters — one per conversation, kept until the server restarts. Since 7.92.3 it also sends x-opencode-session-id with the same value (as OpenCode 1.19.0 does), and when the agent calling MCC is OpenCode itself with an id in exactly OpenCode's shape, that id is sent on unchanged. The addresses are https://opencode.ai/inference/v1 (Zen) and https://opencode.ai/inference/go/v1 (Go), what the vendor's registry publishes; they are not a setting, so every install uses them from its next start. A request with no tools to a free model (a title or summary call) now carries OpenCode's five tool names, each marked as not to be called, because the free tier refuses tool-less requests; Probe capabilities asks free models the same way. Paid models and OPENCODE_CLIENT_IDENTITY=mcc are unchanged. The free-usage limit is counted per key — free models use OpenCode's own anonymous public key, not yours — and that shared bucket also follows the address you call from, which is why a proxy chain can lift it one exit at a time.

New in 6.74.0 — OpenCode Zen is four APIs, not one. Which one a model is served on is a property of that model, published in OpenCode's own registry, and two of the seven free models Zen lists today (both Muse Spark contributor models) live on the Responses API. Sending them to Chat Completions came back as a bare HTTP 500 with nothing in it — the vendor has an open issue calling that a missing “wrong endpoint” error. MCC now resolves the endpoint per model and shows it on Models as a wire surface row: responses (registry) when the vendor published it, (learned) when MCC probed this deployment and found out, (override) when you pinned it, and chat_completions (profile) when nobody has said anything at all — which is what a fresh install sees, because its copy of the vendor registry has not been fetched yet. The note beside that one says which silence it was. If the endpoint MCC picked refuses in a way that is about the endpoint, MCC spends one tiny probe on the other one, remembers the answer and retries your request there. Nothing is ever hidden: a model Zen serves through an API this provider does not speak keeps its row and reads unservable with the reason.

That 404 case catches people constantly — check the exact model id against the provider's own list before assuming the key is bad.

An OpenAI-compatible endpoint with no card of its own goes in under Custom providers — a display name, a base URL and a key. Two things differ from a built-in card. The base URL is used verbatim, so it must already end in /v1 (or whatever the gateway's own curl example puts before /chat/completions); My Claude Code does not append it. And its keys live in ~/.mcc/custom_providers.json, not ~/.mcc/.env. Creating, enabling or re-keying one reads its model list once and publishes it everywhere immediately, with no restart; if that read fails the card says so, and Refresh models retries on demand.

Local backends take a base URL instead of a key, and offer Test connection where remote providers offer Refresh models:

LM_STUDIO_BASE_URL="http://127.0.0.1:1234/v1"
OLLAMA_BASE_URL="http://127.0.0.1:11434"

Everything is stored in ~/.mcc/.env. Edit that file directly if you prefer, then restart the server — config is read at startup.

If you installed before 6.40.0, your configuration is in the legacy ~/.fcc instead — the same file, the same everything, just the older directory name. It stays fully supported and MCC never moves it for you. The startup log names the directory actually in use, and so does the banner at the top of Get Started.

To move it, stop the server and quit the tray, run mcc-migrate in a terminal, then start the server again. That renames the directory in one atomic step — nothing is copied, deleted or merged — and leaves a ~/.fcc-old/RESTORE.txt note saying how to undo it. There is deliberately no button here for it: relocating your keys and your request history should not be one click away in a browser tab, and on Windows the rename cannot succeed while this server is running anyway. To pin a directory instead, set the MCC_CONFIG_DIR environment variable to an absolute path before starting the server.

The file records what you chose, not what the defaults are. A setting you never touched is written as a commented placeholder naming its default — # FALLBACK_BENCH_ENABLED= (default: false) — while a plain KEY=value line means the dashboard set it, and the field shows set here. Every field prints its default underneath, and one that was set gets a Use default button that removes the line again. That is also why a switch is a three-way select — Default, On, Off — and why every list carries a Default option: a checkbox has nowhere to say "I have not chosen". Leaving a setting alone is what lets a later release improve its default for you; choosing the default explicitly pins it against that.

Use Claude models

There are two Anthropic providers and the difference matters.

Anthropic (Claude API) is the ordinary path: a Claude Console API key, billed per token like every other provider here. Create one at platform.claude.com, paste it into the card, press Refresh models, and set a model ref such as anthropic/claude-sonnet-4-6. This is the authentication method Anthropic documents for software that calls Claude on your behalf.

Claude models also arrive through bedrock, vertex, and gateways such as kilo, nous_portal and cline — all pay-per-token, none with a policy question attached. And the two-door pattern still works: keep native claude for your subscription, and use mcc-claude for everything else.

Map model tiers

Routing is by tier: Mythos, Fable, Opus, Sonnet, Haiku and a fallback each map to a real model on your provider. That is what lets an unmodified agent run on any backend. Each rail heading also carries the id every other coding agent asks for to reach it — Mythos (mcc/cyber), Fable (mcc/best), Opus (mcc/good), Sonnet (mcc/medium), Haiku (mcc/cheap) and the Vision adapter (mcc/vision). The Default rail carries none, because it is not a tier: it is the route every unset rail falls back to, including Fable's. Before 6.51.0 mcc/best named the Default rail; if you never filled Fable in, it still lands there. Mythos is new in 7.2.0; on an install first started before 7.78.0 it is unset, so claude-mythos-5.1 and mcc/cyber follow MODEL until you fill the rail in — which is exactly where they went before 7.2.0. Mythos leads the list but is never the default: apps that are told a default model are still told mcc/best.

New in 7.78.0 — a fresh install already has four rails filled. The first start of a new install writes Mythos, Fable, Opus and Sonnet as opencode/muse-spark-1.3-contributor-free, OpenCode Zen's free model, which needs no key — so Claude Code works before you add one. Haiku and the Default rail are not filled in: Haiku follows MODEL, which still names an NVIDIA NIM model. An install from before keeps exactly what its settings file says, and a blank or missing rail still follows MODEL. A filled rail uses only its own fallback chain, and a fresh one has none, so add one if the free model's daily limit (429, reset around midnight UTC) or its withdrawal (401 "not supported") should not stop those tiers. Use default on one of these rails clears it back to MODEL.

Map Haiku to something cheap and fast. Agents use the small tier constantly for internal bookkeeping, and a slow model there makes the whole session feel sluggish even when your main model is quick. This affects perceived speed more than any other setting here.

Reserve the big tier for real work, and point the fallback at something cheap so unmapped requests cannot surprise you.

Every other coding agent gets these tiers too. Claude Code never names a model — it asks for claude-sonnet-5 and gets whatever you mapped Sonnet to. Every other agent had to name a real provider/model ref, so a model id typed into its config a month ago is still that id today however many times you moved the route it should have followed. Six names now sit at the top of every generated picker — mcc/cyber (Mythos), mcc/best (Fable), mcc/good (Opus), mcc/medium (Sonnet), mcc/cheap (Haiku) and mcc/vision — each carrying that route's own fallback chain and pause list. An unset tier follows MODEL, exactly as claude-opus-5 does, and the card says so rather than inventing a model for it. One agent can be given its own chain per tier under Tiers on its Coding agents card; nothing else is affected.

Managing many models at once. Each provider header carries Show all, Hide all and Invert, and they act on whatever the filter and the state chips have narrowed the provider to. Tick the boxes in the left gutter to pick models by hand — click one and Shift-click another for a range, Shift+arrow to extend or shrink one from the keyboard, or press and drag down the gutter — then use the bar at the bottom. That bar is the only way this page changes what the catalogue shows, for one row as much as for three hundred; the word beside each checkbox is a readout — Shown, Hidden, or Hidden by nous_portal/* — and not a second control. Hide all for a whole provider writes one pattern like nous_portal/* as a standing policy, so models that provider adds next week are hidden on arrival too. It shadows the exact patterns underneath rather than deleting them, so the first Show all afterwards lifts only the glob and hands back exactly the per-model state you had before; press it again to clear those too. A glob you wrote yourself is never deleted on your behalf — if one of yours still hides a model, that row says Hidden by it, and clicking the pattern offers to remove it. None of this changes routing: a hidden model still resolves and still serves.

994 patterns and no globs? Ticking models one at a time writes one exact pattern each, and a real install reached 994 of them — a 30 KB line rewritten on every write. Migrate exact patterns to globs, beside Save patterns, folds every provider whose models are all individually hidden into one provider/*. It previews first: how many patterns become how many, and how many models are hidden before and after. It is only offered when those two numbers are equal, and the write is undoable.

Filter first, then act on what is left: / jumps to the search box, Select all N on the result count takes exactly the filtered set, and Escape clears the selection again. Provider headers stick to the top of the list with their visible/hidden/configured counts, and Hide all works while the provider is collapsed. Above 200 models the button asks once, in place. What happened is written into the status panel and stays there — no toast to miss — with an Undo that restores both lists exactly.

Give each tier a fallback chain. Press Add fallback under a tier's model to name a stand-in, and another for a stand-in after that. If the model a request routes to cannot serve it, the next entry takes over — a free model that rate-limits at the wrong moment stops being the end of the request. A model may appear more than once — the tier's own model again further down, or one fallback twice. Each appearance is one more try, judged when it is reached exactly like any other entry: its pause, its bench, the rate-limit cooldown and the same-key retries all apply to it, so a model still cooling down is stepped over unless it is the last entry. Every row of a repeated model carries a small ×2 chip.

Reorder a chain by dragging it. Every entry has a grip on its left. Drag it to move the row; hold Ctrl (or Cmd) while clicking to pick several, or Shift-click for a run — Shift+Space and Shift+↑/↓ on a focused grip do the same from the keyboard. Drag onto another tier’s card to copy the model there, hold Shift as you drop to move it instead; within one card hold Ctrl (or Cmd) as you drop to copy a row into the same chain, and drop onto a card’s top slot to make that model the route’s own — whatever it replaces becomes fallback 1. A group lands in the order it has on screen. The up/down arrows still do the same job one step at a time, Ctrl+Z undoes the last drag, and nothing is written until you press Apply.

Pause one entry without deleting it. Each row has a Pause button. A paused model keeps its place and stays on screen with its whole name, but the router never tries it: no attempt is spent on it and no deadline is consumed, and it still appears in the request log under not tried with the reason paused — so a paused route is still readable. A pause takes effect immediately, with no Apply, and the panel at the top of this page offers an Undo. If it fails, that same panel says so and the row returns to the state it was really in. After a Save or a reload, every row shows its real state straight away, and a click always sends the opposite of what its button showed; if the button was showing an older state, nothing is sent and the row is redrawn. Pausing an entry on one route does not pause the same model on other routes. A ref that appears in two chains is two entries; pause it on each route you want it off. Pausing is not hiding. Hiding a model on the Models page only changes what appears in listings and never changes routing; pausing only changes routing and never changes listings.

Failover stops once you have seen output. A model that fails while connecting, authenticating or rate-limiting is replaced silently. One that dies halfway through streaming an answer is not, because switching then would splice two different replies together — so a chain rescues the failures that happen before the first word, not the ones that happen at word five hundred.

A context-length rejection no longer ends the chain. A model that answers “this prompt is too long” with an HTTP 400 used to stop the route dead, because a 400 normally means you sent something invalid and retrying it elsewhere is pointless. A prompt that overflows one model’s window is the exception: the very next model on the chain may hold twice as much. Those rejections are now classified as context_length and the chain continues, so a long session falls through to a roomier model instead of failing. The reason is spelled out when it happens — Request exceeds this model’s context window. Needed about N tokens; this model holds M. To get the old fail-fast behaviour back, add context_length to FALLBACK_SKIP_KINDS, which defaults to invalid_request.

Neither does a model refusing the request. Since 6.46.0 a 400 only ends the route when the provider’s own message says the request is malformed. Every other 400 — a model that host does not serve on that endpoint, a sampling value one model pins, a tool name longer than that dialect allows — is the new model_rejected kind, which is not in FALLBACK_SKIP_KINDS by default, so the next model gets its turn. Measured over 274,375 requests, every 400 this install ever received was one of the latter, and each one ended a chain with healthy models still in it. Your client sees no change: both kinds still go out as invalid_request_error. To restore the old behaviour, set FALLBACK_SKIP_KINDS=invalid_request,model_rejected.

Neither does running out of credits. Several gateways answer an account with no balance left with an HTTP 400 that calls itself an invalid request — one measured on 2026-09-02 said “You have insufficient credits to make this request. Please purchase more credits to continue using the service.” and six configured fallback models were never tried. That is now its own kind, quota, matched on the provider’s own words (a 402, or a 400/403 naming an explicit billing phrase) and never on a bare mention of “credit”. MCC rotates to the next key first — another key may have credits — then falls through to the next model, and benches the empty key for RATE_LIMIT_COOLDOWN_SECONDS. The Models page shows it as COOLDOWN — credits exhausted. If every model ends this way you are told plainly: all keys reported exhausted credits, pointing at Providers.

Images are routed separately. Plenty of fast text models cannot read a screenshot at all. Set a Vision adapter and any request carrying an image goes there instead, but only when the tier's own model is known not to accept images — a model nobody publishes capabilities for is left alone rather than diverted. When that applies to one of your tiers, its card says so directly, and the adapter gets its own Add fallback chain like any other route.

Or the image can be described instead of rerouted. Vision adapter mode, in the same card, chooses. Route — the default, and what every release before 6.51.0 did — sends the whole request to the vision model, so the vision model answers it. Describe sends each image to the vision model on its own, puts its answer in the picture’s place, and lets the model your tier actually picked answer the question. Pick describe when your coding model is fast, cheap and blind and the screenshot is context rather than the question — in route mode the vision model has to answer a coding question it has no context for. Pick route when the picture is the question. Descriptions are cached against the image itself, so a screenshot re-sent every turn is described once; Clear image descriptions on Requests forgets them. If a describe call fails, the request falls back to route mode and then to a plain sentence — it is never the reason you lose an answer.

An image a tool returned now arrives as an image. A browser screenshot, or a Read of a PNG, comes back nested inside the tool result — and no OpenAI-format chat message can carry an image there. Before 6.49.0 MCC turned it into base64 text, and every OpenAI-dialect provider billed roughly one token per byte for a picture the model never saw: one 213 KB screenshot measured 324,000 prompt tokens, four of them failed the request outright. It is now moved into a short message right after the tool output, marked as tool output rather than as something you typed. TOOL_RESULT_IMAGE_DELIVERY on Model Config picks the rule, and each request records which one applied.

Afterwards, Analytics shows the whole path a request took: which models were tried, which one answered, and whether the vision adapter stepped in.

What MCC knows and learned

The Models page is where every model MCC has discovered lives, and it answers two different questions about each one: what its provider publishes, and what this deployment has actually taught MCC by refusing something.

The provider's own words are kept. Where a provider's model list says what a model accepts and produces, what type of model it is, or which endpoints serve it, the model's table shows it in the provider's own words — the accepts → produces, model type and endpoints rows — with the source and rung beside it, like every other row. Where the list is silent, the pair comes from models.dev and the other two read unknown. They are shown, not acted on: no list, kind or route reads them. Refresh models on a provider card records them at once.

The provider's own numbers come first. Where a provider's model list publishes a model's context window, output limit, listed input and output price, or says it reasons or takes tool calls, that is the answer MCC uses — models.dev only fills what the list left out. The model's table says which: provider /models with the rung it matched at, or provider /models or models.dev where the value came from the catalogue. A provider's own output limit is also the one MCC clamps a request's max_tokens to. What a request is charged is unchanged: Analytics still prices it from the provider's own reported cost, then models.dev, then LiteLLM (if you turned it on), then the cross-provider vote.

OpenRouter's own live list is a rung for every provider. MCC reads OpenRouter's public model list — every model it serves, matched to your providers' models by name (exact id, tag stripped, bare model) — and uses it like this: what a model accepts and produces (so its kind), whether it reads images, reasons or takes tool calls come from it right after the provider's own list for a provider models.dev does not describe; for one models.dev does describe, only where that catalogue said nothing — where the two disagree, the panel shows both. Window, output limit and prices come from it last, only where nothing else said. Each such row is badged OpenRouter live with how the name matched. It also adds three rows: a description, a knowledge cutoff, and listed on OpenRouter — the day OpenRouter added the model, not its release date. None of it reaches a request: output caps, context room and reasoning are decided exactly as before, and the generated agent catalogues are the only other place it shows. The list is fetched in the background at the models.dev catalogue's freshness, through the OpenRouter proxy chain if you set one (Proxying page). MODEL_METADATA_OPENROUTER_LIVE (Model Config, catalogue card) turns it off, and then nothing differs from before it existed.

When a model was published, when it retires, what it knows. Each model's panel on the Models page shows a description, a knowledge cutoff, a published day and a retires row, each badged with the source that said it, the provider's own model list first. Description and cutoff: the provider's list, then OpenRouter's live list, then models.dev — where the provider's own words and OpenRouter's differ, the provider's are shown and OpenRouter's are listed beside them as also stated. Published: the day the provider's list says it published the model (a list that stamps one value on every row says nothing, and OpenRouter's own created is its listing day, shown in its own row), else the vendor's release day from models.dev (where catalogues disagree evenly, the earliest). Retires: the vendor's own client catalogue, then the provider's list, then LiteLLM's map if Use LiteLLM's price map too is on, then models.dev's deprecated mark, which has no day. With that LiteLLM setting on, LiteLLM's map also fills the endpoints row where the provider names none, and is one more source for a model's kind — see below. All of it is shown only: nothing here changes a route, a list or a price.

Everything known about one model. Under each model's panel on the Models page, open Everything known to see what every source says about each field, beside the value MCC uses (marked used): the provider's own model list, what discovery filled from models.dev, OpenRouter's live list, models.dev's own bucket for the provider, models.dev's copy of OpenRouter, the cross-provider vote (with how many same-named rows stated it), LiteLLM's map when Use LiteLLM's price map too is on, what this host taught MCC, your own overrides and media rails, and the vendor's own client (the Codex CLI's catalogue for ChatGPT). A highlighted statement says something different from the value in use; a dimmed one comes from a rung MCC never reads for that provider — a provider with a models.dev bucket of its own is never answered from outside it. Below the table, each source's own row is listed verbatim, field by field, so a field no row of the panel shows (a tokenizer, a moderation flag, a benchmark score) is still there to read. It is read when you open it, for that one model, and it is shown only: nothing routes, lists or prices on it.

Read a model's fields and override one

Open a model on the Models page and everything about it is one table, in groups: Limits (context length and output limit), Reasoning, Request parameters (the nine sampling fields sent in the body), then the rows you read but do not set — Wire surface where the provider serves more than one endpoint, What the model is, Prices, Dates and Gateway lists. Every row reads the same way: the field, the value MCC uses, and where it came from — a badge for the source and the rung of the ladder that stated it.

A row you can override has its control in the last column: Inherit, Force unset or Force value, and the box for your value. Under the control, whatever you pick, is the default — what MCC would use without you, and where it came from: the context window and the output limit from the provider's own list or models.dev, with the rung; the reasoning word from the route itself, with the model's published effort words and what the host parses; each sampling parameter from the provider's own default_parameters. Only OpenRouter-style lists (OpenRouter, Kilo, Nous Portal) publish those, so most of those rows honestly say default not reported and name what was asked. A row something forces is tinted, and its value cell shows the forced value with an operator override badge and the row it came from — the model's or the provider's; the default stays under the control. Save overrides writes the same file it always did, in the same order, and nothing a request sends changes until you save. Pin endpoint on the Wire surface row keeps its own save. The override(s) active chip beside a model's name counts every key you set that reaches it — the output cap, the context window and the reasoning word included.

Your own context window for one model. Each model's table on the Models page has a context length row (context_length) beside the output limit (max_output_tokens): Force value replaces the window MCC extracted — for the output-budget headroom routing keeps and for every generated agent catalogue — Force unset makes it unknown, and the extracted number stays visible beside yours as also stated, and under the control as its default, with the rung it came from (Read a model's fields and override one).

Catalogues re-read themselves. Every usable provider's model list is fetched again in the background once an hour, so a gateway that added a model this morning is listed this afternoon without a restart. The line under Providers and models says when that last happened and when it happens next; the server log says catalogue changed: +N -M when the list actually moved. MODEL_DISCOVERY_REFRESH_SECONDS is the interval, in seconds, and 0 turns the sweep off — in which case the same line says so rather than going quiet.

This is not Claude Code's model discovery. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY is a variable MCC writes for Claude Code and never reads; it decides whether Claude Code's own picker lists this catalog. The setting above decides how often MCC re-reads its providers. Changing one does nothing to the other.

The Learned chip filters to models this host has corrected. Every negative MCC holds was learned from something the upstream itself said — a 400 naming an output ceiling, a retry that only succeeded once a reasoning field was dropped, a probe that came back without vision. Open a model and the What this host taught MCC block lists them with the evidence, the age, and a Forget link.

Facts survive a restart — they are written to ~/.mcc/learned_facts.json — so an upgrade does not re-pay every 400. They expire because they have to: MCC stops sending the thing that would produce a positive, so a host that raises its own cap has no way to tell us. Three evidence classes, three clocks:

Expiry never deletes. A fact past its clock is still loaded and still shown — marked stale — and simply stops being applied. The next real request re-pays one rejection and the row is fresh again. That is the self-healing a restart used to give for free, put back on a timer.

Probe capabilities asks instead of waiting. The button on a provider card sends a handful of deliberately tiny requests — a one-pixel image, a trivial tool definition — and writes down what came back, so a model's real vision and tool support are known before a real request pays for the discovery. A probe is narrow: it only ever records an absence the host demonstrated, never a capability the catalogue already claims. No response text is stored for any fact — the evidence is a bounded, redacted excerpt, and for a probe it is a status word and at most an HTTP code.

Forgetting works at three scopes. Forget on a row drops that one fact; the button on a provider card drops everything learned about that provider; Forget everything learned under Requests clears the store. Use it when you have changed something on the host's side — a raised quota, a new deployment behind the same name — and do not want to wait out the clock.

Tiers for every agent

Claude Code never names a model: it asks for claude-sonnet-5 and gets whatever you mapped Sonnet to. Every other coding agent had to name a concrete provider/model ref, so a model id typed into its config a month ago is still that id today, whatever you have since changed here. Five aliases close that gap. They are pointers to the same routes the Claude aliases use:

Inside a CLI these appear under the provider mcc, which is why OpenCode's own flag reads -m mcc/mcc/best — one mcc for the provider, one for the alias namespace. Two segments, not three: mcc/tier/best would buy nothing and would make Kimi's generated key mcc/mcc/tier/best.

An unset tier collapses onto MODEL. If you have not mapped Opus, then mcc/good resolves to the same place an unmapped mcc/best does — exactly as claude-opus-5 already does today. Four agents asking for four different tiers can therefore all land on one model, and nothing is wrong. The dashboard says so rather than hiding it: MCC choosing a distinct model for a tier you left unset would be MCC picking a model for you.

Per-agent overrides. The Coding agents card has a Tiers section for saying "best means this in Crush, and the global thing everywhere else". Each (agent, tier) pair has three states, and the middle one is the reason the feature exists:

• No entry — inherit the global tier chain. The default for every agent and every tier.
• An entry with no model — keep the global primary, but use this agent's own fallbacks and pauses.
• An entry with a model — this agent's own chain leads.

A tier may never point at a tier. An override resolving to something in the mcc/ namespace is dropped with a log line, because it would either loop or resolve through a provider id that does not exist — and neither failure is visible from the file that caused it. Overrides live in ~/.mcc/harness_tiers.json; the card is the supported way to edit them.

Reasoning

Whether a request carries a reasoning instruction is decided by two facts, not one: what the model has a knob for, and what the host has a field for. A control is only sent when both are true. When they disagree the nearest thing both can express is sent instead, and when nothing can be, nothing is sent and the request detail says so in those words — no reasoning instruction sent (model default applies). Each model on the Models page states which dialect its host speaks and where that came from: default OpenAI dialect, declared by this provider, or learned from the host's own rejection.

Hosts that never mention reasoning still get it. Any OpenAI-compatible host with no dialect of its own is assumed to parse reasoning_effort over the classic four rungs minimal | low | medium | high — sent only when the model's own metadata says it has effort control. If such a host answers 400 naming that field, the request is retried once without it, that provider and model is remembered for the life of the process, and the Models page relabels the dialect as learned. A 400 about anything else still fails visibly.

Every provider learns this way, not just the OpenAI-compatible ones. An Anthropic-protocol host that refuses a thinking object, and a Responses host that refuses a reasoning block, are read by the same matcher and relabelled the same way. The same 400 also teaches the output cap a host states for itself — max_tokens: 100000 > 64000, which is the maximum allowed number of output tokens for … — and later requests clamp to it without paying the rejection again. Both memories are lost on a restart or a config reload, on purpose: a host that was briefly broken heals by itself.

A rung you ask for is a rung you get. An effort you name that the host cannot spell is clamped to the nearest rung it can, never quietly replaced by that host's own default — so max becomes high on a four-rung host rather than medium. The same rule covers a model that only has on/off sitting behind a host that only speaks effort: it leaves as your rung, clamped. Hosts with an honest on/off field keep using it. Where a catalogue disagrees with itself about a reasoning control, the more capable of the two records wins — controls only; numeric limits still take the tightest.

Reasoning needs room, and takes it from the same budget as the answer. Thinking tokens and reply tokens come out of one max_tokens, so an agent asking for 8,000 can spend all of it thinking and return one sentence. When the resolved policy asks for reasoning, the budget now starts from the larger of the client's ask and the model's own published output limit, then narrows as before — model limit, ceiling, context headroom. A model whose limit nobody publishes is never widened, and max_tokens: 0 is left alone. The request detail names it when it happens: max_tokens raised from 64,000 to 131,072 for reasoning. Turning reasoning off changes nothing about the ask.

What comes back is measured separately from what was asked. The Models page counts reasoning requested and reasoning returned as two independent facts, and Analytics stores the second as thinking_chars: 0 means a stream completed and carried no reasoning, while Not measured means nobody counted. From 6.73.2 the ChatGPT (Codex) provider returns thinking blocks whenever the endpoint sends a reasoning summary — its Responses protocol names that channel as an event type rather than a delta field, and the converter had no branch for it, so 2,671 of 2,671 requests over seven days read returned 0 while the summary was arriving on 57% of them. Rows written before that release stay at 0: they record what was delivered, and nothing is backfilled. A turn where the endpoint sends only encrypted_content and no summary still reads 0, and correctly — the model thought and released none of it, so no empty block is invented.

MAX_OUTPUT_TOKENS_CEILING on Limits & Resilience caps that widening and ships set to 131,072. It is set on purpose: widening asks for the model's maximum, and OpenAI- and Azure-style limiters reserve max_tokens against your per-minute budget before generating a word, so an unbounded thinking turn on a 262,144-output model can be rate-limited for tokens it was never going to use. Blank means the default; 0 is the sentinel for no ceiling at all.

Prompt cache lifetime

A host keeps a prompt cache for a lifetime chosen from its own short list. Anthropic — the Claude API and the Claude subscription — keeps one for 5 min (its default) or 1 h, and nothing in between. Claude Code's terminal app already asks for 1 h on its own cache markers; Claude Desktop and the SDKs leave Anthropic's 5 min. By default MCC forwards whatever the client sent, byte for byte.

To choose instead, open Model Config → Reasoning → Prompt cache lifetime: one default (PROMPT_CACHE_TTL, From client) and one per tier beside its thinking level (PROMPT_CACHE_TTL_OPUS and the others, Inherit). A tier's own value wins over the default, and From client at any level means MCC sets nothing there. Minutes from 1 to 60 are never sent as a number: they are adapted to what the host accepts — the shortest lifetime that is at least the minutes you asked for, else the host's longest. On Anthropic, 1–5 sends 5 min and 6–60 sends 1 h. Every marker the client wrote then carries that lifetime (a marker with none already means 5 min and is left as written when 5 min is the choice), and a request with no marker at all gets Anthropic's single top-level one. The change applies on the next request; no restart.

A longer cache costs more to write. Anthropic bills a cache write at 1.25× the input price for 5 min and at 2× for 1 h; reads are cheap either way. Since 7.111.0 MCC's cost figures price each write at the rate of the lifetime it was written with, as Anthropic reports it, or say not priced where no source states the 1-hour rate (see What a request cost). Hosts that cache automatically, and hosts nothing is known about, get nothing from this setting (see Other hosts). If a host answers 400 naming the lifetime field, that lifetime is remembered as refused (Models page, with Forget, 30 days) and later requests use the lifetime that remains; the refused request itself fails over exactly as any 400 does. Each request's detail records prompt_cache_ttl: the minutes asked, which setting or row asked them (from), the lifetime sent and the lifetimes the host takes.

Set it for one provider or one model

On the Models page, every model row and every provider's table has a prompt cache lifetime row (prompt_cache_ttl in model_overrides.json): Inherit, Force value in minutes from 1 to 60, or Force unset, which is From client on that row — MCC sets no lifetime there even when a tier asks. Who decides: the model's row, then its provider's row, then the tier, then PROMPT_CACHE_TTL, then the client. Under the control the default is always written: the Model Config lifetime each route that names the model reads, and what the host would be sent (default 30 min — PROMPT_CACHE_TTL_OPUS → sent 1 h).

Gateways that speak Anthropic's protocol — Command Code's claude-* models, OpenCode Zen's Messages door, custom providers with the Messages door — publish no cache lifetime, so their rows say lifetimes unknown — sent only when set on this row. Model Config's lifetimes never reach them; a provider or model row does, sent in Anthropic's own spelling of the nearest Anthropic lifetime (1–5 min sends 5 min, 6–60 sends 1 h) on the markers the client wrote, with none added. Whether the gateway passes it on is not known: the first refusal stops lifetimes for that whole host until you press Forget on any of its rows.

Other hosts

Claude models through OpenRouter (anthropic/… and ~anthropic/…) take Anthropic's two lifetimes. MCC's conversion for OpenRouter keeps none of the client's cache markers, so with nothing set they are sent no marker and do not cache there; with a lifetime set, MCC adds the one top-level cache_control marker OpenRouter documents as automatic caching, with 5 min (1–5) or 1 h (6–60). Azure OpenAI takes its retention word, prompt_cache_retention: in_memory (cleared after about 5–10 idle minutes) for 1–5 and 24h for 6–60, priced the same. A deployment that refuses one word is sent the other next time.

The ChatGPT subscription, Gemini, Vertex, DeepSeek, Nous Portal, OpenCode Zen and Go, NVIDIA NIM, Agnes, B.AI, HyperCharm and every OpenRouter model that is not Claude cache automatically and take no lifetime: their rows say caches automatically; no lifetime control and nothing is ever sent to them. Any other host says lifetime control not known for this host.

InferHub: set a price ceiling

InferHub is a marketplace: for one model there are many sellers' accounts at a handful of price levels, and with no ceiling InferHub picks one regardless of price — up to half the model's official price, and a conversation that stays with its seller later pays that seller's current price. MCC's answer is a ceiling sent with every InferHub request, chosen by a marketplace profile.

1. Add INFERHUB_API_KEY on the InferHub card. An InferHub link appears in the left nav (only while a key is set).
2. Open the InferHub page and press New profile: for example At most N % of official with 10 (at most 10 % of each model's official price), named opus-cap. The editor checks it before anything is saved; profiles are kept in marketplace_profiles.json in the config folder.
3. Under Assignments, set the provider default to your profile and press Save. A model's own row can name another profile, or InferHub decides — no ceiling, shown in red. This is the same marketplace profile row the Models page shows.
4. Pick a model in the Offer explorer: its price ladder, with your ceiling drawn as a dashed line, how many seller accounts ask at or under it, and its speed, success and cache hit. Would match now under each profile says the same for every model it applies to.
5. After some requests, Last requests shows what InferHub said served each one, the ceiling sent and the charge it reported; Fetch the charged ask reads InferHub's usage log for the price each was actually charged at.

The kinds: pct_of_official, max_price (dollars per million tokens), cheapest_level_now and cheapest_level_min_accounts (follow the market — add a cap to be sure), with exclude_upstreams and max_usd_per_request on any of them. When nothing on the market is under your ceiling, the request ends with a short 400 that names your ceiling and the cheapest price — MCC never sends it without a ceiling and never raises yours by itself. Each InferHub model's table on the Models page also shows its offers and the route's own route note. InferHub's own budgets and combos are shown read-only; MCC does not write them. Not verified on a real account yet.

Point Claude Code here

Claude Code reads its settings file, and that file wins over exported environment variables — so export ANTHROPIC_BASE_URL=... will appear to do nothing if the file says otherwise. The fastest way to point it at this proxy is the button on this dashboard, not hand-editing JSON.

1. Open the Claude Code page from the left nav. The path field is pre-filled with ~/.claude/settings.json, and the card lists every settings file it can see on this machine — if this server runs under WSL while Claude Code runs on Windows, that includes the Windows-side file too, since those are two different files.

2. Press Configure. It writes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN into that file's env block, merging with anything else already there. The previous file is backed up next to it with a .fcc-backup suffix the first time it writes. If the file already points somewhere else, the status line shows what is there before you overwrite it; Remove deletes just those two keys. If a higher-precedence file (like an enterprise managed settings file) also sets these variables, the card warns you which one wins.

3. Restart Claude Code and run /status. It should report Anthropic base URL: http://127.0.0.1:8082. If it still shows Anthropic, the file was not picked up — check the path and that the JSON is valid.

4. Pick a model. No overrides needed to select a tier by name — but the picker below only lists the MCC catalog once model discovery is on:

mcc-claude sets the proxy variables for just the current shell session, without touching any file. Add --discover-models to also enable the picker above (an extra request to the proxy on every launch, so it is opt-in): mcc-claude --discover-models. The legacy fcc-claude alias was retired in 7.0.0.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<your token>",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8082"
  }
}

Point Claude Desktop here

The desktop app has a native gateway setting, so no file editing is required. Menu labels shift slightly between versions; this is the current route.

1. Enable developer mode: Help → Troubleshooting → Enable Developer Mode. The app restarts with a Developer menu. On older builds it is Settings → enable Developer mode.

2. Open Developer → Configure Third-Party Inference…

3. Fill in the Connection section, then Apply Changes:

Then fill in the model list with the five entries Configure writes for you. Claude Desktop accepts a model name only if it looks like a Claude model, so these are display names MCC resolves itself — mcc/best and its siblings are rejected by the app’s own filter. Tick Offer 1M-context variant and Default to 1M context on each, and never use a bare tier name such as sonnet: with discovery off the app flags it.

4. Use Test connection and Test model discovery before restarting — both call this server, so it has to be running.

5. Restart the app. With model discovery off and the five models named above, the picker is filled from your own list at launch rather than from a /v1/models call, so it cannot come up empty because a request was slow. The initial warning dialog is safe to ignore. With a gateway active the app runs local sessions only.

Point a desktop app here

Some applications MCC cannot launch. They are already running, or they are not, and the only way in is the one configuration file each reads at startup. The Desktop apps group at the bottom of the Coding agents page is one card per app, and a card writes that file for you.

Do it in four steps.

1. Read the card. Every one names the exact file it would edit, which keys MCC would own, which keys it would replace, and the base URL it would write. The badge beside the title is the app's current state: not installed, installed, not configured, configured by MCC, configured but drifted, or config file will not parse.
2. Press What will this write? It renders a real unified diff of the real document and touches no disk. Nothing has been written at this point and nothing will be until you press the other button.
3. Press Configure. Your original file is copied to a .mcc-backup beside it before the first edit, once. Every byte MCC does not own is parsed, carried through and written back unchanged — comments and key order included, which is why each app declares its own document format rather than being round-tripped through JSON.
4. Export the token if the card says to. MCC never sets an environment variable on your behalf, so a card whose app wants one prints the export and the next status poll reports whether it took.

A card that says “managed by your organisation” has no button on purpose. Some of these apps read a higher-precedence source than the file MCC writes — a Windows policy key, a macOS managed profile. Where one is present, MCC writing its file anyway would succeed, report success, and change nothing, so the card names the source and the keys it enforces instead.

Two ways to undo, and what separates them is what they refuse. Both remove the keys MCC created and both put back a value MCC replaced. Remove MCC's keys never refuses: no record, no hash check, always available, and the default. Restore the original values exactly guarantees the pre-MCC state instead — it requires the record MCC wrote at Configure time and declines when the file has been rewritten since, rather than reverting an edit you made on purpose. Before 6.56.0 the first mode deleted a replaced value and then dropped the record, so a Codex user's own default model was lost and the second mode answered “no record” afterwards. It no longer does either.

The drift badge is not an error. It means an owned key no longer holds what MCC wrote — you hand-edited the file, or the app rewrote it. Nothing is corrected behind your back. Press Configure again to take MCC's values back, or Undo to hand the file over entirely.

An app that cannot be pointed here says so, with a date. Kimi's and Qwen's desktop builds, LM Studio and Warp each carry a dated reason rather than silence, so “can I use this through MCC?” has an answer you can re-check rather than an absence you have to test yourself.

Without a browser. mcc-apps list, mcc-apps status <app>, mcc-apps configure <app> [--preview] and mcc-apps undo <app> [--restore] are the same four actions against the same routes the page uses, so a card and a command cannot disagree about what would be written. The server has to be running: resolving what to write means walking the model ladder, which only the server can do.

Point another CLI here

mcc-codex
mcc-pi
mcc-opencode
mcc-opencode2
mcc-kilo
mcc-commandcode
mcc-openclaw
mcc-hermes
mcc-kimi
mcc-qwen
mcc-crush
mcc-cline
mcc-goose
mcc-aider
mcc-droid
mcc-gemini

The Coding agents page lists every CLI this proxy can launch: whether its binary is on your PATH, every command and flag it answers to with a copy button each, the protocol it will speak, and the catalogue this proxy generates for it. A missing one is reported with that agent's own install command, and its card has an Install button (Install a coding agent). A search box at the top of that page narrows the cards as you type — by name, command or app — and sends nothing to the server.

OpenCode, OpenCode 2 and Kilo read a config file rather than command-line flags, and this proxy does not edit yours. Each of them documents a variable naming an extra config file — OPENCODE_CONFIG and KILO_CONFIG — so the launcher writes a file of its own under ~/.mcc and hands over its path. Your proxy token is not in that file either: it is written as OpenCode's own {env:...} substitution and supplied to the launched process only. Inside those CLIs the models appear under the provider mcc, as mcc/<provider>/<model>.

This server owns those files; the launcher only reads them. Every agent's document is written under ~/.mcc when this server starts and rewritten whenever the model list or any model's resolved capabilities change, so mcc-<agent> opens the file it needs and launches — no HTTP, no wait. A launcher asks this server to build a document only when the file is not there at all, and that one build gets Coding agent catalogue build budget on Limits & Resilience → Deadlines (20 s by default). Each agent's card above names its file and when it was last written. Before 6.36.1 only the launcher could create a document and its fetch was given the 1.5 s health-check budget for a route that takes 1.8–4.0 s, so the first launch failed, the file was never created, and every launch after it failed identically.

Command Code is the one exception, and it says so on its card. It reads exactly one document, ~/.commandcode/providers.json, and publishes no flag or variable naming another — so this proxy merges a single provider.mcc key into your file. Every other key is written back unchanged, your document is copied to providers.json.mcc-backup before the first edit, a refresh that resolves the same numbers writes nothing, and mcc-commandcode --disconnect takes the key back again. The token still stays off disk: Command Code refuses a literal key there and expands $MCC_COMMANDCODE_API_KEY from the launched process's environment instead.

OpenClaw is the second, and its file is the one you are most likely to have written yourself. It reads exactly one ~/.openclaw/openclaw.json — JSON5, comments and all — and publishes no extra-config lever, so this proxy merges a single models.providers.mcc block into it. The edit is made to the text, so comments, indentation and key order come back byte for byte; the document is copied to openclaw.json.mcc-backup before the first edit; a refresh that resolves the same models writes nothing and only ever touches a block that already names this server. One value outside the block is written — OpenClaw's default model, agents.defaults.model.primary — and what it held is recorded, so mcc-openclaw --disconnect puts it back. mcc-openclaw --restore does the same but refuses if the file changed since. Models carry the limits and prices the ladder actually resolved; a value nobody published is left out rather than written as a zero.

Hermes Agent's file is YAML, and its home is not your home on Windows. Nous Research's CLI reads one config.yaml in HERMES_HOME, else %LOCALAPPDATA%\hermes, else ~/.hermes, and publishes no extra-config lever — so this proxy merges a single providers.mcc block into it, as a text edit that keeps comments, quoting, indentation and every other section. The block names key_env: MCC_HERMES_API_KEY, so the proxy token never reaches the file: mcc-hermes sets that variable in the child process only. The only per-model field it writes is the context window the ladder resolved, and a model whose window nobody published gets none rather than a zero. mcc-hermes --disconnect removes the block with no record needed; mcc-hermes --restore refuses if the file moved, because Hermes re-dumps its own YAML on migration and that hash is the only honest guard.

Kimi Code reads a config file too, and takes a flag for it. It is a Python tool — uv tool install kimi-cli, not npm — and it publishes --config-file, so this proxy writes ~/.mcc/kimi-code-config.toml and passes that path. Your ~/.kimi/config.toml is never read, written or backed up, and your sessions and skills are untouched. Two things are different from the CLIs above and both are on its card: the flag replaces the config rather than overlaying it, so an mcc-kimi session takes Kimi's own defaults for theme and hooks; and Kimi's api_key accepts no environment reference of any kind, so this is the one generated file that holds the proxy token — mode 0600, under ~/.mcc, beside the .env that already holds the same value.

Qwen Code and Crush each publish a variable naming a whole config document, so neither file of yours is touched. Qwen Code reads QWEN_CODE_SYSTEM_SETTINGS_PATH and this proxy writes ~/.mcc/qwen-code-settings.json: a modelProviders.anthropic array carrying every routable model with its real context window, and an envKey naming MCC_QWEN_API_KEY rather than the token itself. The auth type comes from --auth-type anthropic on the command line, which outranks anything saved in your settings, so nothing under ~/.qwen is read for it or written to. Crush reads CRUSH_GLOBAL_CONFIG, which names a config directory, so this proxy owns ~/.mcc/crush/ and writes one crush.json into it with "api_key": "$MCC_CRUSH_API_KEY" — Crush's own documented reference form. Your ~/.config/crush is never read for a provider, written or backed up.

Both trades are on their cards. A Qwen session takes this proxy's modelProviders list as the whole list, because Qwen declares that key replace rather than merge; every other setting you have still applies. A Crush session takes Crush's own defaults for the LSP servers, MCP servers and permissions you set globally, because the variable moves the whole global layer — your project-local crush.json still applies and your sessions, logs and statistics are untouched, since the data directory is not moved. Crush is also the one catalogue where an unknown cannot be omitted: ten of its per-model fields are required, so anything the ladder did not resolve becomes Crush's own number and is listed under _mcc_defaulted and on the card.

Cline, Goose and Aider reach this proxy over POST /v1/chat/completions, which is why they could not be served before. Each takes a different lever and none of them is your own config file. Cline publishes --config, which moves its whole configuration directory, so this proxy owns ~/.mcc/cline/ and writes one providers.json into it declaring the openai-compatible provider — the one entry that takes an arbitrary base URL and makes no discovery call. -P openai-compatible is passed on every launch, because a provider block that is written but not selected leaves Cline falling back to its own hosted account. Goose is configured entirely from the environment: OPENAI_HOST plus OPENAI_BASE_PATH=v1/chat/completions compose the endpoint, GOOSE_PROVIDER and GOOSE_MODEL pick the session, and GOOSE_CONTEXT_LIMIT carries that model's real context window. Nothing is written to disk at all — Goose's only file mechanism would put this proxy's document inside Goose's own config directory, beside your settings, which is the one thing none of these launchers do. Aider reads two documents and publishes a flag for each: --model-metadata-file takes a LiteLLM model_cost map with every model's context window, output ceiling, per-token prices and vision support, and --model-settings-file takes a list saying what each model accepts — whether --reasoning-effort will be honoured, whether temperature may be sent. The proxy token is in neither: OPENAI_BASE_URL and OPENAI_API_KEY are set in the launched process only.

Droid is the odd one out, and in your favour. It was expected to need the chat-completions door too, but Factory's customModels[].provider: "anthropic" accepts an arbitrary baseUrl — so mcc-droid talks to this proxy in its own native Anthropic Messages protocol, with no translation in between. Its --settings flag is a runtime overlay merged for that process only, so this proxy owns ~/.mcc/droid-settings.json and ~/.factory is never edited. The key is written as Droid's own ${MCC_DROID_API_KEY} reference and supplied to the launched process, so it never lands on disk. No Factory account is needed for a model this proxy routes.

Cline is the second generated file that holds the proxy token literally, for a measured reason: its environment fallback for a missing apiKey does not authenticate a headless run. Like Kimi Code's, that file is mode 0600 under ~/.mcc, beside the .env that already holds the same value. Cline also carries limits for one model at a time — its schema has no per-model array — so mcc-cline -m <model> is what moves the context window and output ceiling onto the model you actually asked for.

What the picker is told. Each model in that catalogue carries its own context window, output ceiling, vision and tool support and reasoning-effort vocabulary, as this proxy's metadata ladder resolved them — not a fixed placeholder. A model with a 32k window is advertised as 32k, and a model that only supports low and high offers exactly those two rungs.

Where a CLI's own format demands a number nothing published, the proxy uses that CLI's documented default and says so — on the agent's card, in a one-line summary on the launcher's output (MCC_CATALOGUE_VERBOSE=1 for the per-model list), and in a _mcc_defaulted block inside the generated file. Kilo CLI is the exception on that last one: its config validator rejects unknown top-level keys, so its file carries no such block and its card says so.

These catalogues are pickers rather than protocol surfaces, so they list fewer entries than /v1/models deliberately: :batch refs are an asynchronous pricing tier of a model you already have and are left out, and every model appears once under its plain id. Hiding a model on the Models page removes it from every agent's catalogue too.

Cline, Crush and Goose have to be given one model up front to open a session at all. They start on the route named by MODEL, or on the first entry that is not a free tier when that route is hidden — not simply on whatever happens to be listed first.

A coding agent is not a provider. The CLIs here sit downstream of this proxy and send requests to it; the names on the Providers page are the upstream gateways it buys tokens from. Some names appear in both and mean different things.

Editor integrations work the same way — Claude Code and Codex in VS Code, or Claude Code through JetBrains ACP.

Housekeeping commands do not need the proxy. Each launcher keeps a list of subcommands and flags that reach the CLI untouched — no MCC configuration, no generated file, and no running server. mcc-kimi login, mcc-crush dirs, mcc-droid doctor and mcc-<agent> --version all answer with the proxy stopped, because logging in or printing a version has nothing to do with which provider serves a request. Anything that actually runs the agent is configured normally.

Install a coding agent

The installer installs MCC and its prerequisites, nothing else; agents are installed only by the dashboard button you press. On the Coding agents page a card whose program is not on this machine — a CLI or a desktop app — has Install, a picker when your system has more than one way, and Copy command with the vendor's own line for your own terminal. A card that is installed shows its path and version and no button: MCC never installs a second copy.

1. Press Install. The plan comes first: each file it downloads (https only, from that vendor's own hosts), each command, the permission prompt your system will show (“Windows will ask for administrator permission”), and what changes (“adds that folder to your PATH”, “adds one line to ~/.bashrc”). Nothing has run yet.
2. Press Install now. The installer's lines appear under the card; Cancel install stops the installer MCC started and its children, nothing else.
3. Read the result: Installed and verified with the version and the path, or not on PATH in this server yet — open a new terminal, or a failure panel with the exit code, the last lines, the log path, what went wrong, the command to run yourself and the vendor's page. Nothing is retried on its own.

The vendor's own installer comes first; npm only where it is the only way. Node.js and npm are installed only when an npm method needs them and they are missing: the official installer on Windows and macOS (your system asks for permission itself), fnm per user on Linux and WSL. An older Node.js is never upgraded — the card says it is too old and offers the agent's own installer. MCC never runs sudo or runas, never elevates itself, never runs a script from a string, never installs into WSL from Windows, and offers no Update or Uninstall. Kimi Code has no button until MCC has checked mcc-kimi against Moonshot's new Kimi Code; Warp, Kimi and Qwen desktop and Codex desktop are links to the vendor's page. Every run is logged under ~/.mcc/logs/agent-installs/.

Connect any OpenAI-compatible client

Anything that speaks the OpenAI API can point at this proxy without a plugin or an adapter. Give it these three, and nothing else:

Two OpenAI request shapes are served. POST /v1/chat/completions is the one almost every client sends — the OpenAI SDKs, the IDE plugins, the agent frameworks — with streaming, tool calls, images and reasoning_effort. POST /v1/responses is the newer shape Codex speaks. Both run through the same routing, fallback chain, reasoning gating and request log as /v1/messages, so a request costs and behaves the same whichever door it arrives through.

curl http://127.0.0.1:8082/v1/chat/completions \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "mcc/medium", "stream": true,
       "messages": [{"role": "user", "content": "hello"}]}'

GET /v1/models answers in the OpenAI list shape, so a client with a model dropdown fills it from this proxy. Thinking is streamed as delta.reasoning_content, which is the field the clients that display reasoning actually read. The Requests page labels each of these rows openai_chat in its Protocol row, so you can tell at a glance which door a request came through. /v1/responses answers streamed requests only. Every endpoint, its auth headers, its error shapes and one runnable example each are in the API reference of Clients on the Docs page.

Four coding agents reach this proxy through that door, and each has a launcher of its own. mcc-cline writes an openai-compatible provider into a configuration directory this proxy owns. mcc-goose sets OPENAI_HOST and OPENAI_BASE_PATH=v1/chat/completions and writes no file at all. mcc-aider sets OPENAI_BASE_URL to the /v1 form above and hands Aider two generated model documents. mcc-droid is the exception: Factory's Droid takes an arbitrary base URL on its anthropic provider, so it uses POST /v1/messages instead. See Coding agents for every command each one answers to.

n above 1 is refused with a 400 rather than served quietly as one choice. seed, logprobs and the frequency and presence penalties have no equivalent upstream and are dropped — the request still runs, and the drop is recorded in the server log rather than being silent.

Connect a Gemini client

Gemini CLI and everything built on Google’s google-genai SDKs speak one protocol and no other: they cannot be pointed at an OpenAI-shaped endpoint at any price. So this proxy serves Google’s own request shape as a third door. Give a Gemini client these three:

POST /v1beta/models/{model}:generateContent answers with one GenerateContentResponse; :streamGenerateContent answers with Google’s alt=sse stream — bare data: frames and no [DONE] sentinel, which is OpenAI’s convention and would break a Gemini client. :countTokens is served too. systemInstruction, generationConfig (including thinkingConfig and responseSchema), tools and toolConfig are all translated, and inline images and function-call round trips work. All of it runs through the same routing, fallback chain, reasoning gating and request log as /v1/messages.

curl "http://127.0.0.1:8082/v1beta/models/mcc/medium:generateContent" \
  -H "x-goog-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "hello"}]}]}'

The Requests page labels these rows gemini in their Protocol row, and their Endpoint row carries the model and the method — the path is the model on this surface, so collapsing it to a constant would hide which model a row was for.

One coding agent reaches this proxy through that door. mcc-gemini sets GOOGLE_GEMINI_BASE_URL and GEMINI_API_KEY in the launched process and hands Gemini CLI a settings document this proxy owns, through the CLI’s own GEMINI_CLI_SYSTEM_SETTINGS_PATH variable. Your ~/.gemini/settings.json is never written, and the OAuth tokens beside it are never read. See Coding agents for every command it answers to — including why a headless run needs --skip-trust.

candidateCount above 1 is refused with a 400 rather than served quietly as one candidate. safetySettings and cachedContent have no equivalent upstream and are dropped, as are Google-hosted tools such as googleSearch — the request still runs, and every drop is recorded in the server log rather than being silent. Thought parts are returned only when the request asked for them with thinkingConfig.includeThoughts.

Search the web

Claude Code's web_search is normally executed and billed by Anthropic. This proxy fulfils it locally, so no Anthropic search credits are used and it works with any model provider.

WEB_SEARCH_PROVIDER=auto needs no configuration — with no keys it falls back to the keyless ddgs metasearch, then to MCC's own DuckDuckGo hop. Add any provider key and auto prefers it. A missing key on an explicitly chosen provider fails visibly rather than degrading silently.

The ddgs provider is a metasearch. The keyless DuckDuckGo (ddgs) provider is the ddgs package: with its Backend engine empty, one search asks several engines and merges their results, so DuckDuckGo itself may not be asked; set DDGS_BACKEND=duckduckgo to ask it alone. Bing, Google and Yandex are switched off inside the version MCC ships, so choosing one of them runs auto. Its safe search (DDGS_SAFESEARCH: on, moderate or off) applies only on the engines that read it — DuckDuckGo's own engine ignores it — and a strict saved from older docs is read as on.

The keyless DuckDuckGo hop. The last hop of auto submits DuckDuckGo's html search form first, and asks its lite page only when that page has no result and no bot check; it returns each result with its snippet, skipping ads; DDGS_REGION and DDGS_TIMELIMIT reach it as the page's region and time fields when set. When DuckDuckGo answers with its bot check, the search says so as a rate limit instead of reporting no results, and a search chain moves on to its next entry. To space its requests, set WEBSEARCH_LEGACY_MIN_INTERVAL_SECONDS on this page (0, the default, sends them back to back; the html and lite requests of one search count as two).

The setting most worth changing. By default most providers return a one or two sentence snippet. Several can return the extracted text of the page — the difference between the model guessing from a summary and actually reading the source.

EXA_CONTENTS=text
TAVILY_INCLUDE_RAW_CONTENT=markdown
FIRECRAWL_SCRAPE_FORMAT=markdown

WEBSEARCH_DIGEST_CONTENT_CHARS=4000

Jina, Parallel and Linkup return extracted text by default. It has its own cap, separate from the snippet cap, so opting in is not trimmed back to snippet length — set it to 0 for snippets only. It costs more on most providers and adds input tokens to every search; each option's drawer states its cost.

Domain filters from the client are forwarded and applied server-side on Exa, Tavily, Firecrawl, Linkup, Perplexity and Parallel, so you pay for relevant results instead of filtering afterwards. Providers without native support search normally; each recorded attempt shows supports_domain_filters so you can tell which happened.

Two options that matter for coding work:

FIRECRAWL_CATEGORIES=github,research
TAVILY_CHUNKS_PER_SOURCE=3

Locale is worth setting if you are not in the US — Firecrawl returns US results unless told otherwise (FIRECRAWL_COUNTRY=DE). Safe search is available on Brave, SearXNG, SerpAPI, SearchAPI and DDGS (on the engines that read it, not DuckDuckGo's own). All 66 advanced options live in the Advanced options drawers, which are open when the page loads, and each states what leaving it blank does.

Set a search chain

On Web Search, the Search chain card lists the search services a web search tries, top first. Press Add search service and pick one per row — for example Exa, then Context7, then Tavily — reorder with the arrows or the grip, and press Apply. A service may be listed twice (it is tried again at its place); Pause skips a service everywhere it is listed without removing it; a row whose service has no key says so and is skipped.

While a chain is set, the route summary shows it and says that Web Search Provider and Fallback Policy are not used; Disabled still disables search. Each service's keys follow your model providers' rules: a key is benched only for a rejected key, a 429 or an out-of-credits message, and Manage keys on its card shows why (benched 60 s: rate limited, locked out, tier 1 of 3) with a Reset button. In Analytics, the Key tries column expands to every try on every key. Empty the card and Apply to go back to the provider route above.

Context7 answers with library documentation rather than web pages, so Auto never picks it: add CONTEXT7_API_KEY and put it in the chain where a documentation answer helps (for example first, ahead of a web search service). It has not been verified on a real key.

Use a VPN, WARP or Tor

For a provider that counts a free allowance per address (OpenCode Zen's free models), refuses your country, or should not see your home address. MCC never installs, starts or signs in to a VPN app, WARP or tor: it uses what you run — except row 7, where MCC runs the pinned wireproxy with a WireGuard file you exported, only after you press its buttons — and TLS stays strict, so no proxy or VPN can read your keys, prompts or replies. Find your row, then follow its steps.

1. Proton VPN Free: turn the app on

1. Connect the Proton VPN app. Nothing is set in MCC: everything MCC sends from this computer's own address — a provider with no chain, a chain's Direct entry, Direct fallback — now leaves through Proton.
2. On the Proxying page press Where does Direct come out? on a provider's card: it shows the address and country the provider's own host saw. It sends only where that provider's traffic may leave from this computer right now; anywhere else nothing is sent and the card says why.

Proton VPN Free (Proton's own pages, read 2026-10-06): no proxy, no split tunnelling, one device, a server picked at random from about ten countries, and Change server waits 45 seconds, then ten minutes. So it is one exit for the whole computer, and MCC cannot choose its country or press Change server. Gotchas: a chain with Direct fallback off never uses this computer's address, so the app changes nothing for it; a VPN or tool that sets the Windows or macOS proxy setting carries every Direct dial, and the log names it direct via system proxy host:port.

2. Split tunnelling: only MCC through the VPN

Proton VPN Plus and ExpressVPN can send only the programs you list through the VPN (Proton calls it include mode). List the program that opens MCC's connections: the Python interpreter running the server — not the mcc-server command, which only starts it, and not the desktop window. The server names its own process in the x-mcc-pid header of /health; in PowerShell:

$p = [int]((Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8082/health).Headers['x-mcc-pid'] | Select-Object -First 1)
(Get-Process -Id $p).Path

On an installer-made Windows install that prints uv's own Python, for example C:\Users\<you>\AppData\Roaming\uv\python\cpython-3.14.0-windows-x86_64-none\python.exe. Add that file to the VPN app's list. Gotchas: every other program running on that same python.exe goes through the VPN too; an update that moves MCC to another Python changes the path, so run the two lines again after updating; your coding agents reach MCC on 127.0.0.1 and need no VPN; a WSL install was not tested.

3. A VPN account, a gateway or a proxy list

Under Proxies on this computer press Add a VPN account, Add a gateway or Add a proxy list, pick the preset, fill in your login, press Save and offer (it contacts nothing), then Add all to chain — each address is tested against that provider's own host first. Mullvad and IVPN take no login and answer only while their app's tunnel is connected; NordVPN wants its service credentials, not your login. Every vendor's facts are in VPN accounts, commercial gateways and proxy lists.

4. Cloudflare WARP

Turn on the WARP desktop app's proxy mode (Cloudflare documents it under Preferences → Advanced → Configure Proxy, on a port you choose), then press Scan this computer, or type socks5h://127.0.0.1:<your port> into a chain card and press Add proxy. Gotchas: WARP is one exit, shared with other WARP users nearby, so two WARP entries are not two addresses; Cloudflare documents a 10-second limit per request for its Zero Trust client's proxy mode, so a long streamed answer may be cut.

6. gluetun: any VPN's OpenVPN or WireGuard file

gluetun is a VPN client in a Docker container with an optional HTTP proxy. You run it; MCC does not install or start Docker or gluetun. A Proton VPN WireGuard example, its proxy published on this computer only:

docker run -d --name gluetun-nl --cap-add=NET_ADMIN --device /dev/net/tun \
  -p 127.0.0.1:8888:8888/tcp \
  -e VPN_SERVICE_PROVIDER=protonvpn -e VPN_TYPE=wireguard \
  -e WIREGUARD_PRIVATE_KEY=<the PrivateKey of your Proton WireGuard file> \
  -e SERVER_COUNTRIES=Netherlands \
  -e HTTPPROXY=on \
  qmcgaw/gluetun

Then press Scan this computer (8888 is one of the ports it asks) or add http://127.0.0.1:8888 with Add proxy. A second container on another host port and country is a second exit. Gotchas: publish on 127.0.0.1, or anything on your network can use the proxy; Proton VPN Free allows one device, so gluetun with a Free key while the app is connected may be refused (not tested).

Check that it worked

A chain card (from a test install whose proxies are not running, so every entry reads unhealthy): its entries, What <provider> can see, Direct fallback and Keep trying exits until one answers, which is on for every chain. The Analytics Exit column shows the exit that answered (+N when more were tried), and a request's View lists every exit it dialled and what each one answered:

Worth knowing: a chain with one entry never switches and never falls back to Direct; Direct fallback, on for a new chain, sends from this computer only once every proxy in the chain is unhealthy; a refused exit is remembered until Forget exit memory or a restart; the OpenCode session id is the same on every exit. No VPN vendor found allows automated API traffic in its terms, and commercial proxies bind you to the use you declared to them: using them for a coding assistant is your call.

What a proxy chain hides

A chain on the Proxying page sends a provider's traffic out through other addresses, so the provider does not see this computer's own. Each card has a box, What <provider> can see, that says exactly which traffic that covers, worked out from the card as you edit it.

• Through the chain: model requests on every surface, with their retries and fallbacks to the provider's other models; the model listing (hourly and Test); Probe capabilities; health probes; renewing a sign-in's token (by the request that needed it, and the card's Refresh button); media requests.
• Never through the chain: signing in (from this computer, once). Web search, web fetch, models.dev, price lists and update checks are not sent to the provider at all; web search and fetch have proxy settings of their own.
• Direct fallback (Fall back to this machine's own address): on, the provider sees this computer's address only once every proxy in the chain is unhealthy — unreachable, refused for intercepting TLS, or cooling down after a refusal. A request that ends with a healthy proxy still untried moves on to its next model instead. Off, the provider never sees this computer's address.
• A chain whose entries are all paused or removed, or whose file cannot be read, is refused whatever Direct fallback says. Switch the chain off to send that provider's requests from this computer on purpose.
• The request log names the address that carried each try: a chain's entry, a one-entry chain's entry, a provider's own static proxy, direct, or direct via system proxy host:port when the operating system's proxy (a VPN app, a corporate proxy) carried a Direct dial.
• The Analytics Exit column (where Folder was until 7.88.0) shows that name for the attempt that answered, with +N when the request went out through more exits and every one of them, in order, in its tooltip. A dash means no chain and no proxy. The Exit box in the toolbar finds requests by any part of an exit's name; the export's Exit field adds both to a download.

Keep trying exits until one answers

Some providers count their free allowance per address: OpenCode Zen's free models answer a spent address with a 429 FreeUsageLimitError while another address still gets answers. Keep trying exits until one answers is on for every proxy chain — new ones and, since 7.81.1, the ones saved before 7.81.0 too. Untick it on a chain's card to give that chain back the rotation of earlier releases. While it is on:

• A request that an exit refuses because of the exit goes to another exit of the chain, on the same model: a free-usage or rate limit (with the rate_limit chip ticked), a refusal for the exit's country (the host's own words, such as RegionError), a proxy that cannot be reached, or one that drops the connection before the first byte. It is not retried on the same exit.
• Your existing limits still apply: it moves on at most Switches per request times for refusals (and PROXY_MAX_LIVE_FAILURES failed exits in all). After that the request moves to the next model of your fallback chain, and the model is not paused for the exits that refused — the key is not charged either.
• MCC remembers each refused exit for that provider: spent until the wait the provider stated (or your PROXY_COOLDOWN_SECONDS when it stated none), blocked for its country for PROXY_COOLDOWN_SECONDS. Later requests skip those exits without dialling them, a chain save or a speed re-sort does not forget them, and the model is only skipped while no exit of the chain can serve. Each entry shows what is remembered; Forget exit memory on the card clears it (and lets unreachable exits be tried again). A restart forgets it too.
• Direct fallback keeps its rule: this computer's address only once every proxy is unhealthy, and a remembered exit counts as unhealthy. Reaching the switch limit never ends in Direct.
• The request detail shows each exit dialled, what it answered and what MCC now remembers about it, how many exits were skipped from memory, and — when every usable exit refused — one sentence saying so.
• Since 7.96.0, on every chain (ticked or not) and without one, an attempt whose tries met a country refusal or a bot-challenge page carries a country refused ×n / challenged ×n chip in the request detail, and the Exit cell's tooltip counts them. They are read from the stored tries, so older requests show them too. A country refusal never locks the key out any more; an unticked chain still does not move to another exit on one.

Time: each bad exit costs what it costs today (a refused connect up to PROXY_CONNECT_TIMEOUT_SECONDS, a 429 a second or two, a silent exit up to HTTP_READ_TIMEOUT), but only once per memory window instead of once per request. Output is never moved: once the first byte has reached your client the request stays on its exit. A drop while a model is still thinking (before any answer text) counts as after the first byte.

Faster proxy exits: keep-alive and recency

Two settings on Limits & Resilience → Credential health, both 0 (off) until you set them. With both at 0 everything is built exactly as before.

• PROXY_KEEPALIVE_SECONDS — how long a connection through a proxy exit stays open while idle. The HTTP library closes an idle connection after 5 seconds, so nearly every request through a proxy dialled it again and ran the proxy's tunnel handshake and the TLS handshake before the first byte; through a free proxy that alone can take tens of seconds. Set 60: requests up to a minute apart through the same exit then reuse its connection — Chat Completions, Responses and Messages streams and requests that are not streamed (a Chat Completions stream closed its connection at its end, and so gained nothing, until 7.111.1). It reaches only the proxy entries of a chain with two or more entries — no chain, a single fixed proxy, Direct entries and the Direct fallback are untouched. A proxy that silently drops an idle connection can make the first request after a pause fail on that exit; the chain then moves on, as for any dropped connection.
• PROXY_ORDER_RECENCY_HALF_LIFE_MINUTES — makes Keep the fastest healthy proxy first and Sort by speed now prefer exits a real request succeeded through lately (the provider answered, or a first token arrived — a health check alone never counts). An exit one half-life staler than the chain's most recently proven one ranks as if it were twice as slow. 10 is a good start; 0 orders by speed only. It changes only which entry is first in the saved order: which exits are healthy, benched or skipped, and how a request moves between them, are untouched.

Both apply on Save. The reference is docs/ROUTING-REFERENCE.md, Keep-alive and recency.

Proxies on this computer, and where each exit comes out

Proxies on this computer. If you already run a proxy here — Cloudflare WARP in proxy mode, ssh -D to a server of yours, Tor, gluetun (a VPN in Docker), wireproxy — press Scan this computer on the Proxying page. MCC asks 127.0.0.1 only, on ports 1080, 8888, 9050, 9052, 9150, 25344 and 40000, whether a SOCKS5 or an HTTP proxy answers, and offers each one that does. It sends the SOCKS5 greeting and, if that is not what the port speaks, an HTTP CONNECT to this computer's own port 9 — nothing leaves the machine, and nothing is scanned until you press the button. Choose a chain and press Add to chain: the address is tested against that provider's own host first, as any address is. A listener that asks for a login gets a username and password box; the login is kept in proxy_sources.json and in that address's URL in proxy_chains.json, both readable by you only, and is never shown again. A port that stops answering is withdrawn on the next scan; a chain that took it keeps it.

Where each exit comes out. Set PROXY_CHECK_EXIT_IP_URL=provider (the Proxying page's Use each provider's own trace) and every Test also asks the provider's own host — its /cdn-cgi/trace, through the tunnel — which address it saw. Providers behind Cloudflare answer with the address, its country and whether it is WARP; others publish no trace and the row says so. It contacts nobody new, and a fetch's sweep (which sends the provider nothing) does not ask. Entries that come out of one address are grouped on their card; Keep one per exit pauses all but the first, removing nothing. Where does Direct come out? asks the same question with no proxy — so you can see a VPN app is on — but only where the chain itself would use this computer's address (no chain, a Direct entry, or every proxy unhealthy with Direct fallback on); anywhere else nothing is sent and the card says why.

Two addresses on one host:port. Sessions of one gateway, or one proxy host used with two logins, used to share one health record, cooldown and history. Since 7.89.0 they are told apart as host:port#1a2b — a short digest of each login, never the login — and a chain that would hold the same address twice is refused with a sentence naming both entries.

Bring your own Tor

MCC can send a provider's requests through a tor you run. It never downloads, installs or starts tor: you run it with a few lines MCC shows you, and MCC uses its SOCKS ports as chain entries and its control port for one button.

1. Choose ports. One SOCKS port per identity — two or more — and one control port. Any free ports will do. On some Windows computers 9050, 9052 and 9150 sit inside a range Windows reserves (netsh int ipv4 show excludedportrange protocol=tcp lists it), and nothing, tor included, can listen there. Type them on the Proxying page under Proxies on this computer → Tor you run yourself and press Save Tor ports. Saving contacts nothing.
2. Paste the torrc lines. The card shows one SocksPort 127.0.0.1:<port> line per port, ControlPort 127.0.0.1:<port> and CookieAuthentication 1, with the ports you typed. Copy torrc lines, paste them into the torrc your tor reads, and restart tor. Tor keeps streams from separate SocksPort lines on separate circuits, so each port is its own identity.
3. Check Tor. MCC logs in to the control port and shows tor's version, whether it has a circuit (or how far it has bootstrapped), and which of your ports tor really listens on.
4. Add the ports to a chain — one at a time, or Add all to chain. Each is tested against that provider's own host first, like any address. Each port goes by its own name, Tor · 127.0.0.1:<port>, on the card, in the Analytics Exit column and in what MCC remembers about exits.
5. Tick Keep trying exits until one answers on that chain: a 429 or a country refusal from one Tor exit then moves the same request to the next Tor port at once, and MCC remembers the exit that refused (see Keep trying exits until one answers).

One Tor port does not rotate. A chain with only one proxy in it never switches and never falls back to this machine's own address: that one address carries everything, refused or not. Put two or more Tor ports in the chain for a refusal to move on.

New Tor identity. The button sends tor SIGNAL NEWNYM: new requests on every one of its ports get new circuits, so new exits. A connection that is already open keeps its exit until it closes (MCC lets an idle connection go after five seconds). Tor allows one new identity per 10 seconds, so MCC refuses a second press inside that window, sends nothing, and says how many seconds are left. MCC never asks for a new identity by itself — not after a refusal, not on a timer: moving a refused request to another port is the chain's job.

How MCC logs in. By default, with tor's cookie: MCC asks tor where its cookie file is and reads it at the moment you press a button. It prefers SAFECOOKIE, where tor first proves it knows the cookie and the cookie itself never crosses the connection. The cookie is never copied into MCC's files, its logs or this page. If tor runs as another user or inside WSL, MCC may not be able to read that file: give tor a control password instead (HashedControlPassword followed by what tor --hash-password prints for it), choose Log in with a control password and type it. It is kept in proxy_sources.json, readable by you only, and never shown again. Both buttons talk to 127.0.0.1 on the control port and nowhere else: never through a chain, never to a provider.

Tor is slow to connect. A fresh circuit can take longer than the 10-second default of PROXY_CONNECT_TIMEOUT_SECONDS (Limits & Resilience → Credential health). Raise it — to 30, say — when your chains use Tor.

What Tor sees, and what it asks. Tor's first relay sees your address and its exit sees the destination's name; no single relay sees both, and TLS keeps your keys, prompts and replies from every one of them. Tor exits are shared with strangers and many providers sit behind Cloudflare, which can challenge or refuse them. The Tor Project asks people not to push heavy or automated traffic through its volunteer exits.

VPN accounts, commercial gateways and proxy lists

Since 7.91.0 the Proxying page's Proxies on this computer section has three more kinds of source. Each one turns what you give it into ordinary chain addresses, offered on its card: Add to chain (or Add all to chain) tests each against that provider's own host first, like any address. A preset fills the form from the vendor's own documentation — its host, port, session syntax, a link to the page and the day MCC read it — and you keep, change or replace every field. Nothing is stored or contacted until you press Save. A vendor's list is fetched only when you press Fetch now or switch on that source's own schedule (every 6 hours, 24 hours or 7 days; off until you choose), from the URL you confirmed, and — if you choose a provider's chain for it — through that chain's exit, never from this computer where that chain says no. Passwords, service logins and download links are kept in proxy_sources.json and in each address's URL in proxy_chains.json, both readable by you only, and are never shown again; a download link is shown by its host alone.

VPN accounts with a proxy. NordVPN: SOCKS5 on port 1080 with your service credentials (Nord Account → Set up NordVPN manually), not your login. Its SOCKS5 servers are in the Netherlands, Sweden and the United States only; the preset fills nl, se and us.socks.nordhold.net and, optionally, Nord's server list URL — press Fetch now and its SOCKS5 servers in the countries you keep become addresses. Nord allows 10 connections at once per account. Nord also documents an HTTPS proxy on port 89; it is untested with MCC (an httpx user reported a TLS error through it), so it is not offered. Private Internet Access: proxy-nl.privateinternetaccess.com:1080 with the SOCKS credentials you generate in its Client Control Panel (one exit, in the Netherlands). IPVanish and TorGuard: their SOCKS5 hosts with their proxy credentials (TorGuard also answers on 1085 and 1090 — type host:port for each). One host is one address; a SOCKS5 login crosses the network unencrypted, which exposes a proxy-only login, never your API key.

VPNs whose proxy is inside their tunnel. Mullvad: while the Mullvad app is connected, 10.64.0.1:1080 is the server you are on, and every other server's proxy (nl-ams-wg-socks5-001.relays.mullvad.net and so on) is reachable through the same tunnel — add the ones you want, one per line. No login. These addresses answer only while the app's tunnel is up, and the card says so. IVPN works the same way with 10.1.0.1 and socks5.<server>.gw.ivpn.net.

VPNs with no proxy at all: Proton VPN, Surfshark, ExpressVPN, Windscribe. They give a whole-computer tunnel and nothing a chain could choose per request. Proton VPN Free has no proxy, no split tunnelling, one device and a randomly chosen free server: turn the Proton app on and MCC's Direct goes out through Proton for the whole computer — nothing to set in MCC. Press Where does Direct come out? on a card to see which country Direct now exits from. On Proton VPN Plus and ExpressVPN, split tunnelling in include mode can send only MCC's program through the VPN. Surfshark and Windscribe: the same, Direct through the app. Cloudflare WARP in proxy mode is a proxy on this computer: Scan this computer finds it on 40000, or type socks5h://127.0.0.1:<your port> as an address; Cloudflare documents a 10-second limit per request for that mode in its Zero Trust client.

Commercial gateways. One gateway host gives a new address per session, so MCC spells N sessions in the vendor's own syntax — each its own address with its own name (Oxylabs · session 3f9a0c1e0001) and its own health, cooldown and history. New sessions mints fresh session ids (never one used before) for fresh addresses. Bright Data: brd.superproxy.io, SOCKS5 on 22228 (or HTTP on 44445), datacenter and ISP zones only — residential and mobile zones need Bright Data's own certificate installed so it can decrypt your traffic, and MCC refuses them. Oxylabs: pr.oxylabs.io:7777; a session keeps its address for its session time or until it is idle 60 seconds, so 30 minutes or more keeps a quiet thinking pause from changing it mid-answer. IPRoyal: geo.iproyal.com:12321; the session goes in the password, and without one IPRoyal changes address on every request. Decodo: gate.decodo.com:7000.

Proxy lists. A list of ip:port:username:password rows your provider gave you — Webshare's free plan (10 datacenter proxies, 1 GB a month, shared with other users, and some sites block them) first. Paste it, or give the list's download link from your Webshare dashboard: the link carries your token, so MCC keeps it like a password and fetches it only on Fetch now or your schedule. Each row is one address; its login lives only in that address's URL.

Terms. No VPN vendor found allows automated API traffic in its terms, and commercial proxies bind you to the use you declared to them: using them for a coding assistant is your call.

WireGuard files MCC runs (wireproxy)

Since 7.108.0 a WireGuard file your VPN account exports becomes a chain address: MCC runs wireproxy with it, a WireGuard client that lives entirely inside one program — no network adapter, no route change, no service, no administrator — and offers its SOCKS5 port on 127.0.0.1. Only the chains you add it to go through the tunnel; everything else on this computer is untouched.

1. Export a WireGuard file from your account: Proton VPN (account.protonvpn.com → Downloads → WireGuard configuration; the Free plan included), Mullvad's or IVPN's generator, Surfshark, Windscribe (Pro), AirVPN, PIA's manual-connections script, or wgcf generate's wgcf-profile.conf for Cloudflare WARP.
2. On the Proxying page press Import a WireGuard file, upload or paste it and press Import. That contacts nothing and starts nothing. The private key is kept in proxy_sources.json and in the config MCC writes for wireproxy, both readable by you only, and is never shown again. Commands a file names (PostUp and the like) are dropped.
3. Press Download wireproxy once. MCC fetches the pinned release (wireproxy 1.1.3) from GitHub: the release's checksums.txt first, which must agree with the sha256 this MCC pins, then the archive, which must match both; one executable is installed under your MCC folder with a receipt, and both are checked again at every start. Or give the path of a wireproxy of your own (Use my own binary). There is no Windows arm64 build of wireproxy, and MCC does not fall back to the 32-bit one.
4. Press Start. The card says Starting, then Ready once the SOCKS5 port answers and wireproxy's own check hears the tunnel — which proves the tunnel is up, not that a provider is reachable through it.
5. Choose a chain and press Add to chain: the address is tested against that provider's own host first, like any other.

The SOCKS5 port asks for a random username and password only MCC holds, so no other program on this computer can borrow the tunnel. Its port is chosen once from PROXY_RUNNER_PORTS (Limits & Resilience → Credential health; 41000–41999 by default) and kept, so the address keeps its name; Pick new ports chooses again if another program took one. A started runner starts again with the server; Stop keeps it stopped. If wireproxy exits on its own the card says so with its exit code and a Restart button; tick Restart automatically after a crash (off by default) and MCC restarts it after 1 s, 5 s, 30 s and 5 minutes, then leaves it stopped. The server's own shutdown stops every runner, and on Windows a server that is killed takes its runners with it.

Proton VPN Free allows one device: disconnect the Proton app before you start a Proton runner, or one of the two may be refused or disconnected. Mullvad and IVPN run a SOCKS5 proxy on each server that only their tunnel reaches: on the card's form, type the servers you want, one per line, in the vendor's documented shape (<country>-<city>-wg-socks5-<NNN>.relays.mullvad.net), and each becomes its own address through the one tunnel — one key, many exits. Those forwarded ports take no login, because the vendor's proxy takes none. WARP: import a wgcf-profile.conf you made yourself; MCC never registers a WARP device. Cloudflare's own trace shows warp=on once the address is tested with exit identity on. Every vendor here — Proton VPN included — has so far been tested only with files of its shape against stand-in servers, never against the real service; the card says so.

gluetun, for a VPN that gives only OpenVPN files: the Proxying page's gluetun card has a two-container docker-compose.yml; MCC never runs Docker for you. See step 6.

Where the advanced settings went

Nowhere — they are all on the page. Since 7.29.1 nothing on this dashboard is hidden behind a toggle. A setting marked advanced simply sorts after the common ones in its card and carries that tag; every one of them renders the moment the page loads. Before 7.29.1 the mark meant the field was not drawn at all until you found a Show advanced button, and on the Providers page that button was never added, so a provider's proxy and base-URL overrides could not be reached from the dashboard at all. If you would rather see the short form, each card has a Collapse advanced control; it starts expanded and remembers your choice in this browser.

Generate images through the proxy

Any client that speaks the OpenAI images API can point its base URL at this proxy: POST /v1/images/generations and /v1/images/edits are routed over the Image rail on Model Config (and /v1/audio/speech over the Speech rail, /v1/audio/transcriptions and /v1/audio/translations over the Transcription rail, /v1/videos over the Video rail), primary first, then its fallbacks, with the same retry, key-rotation, 429, pause and proxy rules as a chat chain. A provider/model in the request pins that model when it is on the rail (since 7.95.0 one that is not is refused with 400 naming the rail's models, and nothing is sent); any other name uses the rail. Only providers that declare an image endpoint can serve it (Gemini, xAI, Together, DeepInfra, Agnes, SiliconFlow, ZenMux); any other model on the rail is skipped without being charged.

A video is a job: the Video rail is walked only until a provider accepts it, and from then on every status check and the download go to that provider with the same key; a job that later fails is never resubmitted elsewhere. Video is served by Gemini, OpenRouter and DeepInfra. Clients that speak Google's Gemini API reach the same rails: a generateContent asking for image or audio output, and :predictLongRunning for video. Gemini models can also serve the Speech and Transcription rails. The Models page lists every media-rail model and what its provider declares; Analytics has a separate Media card; a custom provider declares media endpoints with the Media endpoints checkboxes. A request's detail shows its media, with a preview for stored files; MEDIA_STORE_MAX_MB caps what is kept. Media requests are priced from the provider's figure, models.dev or LiteLLM; anything else stays unpriced.

The rail keeps health records of its own, so a model or key that fails at images is not benched for chat. Every request is logged with how many images came back and their size; turn on Store generated media on Analytics to keep the files too.

Try it. Put a model on the Image rail on Model Config, send one request, then look at the Media card near the bottom of Analytics:

curl http://127.0.0.1:8082/v1/images/generations \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt": "a red cube on a white table", "response_format": "b64_json"}'

An empty rail answers 404 — No model is configured for the Image rail — on purpose: the OpenAI SDKs would retry a 503 for nothing. Since 7.95.0 a media row's Turn cell in the requests table says what it did (1 image generated, speech · 4.2s, transcribed · 31s, video job, or image request for one that produced nothing); each row is labelled by its own API (openai_speech, openai_videos, …; older rows keep openai_images); a client that hung up before a whole answer was ready is logged cancelled and still priced, because the provider billed it; a wrong proxy token answers in OpenAI's error shape; image stream: true and speech stream_format: sse are answered as one final event when no provider on the rail streams; a custom provider's video with no download link is fetched from videos/{id}/content; and MEDIA_UPLOAD_MAX_MB (the Media uploads card under the rails, 0 = no limit) refuses a larger upload with 413 before anything is spent. A curl for every rail and the full list are on the Docs page under Media routing (docs/MEDIA.md); every endpoint, with one runnable example each, is in the API reference of Clients (docs/CLIENTS.md).

Request fields per model (since 7.98.0). A media model's host can refuse a request for a field no catalogue mentions — Agnes answers a video without mode with mode is required, and an image carrying image_config with not supported. Each media model now publishes the fields its request takes, as a JSON Schema per operation: open Request fields under its row on the Models page. Each field says who said so — your own statement (type it in the small editor there), a refusal this host gave (with Forget), the provider's declared endpoint, MCC's own adapter, or the provider's model list — and a field nobody spoke about is forwarded, not known, never "unsupported". A refusal is written down the moment it happens and changes nothing a request sends: MCC does not skip a model or drop a field because of it. A client or an agent reads the same list, with which models on each rail accept, need or refuse every field:

curl http://127.0.0.1:8082/v1/media/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

Each picker offers only its own kind of model: a chat route chat models, the Image rail image models, and so on. The kind comes from the provider's own model list first, then what models.dev says a model accepts and produces — with OpenRouter's own live list ahead of models.dev for a provider models.dev does not describe, and only where models.dev is silent for one it does — then the provider's model type or endpoint names, then the media rail you saved it on; never from its name. With Use LiteLLM's price map too on (Cost estimation), LiteLLM's map answers too: what it says a model accepts and produces, where nothing above the cross-provider vote did, and its mode and endpoint names after the provider's own — so turning LiteLLM on can state the kind of a model nobody had described. The kind row in a model's panel on the Models page names the one that decided it. A model whose kind is not chat is left out of /v1/models and every coding agent's catalogue. A model nobody has described stays listed for chat and appears on a media rail under Kind not known, and a value you already saved is never dropped -- it is marked. The Models page has a filter chip per kind.

Let a coding agent make media itself (MCP)

Since 7.99.0. An agent does not know MCC serves pictures, speech, transcripts and video unless something tells it. MCC's media server, mcc-mcp, is that something: a small program installed with MCC that an agent starts over MCP and that offers one tool per media rail you filled in on Model Config — generate_image, edit_image, speak, transcribe, translate_audio, create_video with get_video — plus media_status, which is free and says what is configured. Every field a tool takes comes from the rail's own models (the same lists as /v1/media/models), labelled with which models take, need or refuse it.

Add it per agent. Open Coding agents and press Add MCP server on the agent's card; Remove MCP server takes it out and puts back exactly what was there. MCC writes it only where it already writes: the launch line of mcc-claude (its own --mcp-config= file) and mcc-codex (-c settings for that launch), the config layers it owns for OpenCode, OpenCode 2, Kilo, Crush, Qwen Code and Gemini CLI, and its own Claude Desktop document — never your own ~/.claude.json, config.toml or opencode.json. The agent's next session lists the tools. Claude Desktop needs its card under Desktop apps configured, and one relaunch. Gemini CLI starts MCP servers only in a folder you trusted.

What it costs, and who asks. Each agent that has the server sends its tool list with every request — a few KB, shown on the MCC media server card — built once per session, so it stays byte for byte the same from turn to turn and the prompt cache keeps its prefix. The tools that spend money are never marked read-only, so an agent that asks before a tool asks before these; for OpenCode and Kilo, which do not ask by default, MCC's own config layer turns their ask on for those tools. MCC adds no limit of its own.

Where results go. Files are saved in the folder the agent is working in (Claude Desktop, which has none: the mcp-media folder of MCC's configuration folder), never over an existing file; the agent can name another folder. Pictures are also shown to the model; speech and video are given as paths. A video tool returns a job id at once, and get_video saves it when it is done. A call the agent stops waiting for still finishes and is listed by media_status — the provider bills it either way. The server reads MCC's address and token from MCC's own settings, so no app file carries the token, and it talks only to MCC: a picture a provider answers with a link is downloaded by MCC through that provider's proxy. For an app MCC does not launch, the card has a line to copy.

In your own app files (7.100.0). An app you start from its own icon reads its MCP servers from your file, which the buttons above never touch. The cards under Desktop apps have the same Add MCP server / Remove MCP server button for that file: Codex desktop (and plain codex) in ~/.codex/config.toml as [mcp_servers.mcc_media], OpenCode desktop (and plain opencode) in opencode.json as mcp.mcc_media plus OpenCode's own ask for the tools that spend money, Command Code in ~/.commandcode/mcp.json. The first press shows the change and a Write it button — nothing is written before you press it — the first write takes a one-time backup beside the file, and Remove MCP server or the card's Undo gives the file back byte for byte. An mcc_media entry MCC did not add is left alone and the card says so. Claude Desktop's card has it as a fallback for claude_desktop_config.json, where the app gives a tool 60 seconds: press it only if a relaunch did not bring the tools from MCC's own document. VS Code and Roo Code: not measured yet. Restart the app after a change.

Images, and what they cost

A screenshot is the most expensive thing an agent routinely sends, and three separate mechanisms decide what actually leaves this machine. They are all on Model Config.

Codex too, since 7.95.0. An image attached to a Codex turn (codex -i shot.png, or a paste) reaches MCC's Responses door as an input_image and becomes the same image a Chat Completions client sends, so everything below applies to it. Before, it was refused with 400. Images a Codex tool returns (view_image) still reach the model as text, and Codex's own image-generation tool never calls MCC.

1. An image a tool returned arrives as an image

A browser screenshot, or a Read of a PNG, comes back nested inside a tool result — and no OpenAI-format chat message can carry a picture there. Before 6.49.0 that picture was sent as base64 text, which every OpenAI-dialect provider tokenised at roughly a token per byte: one 213 KB screenshot measured 324,000 prompt tokens, and the model never saw a picture at any price. Now it is hoisted into a short user message straight after the tool output, marked as tool output rather than as something you typed, with a one-line note left behind pointing at it.

TOOL_RESULT_IMAGE_DELIVERY chooses the rule. auto (the default) attaches the picture unless the model that answers is published as unable to read one, in which case a plain sentence naming the tool takes its place; attach always sends it; strip never does. There is deliberately no option to go back to base64 text. The request detail marks what happened with an image_delivery line, so a request that lost a picture says so.

2. Oversized pictures are shrunk before they are sent

IMAGE_MAX_LONG_EDGE ships at 1568 — Anthropic's own resize budget — and applies to the deep copy the router already takes, so your client's request is never mutated and every dialect converter is handed pre-shrunk data. On three of the four billing families this is token-neutral because they resize server-side anyway; on the fourth, OpenAI's patch-billed models, it is a real 41% saving and the one case where the model genuinely sees less. 0 sends exactly what the client sent.

Two knobs beside it, both opt-in. IMAGE_JPEG_QUALITY re-encodes a resized image as JPEG; 0 — the default — never changes the format, because these are screenshots of text and code and that is the worst case there is for JPEG ringing. An image with an alpha channel is skipped whatever it says. IMAGE_DETAIL is OpenAI's per-image fidelity field; auto emits nothing at all, and it is meaningless outside the OpenAI dialects.

Was the estimate right? A provider row on the Models page carries a billed/est chip once there is enough traffic to compare: the input tokens that host actually billed against what MCC's per-family estimator predicted. A ratio near 1.0× means the estimator has this family right; a large one means it does not, and the number is the only thing that can audit that.

3. A blind model can be given the words instead

Plenty of fast, cheap models cannot read a screenshot. Set a Vision adapter and MCC diverts — but only when the tier's own model is known not to accept images. A model whose provider publishes nothing is left alone, because rerouting on silence moves traffic away from models that handle images perfectly well.

Vision Adapter Mode — VISION_ADAPTER_MODE in the env file — picks what “divert” means, and the default is unchanged from every release before 6.51.0:

What describe mode actually costs. One extra sub-request per image, not per request — and descriptions are cached on the image itself, so a screenshot Claude Code re-sends every turn is described once. Each describe call is an ordinary routed request: the vision chain's own fallbacks, pause list, health registry and retries apply, and it gets its own row in the request log against the request that carried the picture, priced separately so it cannot make the answering model look more expensive than it was. Clear the cache from Requests → Clear image descriptions when a better vision model arrives.

Nothing here can cost you an answer. A describe call that fails falls back to route; a route with nowhere to divert to falls back to the placeholder sentence. And both modes fire only when the answering model is published as unable to read images — a model that can see is simply sent the picture, which is cheaper than two calls and always better.

See what a request actually did

Two local SQLite stores under ~/.mcc/logs/, written by a background thread so they never block a request.

Not every row has a provider. Requests MCC answered itself show answered locally · <rule> in the provider column rather than crediting a provider that was never called. They are real rows with real token counts, and they filter like any other value — see the Token Optimizer page.

Web searches are local answers too. Claude Code sends each web search and web fetch as its own small request, and MCC answers it with its own search. Since 7.69.5 those rows read answered locally · web search (or · web fetch): no provider, no model, not priced, and hidden while Local answers is on Hide. Before, they carried the first model of the chain — even a paused one that was never called — and were priced as if it had answered. Rows written before 7.69.5 keep that old name. A request that reached a model always keeps the model's name and its attempt rows.

Local answers is set to Hide. On a busy install those rows outnumber the upstream ones, so the table, the cards, the charts and the breakdowns default to real upstream traffic. Switch the Local answers filter to Show for the old totals, or Only to look at nothing else; the choice is remembered across refreshes. Rows whose provider is genuinely unknown stay visible under Hide, and the All time rollup ignores this filter as it ignores every other one. Every filter applies itself — selects on change, typing after a short pause — so Apply is now only there when you want it.

How often this page asks the server. With Auto-refresh on, the table follows the interval chosen beside it; a request finishing no longer reloads the whole page. The heavy totals — the cards, the charts, the breakdowns, cost, latency and TTFT — are re-read at most once a minute, and each panel's caption ends with as of hh:mm:ss, the time its numbers were computed. Opening the page, changing a filter, paging or pressing Refresh still reads everything at once. The in-flight count beside Analytics on other pages reads every 10 s, only one tab per browser polls (the others show what it reads), and a busy or silent server makes the polls wait longer instead of piling up. After an update, reload any dashboard tab that was already open.

Input tokens are reported in parts, because they bill differently:

p50 and p95 latency are approximate. They are read from a 64-bucket histogram rather than by sorting every stored duration, which is what makes an all-time view load in a fraction of a second instead of half a minute. On a real log the error measured at or under 2.3%; on a filter matching only a handful of requests it can be larger, because there is nothing inside the bucket to interpolate against. The average, and every count, stay exact.

A hit rate of — means that provider never reported caching, which is different from a measured 0.0%. OpenRouter, OpenAI (prefixes of 1,024+ tokens), DeepSeek and — since 6.68.2 — ChatGPT OAuth report it. NVIDIA NIM's hosted endpoint does not do real prefix caching, so a near-zero rate there is accurate rather than a fault.

ChatGPT OAuth rows logged before 6.68.2 read —, and stay that way. The endpoint was reporting the figure all along and MCC was not reading it, so those requests were never measured; nothing is backfilled, because a guess in that column would be worse than a dash. Their input counts were also cache-inclusive and so ran high — from 6.68.2 the cached part is reported separately, the way every other provider's already was.

Every row has a View dialog with the full exchange, the resolved configuration and timing — usually the fastest way to see what actually happened. Web search analytics separate logical searches from provider attempts, so one search that fell back shows as one search and several attempts.

A model can think without the text reaching you, so the dialog’s Thinking line has four answers: thinking shown; thought — text withheld by the provider (the provider reported reasoning tokens or sent signed, redacted or encrypted-only reasoning, as Claude 5 does by default and as Claude Code asks unless showThinkingSummaries is on); did not think; and not measured. The Models page counts the same split, and the Turns with visible reasoning tile counts only the first.

Export opens the export window for Model requests, Route attempts or Web Search — JSON, CSV, XLSX or TXT, over a period of your choice, with selectable fields and optional grouping by provider, period, model or key. It streams the entire matching row set, not just the visible page.

Export attempts, beside it, opens the same window on the Route attempts scope: one row per model the chain tried, rather than one per request. A request that fell back twice is one row in the Model requests export — one provider, one model, one verdict — and the two models that spent the time are not in it at all. Each attempt row carries its own provider, model, outcome, key, TTFT, first-reasoning time, duration and what ended it, beside the parent request's time, harness, endpoint, models and status.

The filters are the request filters, and empty means never measured. Period, provider, model, key, status, harness, search and Local answers all select requests, so every attempt of a selected request is in the file — including the failures, which is the point. The latency columns did not exist before 7.4.0 and are not backfilled, attempt tokens are filled only on the winning attempt, and a skipped attempt has no latency at all — only a reason. Those cells are blank rather than zero. The scope is detail-only: there is no Group by, because the per-model p50 TTFT cards already answer that question properly.

Finding a request again

Search text looks at everything a request contains — the prompt, the reply, the model's reasoning, and its tool calls including commands and paths. That matters more than it sounds: on a typical machine reasoning appears in about half of all requests and tool calls in three quarters, so searching only the prompt and reply missed most of the transcript.

Every word has to appear, in any order and anywhere in the request, so proxy 8082 finds one that says "restart the proxy" in the prompt and "port 8082 is busy" in the reasoning. One word behaves as it always did. Matching ignores case and matches inside words.

A saved search no longer runs by itself when the page opens: the box shows it under a one-line notice, and you press Run (or Enter) to start it, or Clear to forget it. Typing cancels the previous search. While a search reads the log, newest first and over the window you picked, progress is shown where the pager said "counting…" — for example searched back to 12 Aug · 412,000 of 598,683 rows. The matching rows appear first; the count and the cards arrive together when the whole window has been read.

The search index (7.92.0) answers a search without unpacking stored requests. It lives in its own file beside the log, requests-search.db, and holds each distinct piece of text once: a conversation repeats itself on every turn, so the index is a small fraction of the log. Every request logged from 7.92.0 on is indexed as it is written. Requests logged before are indexed only when you press Build search index under the filters; it works between requests and searches, newest first, says how far it has got (Build search index: 41 % · 3 min left), can be paused, and continues after a restart. The line also says how much of the log the index covers (Search index covers 412,000 of 598,683 rows). Rows it does not cover are searched the old way in the same search, so the results are always exactly what they were before; only the time changes. Since 7.93.0 the file also holds the prompts the log stores as chunks, so keep it with the log and do not delete it; Clear log clears it with the log. If this Python's SQLite cannot keep the index, the line says so and searches read every stored request, as before.

What the request body pane says

The wire is the headline. Each attempt in the request detail opens with every parameter that actually left — every top-level key of the body plus each provider-specific extra_body.<name> — above the message structure, and that list is never truncated. Only messages and tools degrade, to counts and names, once the stored body passes REQUEST_LOG_WIRE_BODY_MAX_CHARS on the request-log card; what is kept always parses as JSON.

Reasoning reads as one of three honest states: reasoning sent with the value carried, no reasoning instruction sent (model default applies), or not measured where that provider has no instrumented commit boundary — the pane is never hidden, because a hidden pane reads as "no body was sent". A badge marks the one real contradiction: reasoning was resolved to something the wire then clamped or substituted. Sending nothing at all is not a contradiction and does not badge, and rows written before this was recorded badge nothing either way.

A dash is not a zero anywhere on this page. A dash means nobody measured it; 0 means it was measured and was zero — a completed stream that returned no reasoning stores a real 0. The same rule covers keys: each attempt names the credential it used, and (no key available) is what you see when the whole pool was benched, rather than a key label invented after the fact. The Models page adds a measured chip per model — how often reasoning was requested over the last 7 days, and how often it came back — two independent facts.

The retry ladder. An attempt is not one request upstream: it is up to five tries per credential, across every credential the pool hands it, with backoff in between. Under each failed attempt the chain now lists every one of those tries — its status, its key, how long it took, how long MCC then slept, and a redacted excerpt of the upstream’s own reply — plus one line per credential saying whether the pool charged it and why. The root-cause sentence above them is stored with the row, so the modal and every export say the same thing. Analytics → Upstream statuses counts the same tries across the window, which is why it can disagree with Top errors: that groups by the one message that survived a whole ladder. Attempts recorded before 6.12.0 show no ladder — not measured, not “there were no retries”.

The raw log, per request (7.121.0)

At the very bottom of a request’s detail there are now four collapsed boxes — API payloads, SSE events, API error tracebacks and CLI diagnostics — for the four optional logs a request can write. They are the raw material itself, not a rendering of it: the payload MCC sent, a Python repr and not JSON (there is a labelled Pretty-print as JSON button beside it, which reads it as a literal in your browser and never evaluates anything); the server-sent events exactly as written, with the model’s own <thinking> tags and whitespace intact; the provider’s own frames where MCC records them (the Anthropic Messages and OpenAI Responses doors) — and, where it does not (OpenAI Chat Completions, Gemini), the box says so rather than passing MCC’s re-encoding off as the provider’s bytes.

Each box has a Raw | Normalized toggle. Raw is the recorded lines, every one of them: a box reads them a page at a time with a Load more control and never drops a line, and if the log rotates while you are paging it says so instead of showing the wrong lines under the right numbers. Normalized is what the request log stored — the prompt, the answer, the reasoning, the tool calls, the wire body per attempt — labelled with the column each part comes from. The two views never stand in for each other: an empty Raw box says why it is empty (the setting is off, and where it is; the request is older than the retained window; the data exists only in normalised form), in the server’s own words. The choice of view is remembered for this browser, and each box has a Copy button that copies exactly what is on screen.

Nothing is masked here, on purpose. These lines hold prompt text, answer text and whatever was pasted into them, credentials included — that is what a raw log is for. The route is loopback-only like every other admin route, and the page says what it is showing. Export this request… writes the boxes to one file in any of the four export formats (Raw, Normalized or both; any subset of the four), through the same reader and renderers as the Analytics export, so the file is exactly what you looked at. The Analytics export’s field list gains an opt-in Raw diagnostics group — one column per kind, each cell headed by the request id, the source and the line count, and the lines in full — off by default (an export that does not ask for it is byte-identical to before), limited to 200 requests, and never combined with Group by.

Turn the logs on first. The four boxes read the settings on Limits & Resilience → Diagnostics: LOG_RAW_API_PAYLOADS, LOG_RAW_SSE_EVENTS, LOG_API_ERROR_TRACEBACKS and LOG_RAW_CLI_DIAGNOSTICS. Save applies them; a request makes a new row and new lines, so turn one on, make the request again, then open its detail. The raw file holds about an hour of your traffic at 50 MB per rotation with SERVER_LOG_RETAIN_FILES kept, and the boxes quote the window they actually found. Managed CLI output is the one thing that cannot be tied to a request: the CLI runs outside any HTTP request, so it carries no request id.

How long each model took to say anything

A request that fell back waited for every model ahead of the one that answered, and until 7.5.0 the whole of that wait was printed against the model that rescued it. The Requests row now shows the winner’s own first-token time, with a +N s suffix for the time the chain lost — 300 ms +4.4 s reads “the model that answered took 300 ms; you waited 4.7 s”. Both numbers are in the cell’s tooltip. The gap is not small: across a 290,074-request log the mean is 8.6 s when the first model answered and 25.2 s when a fallback did.

View breaks the same request into its attempts: each row of Route attempts carries its own TTFT, first reasoning time, generating time, tokens out, tok/s and what ended it. Output rate is measured from the winner’s first token, so a fallback request no longer reports a rate that is too high. A model that was never asked keeps its row with dashes and its bench reason underneath.

Analytics → Model latency groups every route attempt by model and outcome: a model that answers in 300 ms and fails after 90 s is one model and two facts, and one average would hide both. Each row leads with its median (p50), keeps the p95 in the tooltip, and states how many of its attempts were actually measured — a panel may never report a percentile over twelve attempts as if it described 4,431. The panel answers over the window only, not the filters above it: a failed attempt has no request row to filter on. The Models page carries the same median per model as a chip, and no chip at all for a model nothing has measured.

There is a third outcome beside answered and failed: client hung up. An attempt that was streaming when the client closed the connection is recorded as a failure of that route — the model did not answer — but what ended it was the client’s own idle watchdog, typically after 300 s or 600 s of silence. Counting those 300–600 s waits as failures of the model made healthy models look broken, so they are their own group and are not in any model’s failed p50 or p95.

Analytics → Why requests were cancelled splits the Cancelled card into the four things that word covers. Client gave up waiting: nothing readable ever reached the client — no frame at all, or a first frame that arrived at the instant the client had already gone. Committed, then silent: a first frame arrived with time to spare and no content ever followed it. Stopped mid-answer: output or reasoning had already been delivered, normally the user stopping the stream. Server restart: the request ended within five seconds of a server session that another session followed, so MCC’s own shutdown cut it; that one wins when two apply. The same label appears as a chip on every cancelled row, in View with a sentence explaining it, as a value of the Status filter, and as a column in every export. It is derived from columns the log already stored, so nothing was added to what is recorded and every historical row carries one.

Nothing before 7.4.0 is measured, and none of it can be. The log never recorded when each attempt’s own stream began, so there is nothing to recover: those rows show dashes for ever, and the panel says so in words rather than leaving a blank column. New requests fill it in as they arrive.

When the numbers stop moving

REQUEST_LOG_MAX_ROWS caps stored rows, so once the log is full one row is deleted for each one that arrives. Everything above All time is therefore a rolling window, and at the cap it stops rising however much traffic you run. Analytics tells you when that happens rather than leaving a frozen counter looking broken.

All time is a small permanent tally kept per day, provider and model. It keeps counting after stored rows roll over, so per-model requests and token usage stay true. It ignores the filters and the time range deliberately. Upgrading seeds it from the history still retained — anything already pruned is gone — and Clear log erases it along with everything else.

Bodies dominate the disk cost — 99% of it, at roughly 30 KB of text a request against 332 bytes of metadata. They are stored compressed against a dictionary trained on your own traffic, which works well here because consecutive requests repeat almost the same system prompt and history: about 6x more retention for the same disk, measured on real traffic. Set REQUEST_LOG_COMPRESS_BODIES=false to store text inline instead, or REQUEST_LOG_CAPTURE_BODIES=false to drop it entirely and give up the drill-down.

Each attempt's wire snapshot — the structure of what was sent upstream — is compressed too, against a dictionary of its own (37x on a real log), and reads back exactly as it was written. Prompts, the rest of a body and wire snapshots each relearn their dictionary in the background once it is older than the last 14 days of traffic and 1,024 new samples of that kind exist; older dictionaries are kept, so no row ever becomes unreadable. Since 7.74.0 older history is converted too, by itself, in the background: a value is replaced only after its new form decodes back to exactly the same bytes, the file shrinks gradually as freed space is handed back, and the progress shows beside the log's size. An older version reads everything but shows a compressed wire snapshot as empty until you update again.

Since 7.75.0 a request's headers, route chain and parameters, which repeat a few hundred values across every row, are stored once each and named by number — new rows from the start, older rows by the same background conversion, with the same read-back check. Everything on these pages reads exactly as before. An older version shows those three fields empty on converted rows until you update again; nothing is deleted.

Since 7.76.0 the route attempts a chain skipped — "never reached", "paused by you", a provider in cooldown — which were nine attempt rows in ten, are stored compactly: one small row per request naming a stored set of them, each set kept once. New requests are written that way, older ones by the same background conversion, and a row is deleted only after its compact form reads back identical. The route trace, the attempt export and every Analytics figure read exactly as before. An older version leaves the skipped attempts of converted requests out of its route trace until you update again; nothing is deleted.

Since 7.93.0 each prompt is stored once per repeated part. Turn N+1 of a conversation repeats turn N, so the log keeps a prompt as the list of the search index's chunks it is made of, each chunk stored once in the index file beside the log. Older prompts are converted by the same background conversion and new ones shortly after they are written, each read back byte for byte before its stored form is replaced; the file shrinks in steps as freed space is handed back. Pause beside the log's size stops it until you press Continue. Everything on these pages reads and searches exactly as before. An older version shows converted prompts as empty until you update again; nothing is deleted. The search index file now holds prompt text: keep it with the log.

No traffic, or no server?

A flat stretch in Requests over time means one of two very different things and the chart cannot tell them apart. My Claude Code records when a server was actually running, so a line under the chart says whether one covered the range you picked, or how much of it had none. Choose a time range to see it; over all time there is no bounded window to measure. Restarts are ignored, and periods before you upgraded report nothing rather than claiming downtime nobody measured.

Search content routinely includes private queries and page text. WEBSEARCH_LOG_CAPTURE_CONTENT=false withholds the payloads and the query text, keeping only lengths and hashes. API keys are never written to either store — only masked labels.

What a request cost

Every request is priced once, at the moment it is written to the log, and the answer is stored beside it with the name of the source that produced it. It is never recomputed when you look at it: a price that changes next month must not silently rewrite last month's bill.

Pricing walks the same ladder every other model fact walks — the host's own answer first, then this provider's catalogue, then a reference catalogue, then a vote across other providers. The rung that answered is what tells you how much to trust the number, so it is carried back and shown:

“Not priced” is a dash, never $0.00. Those are different facts. $0.00 is a claim the request was free, and only a source that actually publishes a zero — a :free model's own catalogue entry — may make it. So every total carries an “N of M priced” denominator beside it, and a partial total can never be misread as a complete one.

Reported and estimated are never added together. One merged figure would launder a guess into a fact and afterwards nobody could tell which half was which. The panel shows two numbers, per provider, per model, per harness and per day.

Three things surprise people, so they are worth stating:

• One request is priced from one rung, whole. A source that names an input rate but no cache-read rate has not priced a request that read from cache — that request falls to the next rung entire rather than being stitched together from two sources into a number nobody published.
• Nothing is backfilled. Requests logged before 6.54.0 stay unpriced forever. Pricing them at today's rates would produce a confident number that was never anybody's bill.
• 1-hour cache writes take the 1-hour rate (7.111.0). Anthropic says in every answer how many cache tokens it wrote for 5 minutes and how many for 1 hour (the request detail's Cache writes by lifetime line), and bills them differently. The 1-hour writes are priced at a rate a source states for that model on that host — the provider's own list, LiteLLM's map while its pricing is on, then OpenRouter's live list to fill a gap; models.dev states only the 5-minute rate. Where no source states it the request is not priced, and says why — never priced at the 5-minute rate. The cost line names the rate each part took, and the Cache lifetime row on the Models page shows the 1-hour write price and its source. Requests logged before 7.111.0 priced 1-hour writes at the 5-minute rate and keep that price.
• A describe hop is its own row. It is a different model on a different key; folding it into the answering model's figure would hide what describe mode actually cost.

The controls are on this page under Cost estimation: the master switch (COST_ESTIMATION_ENABLED, on), which sources may answer (COST_ESTIMATION_MODE — auto, reported_only, or computed_only, the last being how you audit a provider's own billing against a published price), and the LiteLLM source (COST_SOURCE_LITELLM_ENABLED, off). Since 7.97.0 turning it on downloads LiteLLM's price map into ~/.mcc/cache/litellm-prices.json — at once, then in the background after a catalogue sweep whenever the copy is older than LITELLM_CACHE_TTL_SECONDS — and until the first download lands LiteLLM prices nothing. Off, nothing is fetched. The Models page shows the resolved input, output, cache and reasoning rates per model in USD per million tokens, each with the rung it came from — so you can see what a request would be priced from before you send one.

Which agent sent this?

Every request in the log is attributed to the coding agent that made it, so Analytics can answer "what is Crush actually costing me" and not just "what did this model cost". The column is in the request table, it is a filter, it is a breakdown, and it is in the exports.

There are two ways a row gets its answer, and the difference matters when you are reading a number:

• The agent said so. MCC's launchers configure the CLI to send an x-mcc-harness header naming itself. This is exact.
• We recognised it. Five agents cannot send that header — Kimi Code, Aider, Droid, Goose and Antigravity — because nothing in their configuration format describes a request header. They are attributed by user-agent instead, which costs certainty and nothing else. Each row records which of the two it was.

Qwen Code and Pi are filed as Claude Code until they send the header. Both emit Claude Code's user-agent verbatim — claude-cli/<their own version> (external, cli) — and there is no reliable way to tell the three apart from the user-agent alone. A version-range rule would misfile the day Claude Code ships a 0.x or Qwen Code a 2.x, so fingerprinting deliberately answers claude for all three and the explicit header is what separates them going forward. If your Claude Code numbers look too big and you run Qwen Code or Pi, this is why.

An agent missing from Analytics never reached MCC. The log records what this server answered. A request that went straight to a vendor cannot appear here however long you look, so a missing agent is a configuration problem in that agent, not a reporting gap. Launch it from the Coding agents page and it will be configured correctly by construction.

Folder is read from where Claude Code sends it (its first message, since 7.87.1); press Fill in folders for older requests once, on the Request log storage card at the bottom of Analytics, to fill the rows logged before that. Since 7.88.0 the requests table shows the Exit each request went out through where the Folder column was; the folder is still in each request's details (View), in the Session cell's tooltip, in Requests by folder, and in the Folder filter.

Desktop & RTK

The desktop app starts the server itself, every ten seconds, on every path. Since 6.61.0 one controller on one ten-second tick decides everything the window does about the server: it checks, and if the server is not running it starts one — on that tick, with no attempt cap and no page that waits for you to press anything. Every page carries the same two numbers (last checked 3 s ago, next start attempt in 7 s), Retry now only brings the next check forward, and reloading the window shows you the page you were on rather than resetting it. It replaced seven separate waiting loops, six of which could reach a page with nothing running behind it.

A port conflict is now decided by the process, not by a bind test. My Claude Code's own server binds its port about twenty seconds before it answers anything, and a bind test cannot tell that from a stranger — which is how the window came to tell one user that My Claude Code was not My Claude Code. The holder is identified by its pid, image and command line: ours and wedged gets a Take port button, genuinely somebody else's is named and left alone, and an unidentified holder is given DESKTOP_FOREIGN_GRACE_SECONDS (45 s) before it is called a conflict at all.

On Windows the desktop app owns the tray icon. There used to be two — the app's and the Python tray's — with different menus and two different answers to “restart the server”. The app's is the one that stays: it is the process that survives an update. Closing the window hides it to that icon and leaves the server running, Open dashboard brings it back, and Quit is the only thing that ends the app. The Python tray is still the fallback wherever no desktop app is installed, and on macOS.

The optional mcc-desktop tray app changes how the server is owned, and its Server mode is set here on the Deployment card (or from the tray menu): spawn owns mcc-server as a child, attach connects to an existing server and never spawns one, and off leaves the server untouched. Start at Login registers a different target per platform — the tray on Windows (HKCU Run key) and macOS (LaunchAgent), and headless mcc-server under systemd --user or an autostart .desktop entry on WSL/Linux. The tray menu also covers Open Admin, Check Server Status, Restart Server, Tray Enabled, and Quit; preferences live in ~/.mcc/desktop.json.

Since 6.44.0 the first thing Auto tries is the My Claude Code desktop app — a ~1.5 MB window this project builds and attaches to its own GitHub releases. uv tool install cannot deliver a compiled binary, so the first mcc-desktop launch after upgrading downloads it, checks its SHA-256 against both the checksum file published on the release and a digest pinned inside this build, and installs it at ~/.local/bin/MyClaudeCode with a receipt beside it so it never downloads twice. If any of that fails — no network, a proxy, an architecture with no build — the launch is not blocked: it warns once and falls back to app-mode. Opt out with DESKTOP_SHELL=off or by picking App-mode window here; MCC_DESKTOP_SHELL_DIR moves the install somewhere other than ~/.local/bin. It is unsigned, so Windows SmartScreen may warn on first run.

Since 6.60.0 the app keeps itself on that pin, however you launch it. Until then the pin was checked in exactly one place — the moment the tray created a window — so anyone launching MyClaudeCode.exe from the Start Menu, the taskbar or the Programs-folder install ran whatever build they first received, forever. One person ran the v6.43.0 window for fifteen releases while the wheel updated itself every time. The app now compares the release stamped into it (MyClaudeCode --version) with the shell_release_tag the wheel reports and, when they disagree, runs mcc-desktop --ensure-shell in the background: one command that downloads the pinned build, checks both digests, and puts it where it belongs — replacing the file outright when nothing has the app open, and otherwise leaving it beside the running executable as MyClaudeCode.exe.new. It never writes over a window you are running, and the operating system is what decides whether you are: Windows refuses to replace a running image, and on Linux and macOS a running process keeps the file it started from. The tray then offers Desktop app update ready — restart the app to use vX with a Restart now; ignore it and the swap happens the next time you start the app anyway. The previous build is kept for one run as MyClaudeCode.old-<stamp>.exe.

The window can no longer save itself off-screen. Until 6.60.0 the tray's Quit saved the window's geometry after a close-to-tray had hidden it, and what Windows reports for a hidden, minimized window is 0×0 at -32000, -32000. That was written to disk and restored verbatim on the next launch, so the app came back as a tray icon with no window on any screen. Geometry is now never saved while the window is hidden or minimized, and a remembered rectangle that is not at least partly inside a connected monitor's work area — or is below the window's own minimum size — is not restored at all: the window opens at the configured DESKTOP_WINDOW_WIDTH×DESKTOP_WINDOW_HEIGHT (1400×900 by default), centred. Changing that size here now applies on the next launch even after you have resized the window by hand; resizing by hand still sticks otherwise. If you are ever left with a tray and no window, the tray's Reset window position — or MyClaudeCode --reset-window — forgets the remembered geometry and opens centred.

You do not have to start the server first. mcc-desktop in spawn mode probes the port: a healthy server means it simply attaches to the one already running, a free port means it starts one as its own child, and a stranger on the port is an error rather than a silent attach. It also no longer leaves a browser tab behind — the server it spawns is told not to open one, so one launch produces one window rather than a window and a tab. Launching it a second time raises the window you already have. Closing the window does not stop the server; the tray's Quit does.

A slow start is not a failed one, and giving up is not final. The window gives the server it starts DESKTOP_SERVER_START_TIMEOUT (15 s) to answer, and since 6.58.1 it does that three times — DESKTOP_SERVER_START_RETRIES (2) more attempts, 45 s in all — before it says anything went wrong, with the countdown naming the attempt (attempt 2 of 3). A real configuration takes 22–25 s to bind, because everything loaded at startup happens before the port opens, and a single 15 s budget gave up about seven seconds early. A retry never starts a second server: a starting server has not bound its port, so every check says free, and what the window watches instead is whether the child it started is still running. The page you get if all three attempts run out keeps checking on the health poll, so a server that binds late loads the dashboard on its own — Retry is an accelerator now, not the only way out.

First launch, when MCC is not installed at all. The window runs the project's installer and shows its output, and since 6.58.1 it does that at most three times. An installer that succeeds without putting mcc-desktop on the running window's PATH — the ordinary Windows first launch, since a PATH change reaches only new processes — used to mean reinstalling every few minutes forever under a spinner that said Checking the server. It now says what it is doing, quotes the installer's last line, tells you that quitting and reopening the window is the fix, and keeps watching for mcc-desktop to appear. The installer itself is stopped after 15 minutes rather than holding the window for the session.

Getting the app without the command line. Every release carries an installer for all three systems: MyClaudeCode-Setup-windows-x86_64.exe (per-user, no administrator rights, SmartScreen's More info → Run anyway on first run), MyClaudeCode-linux-x86_64.deb for Debian/Ubuntu and MyClaudeCode-linux-x86_64.tar.gz with an install-desktop.sh (and install-desktop.sh --uninstall) for Fedora, Arch and anywhere without root, and MyClaudeCode-macos-universal.dmg, one file for Apple silicon and Intel. Each digest is in SHA256SUMS-desktop-shell.txt on the same release page. The .dmg is unsigned, so Gatekeeper blocks it: drag the app to Applications, then run xattr -d com.apple.quarantine "/Applications/My Claude Code.app" once and open it. Letting mcc-desktop fetch the binary instead avoids that entirely, because a file Python downloaded is never quarantined. A winget manifest exists in the repository but has not been submitted, so winget install will not find this yet.

Two uninstallers, on purpose. “My Claude Code (desktop app)” in Apps & Features (or install-desktop.sh --uninstall on Linux) removes the window and nothing else — your keys, your history and mcc-server are untouched. Removing those is uninstall.ps1 / uninstall.sh, which is a separate, deliberate step. Set MCC_DESKTOP_SKIP_AUTOSTART=1 to stop a launch reconciling the machine-wide start-at-login registration — useful when you run a second config directory and do not want it fighting the first over one registry value.

The Window control on the same Deployment card picks how mcc-desktop shows the dashboard: Auto (recommended), App-mode window, Embedded webview, or Browser tab. Auto walks desktop app → app-mode → embedded webview → browser tab, and a line under the select shows what it currently resolves to, e.g. auto → app-mode (Microsoft Edge). App-mode — a real Chromium browser process with no tabs or URL bar — is the fallback, and a good one: window.open (both OAuth logins), <a download> (the analytics export), and navigator.clipboard (every copy button) all break inside an embedded webview, and app-mode is a real browser process so all three keep working. The CLI equivalent is mcc-desktop --window auto|app-mode|pywebview|browser; an explicit choice there falls back through the browser providers only, never into the desktop app.

mcc-desktop --status prints those preferences as five key=value lines. mcc-desktop --print-status prints the same answers, plus the admin and health URLs, whether the port is held by a healthy server, nothing, or a stranger, and the reconnect budget, as one JSON document for scripts and for a window that renders this dashboard. Both are read-only: neither starts a server or changes a setting.

A --desktop flag on the installer (-Desktop on PowerShell) adds a Start Menu shortcut on Windows, a .desktop entry on Linux, or a minimal .app bundle on macOS. It's opt-in and never fails the install if the shortcut can't be created.

Nine DESKTOP_* settings under Limits → Desktop tune polling intervals, timeouts, initial window size, and an optional DESKTOP_BROWSER_PATH override. They apply on the next mcc-desktop launch, not to a tray already running — it is a separate process that reads them once at start.

WSL and headless Linux still have no tray. Run mcc-server there instead and reach the dashboard from a Windows browser at the URL it prints on startup. A Linux desktop session now does, which is new: the old refusal was about the tray rather than the window, and the fetched app carries its own. It needs webkit2gtk-4.1 — Ubuntu 22.04+, Debian 12+, Fedora 40+ — and still refuses correctly when there is no DISPLAY or WAYLAND_DISPLAY, naming the reason.

When the server is busy, and when it is dead (7.71.0)

The desktop app decides from what the operating system says about the port, never from a check that timed out. While the server’s process still holds its port it is busy: this dashboard stays on screen under an amber banner (“The server is busy: it is running (process 33560) and still holds port 8082 … Nothing will be restarted while that is true.”), nothing is reloaded, started or stopped, and the banner goes away by itself when it answers. A lookup that fails counts as busy too.

Only when nothing listens on the port is the server dead, and then the app replaces it: at once if its process exited; after three looks over 30 seconds if the process is still running without its port (so a reload that re-opens its own port is never touched); and a server the app itself started that has not opened the port after its whole start budget (60 s at 20 × 3) — never one that ever answered, even 503 starting. Replacing means: look again and do nothing if anything holds the port; give each old server up to SERVER_GRACEFUL_SHUTDOWN_SECONDS + 4 s to finish its open requests and exit by itself; stop by exact process id only what is still there; wait up to 15 s for the port; start a new server, and watch it for 15 s before anything counts against it. “Old servers” are only My Claude Code servers of this port and this configuration folder — never a server on another port, never another configuration folder, never a program that is not My Claude Code. Every server the app starts runs with --no-port-takeover and opens no browser tab.

You are told, by the app. When the server is found dead and after every replacement, the app says what was stopped and why: as a banner at the bottom of this window, in desktop-server-start.log beside server.log, and as a notification under the name My Claude Code — on Windows when the app was installed with the Windows installer (which registers that name and removes it on uninstall), on Linux through notify-send. A copy the app fetched for itself, and macOS in this release, show the banner instead of a notification under another program’s name. The app has to be updated to 7.71.0 for any of this (7.71.1 for the Windows notification, which 7.71.0 never showed on a fresh install); until it is, the server you run still never lets a new start take the port from a server that answers.

The Token optimizer card on the Providers tab manages the RTK binary, which filters noisy terminal output before it reaches the model. Toggle it per agent (Claude Code, Codex, Pi); the state lives in ~/.mcc/rtk.json and applies immediately. The same controls are available from the tray's Token optimizer submenu or the CLI:

Two different things share that name. This card is the RTK on/off switch, and it lives here. The Token Optimizer page in the sidebar is where you read what any of it saved — including RTK’s own savings figure, which now appears there as a card in the Ledger, taken from the binary’s own accounting rather than estimated. MCC pins a specific RTK version and installs that one the first time you enable an agent.

mcc-rtk status              # installed binary + enabled agents
mcc-rtk enable claude,pi    # install the hook for these agents
mcc-rtk disable codex       # remove the hook for one agent
mcc-rtk uninstall           # disable every agent and remove the binary
mcc-rtk apply               # re-apply the stored state

The Token Optimizer page

This page answers one question: what did any of this actually save? Measurement comes first, and each control sits beside the number it moves — so nothing here is a switch you flip and hope.

Requests MCC answers itself

Some of what a coding agent sends is not work for a model at all. Claude Code asks a model to invent a name for your session, and it asks for the suggested next message it offers you. MCC recognises both and answers them locally: no provider call, no token spend, no latency. Two rules ship, both on by default, both toggled here — Title generation skip and Suggestion mode skip.

These used to be invisible. Every locally answered request is now recorded with the rule that answered it and what it saved, and it credits no provider, because none was involved. So in Analytics the provider column reads answered locally · title generation skip instead of attributing free traffic to whichever provider you happen to have configured. The token counts on those rows are measured now too, rather than the fixed placeholder they used to report.

Filtering for them. Pick the answered locally · … entry from the provider filter’s list and it works. The value behind that label is local:title_generation_skip — the underscored rule name — so if you are typing rather than picking, type that.

Candidates: finding rules that do not exist yet

Scan the log reads your own request history, groups it into recurring prompt families, and shows which of them no rule covers. It is the honest way to decide whether another rule would be worth having.

• It runs only when you press it. Nothing is scheduled and nothing is cached; the log is not read until you ask.
• It is bounded. A scan reads 2,000 rows by default and you may raise that to 50,000. Above that ceiling the request is refused with a 422, rather than quietly scanning a sample and presenting it as if it were the whole log.

Tool-result trimming — off, and measured

Trimming shortens large Read, Grep and Glob results before they reach the model. It is the only feature in MCC that changes what the model is allowed to see, it is off by default, and it is not a recommended optimization. The measurements are the reason.

If you want it anyway, there is a master switch and then three states per rule:

• Off — results are left untouched.
• Observe — measures what would be removed and records it; the wire is unchanged and the model sees exactly what it saw before. Run a rule here against your own traffic first, and read the result before committing to it.
• On — performs the elision and marks it inline.

These controls used to live on Limits. They are on this page now, next to the figures that tell you whether they helped.

What the log keeps

The Request log storage card at the bottom of this page decides what these tables can ever show. Requests to keep is the retention cap: the newest N requests are kept and older rows are deleted as new ones arrive. All-time counters keep counting either way, so raising or lowering it never changes your lifetime totals. Bodies are about 99% of the stored bytes, so Store prompts and replies is the setting that decides whether content search works at all, and Compress stored text applies to new rows — run mcc-compact-log to convert existing history.

Limits & resilience

Every value on the Limits & Resilience tab is a ceiling on one request, or what happens when a model will not honour one. It is six cards now behind a section rail that follows you down the page — Budgets, Deadlines, Chain benching, Retries & throughput, Credential health and Diagnostics — each saying in one line what it decides. Each field states what the value costs and the range it accepts, beside the box rather than at the end of the paragraph.

Two cards left this page. Request-log storage is on Analytics, beside the numbers it bounds; desktop tray and window timing is on Providers, beside the desktop panel itself. The token-optimizer controls moved earlier, to the Token Optimizer page.

How long a stop may take

Graceful shutdown budget (SERVER_GRACEFUL_SHUTDOWN_SECONDS, on Deadlines) is the one field on this page that does not bound a request — it bounds a stop, end to end, and since 6.41.0 it is the only number that does. Ctrl+C, the reload that follows an Apply of one of the few fields that still need a restart, the tray's Restart Server, and the restart that finishes an update are all the same operation underneath and all obey it. It ships at 20 seconds. At the instant a stop begins the server stops taking new work: a request arriving during the drain gets 503 with Connection: close and a Retry-After, so a busy client can no longer keep a closing server alive. Requests already in flight get the whole budget; at the bound whatever is still open is closed, an in-flight stream simply ends with no special frame, and your agent's own retry finds the restarted server a moment later. The process exits a few seconds past the bound whatever is still running. The floor is 1 s and the ceiling 600 s.

If you set 300 here on an older install, lower it. Before 6.41.0 this bounded only one wait inside the stop and everything after it was unbounded, so a large value cost nothing in practice. Now it is the time you spend watching a tray icon after pressing Restart — and it is the number the tray and the Windows update helper both wait before they terminate the server themselves.

It slows every update, not just every stop. An update waits this budget out twice over: the installer does not begin until the old server has finished draining, and the reconnect budget the desktop window counts down is this number plus the install allowance. Measured on a real machine, 300 here added five silent minutes to a fourteen-minute update and turned the window’s “reconnecting for up to 17 minutes” into 22. If a restart feels long, this is the first field to look at.

What one answer may cost

Budgets bounds the tokens one reply may spend. MAX_OUTPUT_TOKENS_CEILING ships at 131,072 and is the cap on the room a reasoning request is given; blank falls back to that default and 0 means no ceiling at all, which is a real choice rather than the absence of one.

New in 6.47.0, and it changes what your install sends. MAX_OUTPUT_TOKENS_FLOOR ships at 8,192 and is the smallest allowance any request goes out with — the only bound on this card that raises a number rather than lowering one. A client that hardcodes max_tokens: 512 was getting a truncated answer out of a model that could have finished it. It never raises past the routed model's own published limit, it is applied before the context bound so it can never re-inflate a budget the context cannot hold, and it leaves an explicit max_tokens: 0 alone. Set it to 0 to raise nothing at all. It is not the same setting as Smallest bounded budget (MAX_OUTPUT_TOKENS_CONTEXT_FLOOR), which decides when the prompt reserve gives up.

Two more numbers on this card became settings in 6.47.0. ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS is the last-resort max_tokens for a request that reached a provider with none of its own and no published limit to take one from; REASONING_EFFORT_BUDGET_RATIOS is the six-value ladder deciding how much of the allowance each effort spends on thinking. One ceiling is deliberately not here: NVIDIA NIM's own max_tokens, in the nested NIM settings, lowers whatever this card resolved on NIM routes only. It ships unset, and the nested group has no flat environment variable of its own to put on this card.

When to stop waiting

Every deadline on this card ships at 0, meaning no limit — so out of the box MCC never ends a silent or stalled upstream on its own. The fallback chain moves only on an error the provider actually returns. A model that thinks for forty minutes is left to think; a stream that goes quiet and never resumes stays open until the transport read timeout below ends it, or the client disconnects. That is deliberate: a deadline that kills real work is a worse failure than a stall you can see in Analytics, and this is your server to tune. Set the ones you want and the readout under the grid shows what each model on your routes then gets. An install that already sets any of these keys keeps its own values.

A fallback chain can only rescue a request while nothing has reached the client. A model that accepts a request and then goes silent holds it until the transport read timeout, minutes later, so the chain gets its turn long after the client has given up. These are what bound it, and they measure different things:

• First-token deadline (FALLBACK_FIRST_TOKEN_TIMEOUT) — seconds a model may stay silent before any output before the next model on the chain takes over. Nothing has streamed yet, so the handover is invisible. This is the only deadline here that produces a failover rather than an ending.
• Stall deadline (FALLBACK_STALL_TIMEOUT) — seconds a stream that has started producing may then say nothing, measured from the last chunk that moved the answer forward. No model can replace a stream the reader is already looking at, so this ends the request rather than moving the chain.
• Total request budget (FALLBACK_TOTAL_TIMEOUT) — the whole request, across every attempt, retry and recovery. Once output has started no fallback can replace it, but it can still stop.
• Thinking before the chain moves (FALLBACK_REASONING_ANSWER_TIMEOUT) — seconds a model may think without starting an answer, while reasoning is being held back so the attempt is still abandonable.
• Silent-attempt floor (FALLBACK_ATTEMPT_SHARE_FLOOR) — the smallest slice of the total budget the chain-side division may hand one model. It bounds each model's first-token allowance, never a retry of the same model. Ships at 3600 — an hour, wider than any interactive request — and is moot either way while the total budget is 0, because there is no budget to divide.
• Retries before the chain — attempts against one model on the same key after an upstream 5xx or a dropped connection, before the next model is tried. Each retry waits longer than the last. A 429 uses them too, unless Route around a rate-limited model is switched on in the Credential health card.

Once you set a total budget, the first-token deadline becomes a ceiling rather than an allowance: the budget is divided by the number of models still to try, so on a ten-model chain with a 600 s budget each model gets 60 s, not 120 — and the box reading 120 is inert for that route. The silent-attempt floor is what stops that share falling below the number you typed. The Deadlines card computes this for your own routes, one row each, and says which total budget would honour the number you asked for — a total budget of 1200s would give every model the 120s you asked for. At the shipped zeros every row reads no limit.

Every error one of these limits raises names its own knob. A request MCC ended reaches your client as, for example, Provider 'open_router/qwen/qwen3-max' produced no output within 300s. (FALLBACK_FIRST_TOKEN_TIMEOUT -- change it on the dashboard under Limits & Resilience -> Deadlines). The hint names the limit that actually ended the attempt, so a model cut short by its slice of the request budget names the silent-attempt floor instead. The same sentence appears on the attempt row in the request detail.

It answers one question exactly — what each model on this route is allowed before the handover — and deliberately does not model time already spent, a first model that was retried, benched models shortening the chain, or the reasoning answer deadline taking over.

When to stop trying a model

• Bench failures — the master switch, and it ships off: every model in the chain is tried every time and a failing model is retried at every request. With it off every other control in the card is inert. The same switch is at the top of Model Config, beside the routes it governs — one setting, two places to reach it. A default only applies where the key is unset: an install whose .env already carries FALLBACK_BENCH_ENABLED=true keeps benching on until that line is removed.
• What counts as a failure, once it is on: an upstream 5xx, an overloaded response, and a 401/403 from the provider. Those say something about the model. Timeouts (first token, stall, budget), 429s, quota, context_length, model_rejected and malformed requests are facts about the request — they fail identically on a healthy model — and never bench one. Counting them is how a single oversized prompt used to eject an entire chain.
• Eject mode — rate_based benches a model when a share of a recent window of requests fails (with a minimum number of samples first, so one bad minute cannot bench anything); legacy counts consecutive failures instead. The controls the unselected mode does not use stay on the page, dimmed and disabled, each saying why beside itself — Not used while eject mode is legacy, Not used while benching is off. They are not saved, so switching mode drops a pending edit to them from the next Apply, and the unsaved-change counter drops with it.
• How long a benched model sits out applies in both modes. A chain is never emptied: if every model on a route is benched they are tried in order anyway.

Which failure kinds end a route outright rather than trying the next model is FALLBACK_SKIP_KINDS, and it stays on the Model Config page — it is a routing decision, and it belongs beside the chains it ends. The Benching card links to it.

The client-side pace

Provider rate limit (PROVIDER_RATE_LIMIT, on Retries & throughput) ships at 300 per PROVIDER_RATE_WINDOW of 2 seconds since 6.68.0 — 150 requests a second, per provider. That is far above anything a person at a keyboard generates, so requests go upstream as fast as your client sends them, while a runaway loop still meets a ceiling. It used to ship at 40 requests per 60 seconds, per provider, against limits no provider had published — and because every routing attempt spends a slot, a route averaging three attempts began throttling after about thirteen client requests a minute. On one measured machine, 24 concurrent requests took a median of 938 ms and a 95th percentile of 54 seconds, all of it MCC waiting for its own window. 6.62.0 answered that by shipping 0; 6.68.0 puts a number back, at a pace that cannot be what holds you up.

Nothing about a real limit changed. A provider that is over quota answers 429 with a Retry-After, and Credential health obeys it either way. Set a positive number only to hold a metered key back on purpose — and when you do, the queue is fair: waiters are admitted in the order they arrived, so a paced request waits its turn instead of losing a lottery. PROVIDER_MAX_CONCURRENCY (default 300 since 6.68.0, was 5) was never the problem — it is an ordinary semaphore and it was always fair. Lower it if your machine or your link is the bottleneck rather than the provider.

What a key is judged on

The Credential health card holds the only two penalties a key can earn. CREDENTIAL_LOCKOUT_TIERS is the ladder a 401/403 walks — 300,3600,86400, so five minutes, then an hour, then a day for each successive auth failure (a 403 that says your country was refused — RegionError, “not available in your country” — is about the address, not the key, and since 7.96.0 costs the key nothing; the request still tries the next key, then the next model) — and RATE_LIMIT_COOLDOWN_SECONDS is only the fallback for a 429 that arrives without a Retry-After header, capped at an hour either way. That 429 bench is scoped to the one model it happened on; CREDENTIAL_MODEL_BENCH_ESCALATION is how many different models have to be rate-limited on the same key at once before the key itself is benched. RATE_LIMIT_ROUTES_AROUND_MODEL decides what happens next: off (the default) follows your chain order — the model is retried on the same key, then on each other key of the provider, with a short wait between tries, and only then does the request move to the next chain entry. On sends the request straight to a later model on the same provider, on one key and with no waits, and skips the chain entries in between for that request. Nothing else on this page benches a key; see Use more than one key safely.

CREDENTIAL_CIRCUIT_THRESHOLD no longer exists — the breaker it configured was removed along with the fixed cooldown ladder and half-open probing. A stale line for it in ~/.mcc/.env is ignored rather than fatal, but it is doing nothing; delete it.

What to keep

What the request log keeps is set on Analytics now, at the bottom of the page whose tables it decides the contents of.

Blank means default

Clearing a field is a way of saying "stop specifying this", so a blank value falls back to the built-in default rather than failing. A value outside its range is refused here with the range quoted; a value edited directly into ~/.mcc/.env is clamped at startup with a warning in the log, because a proxy that will not start is worse than one running a sane number. A setting you have never chosen is written to ~/.mcc/.env as a commented placeholder rather than a value, and Use default removes the line again — so the file records what you chose, not what the defaults happened to be on the day you saved.

When a provider runs out of credit

"Out of credits" is its own failure kind, quota, separate from a rate limit and separate from a bad key. It gets its own kind because the three want opposite responses: a rate limit means wait, a bad key means stop, and an empty balance means try something else.

Running out of credits never ends the route. quota is deliberately absent from the default FALLBACK_SKIP_KINDS: an account with no balance has said nothing about your request, and the next key or the next model may answer it perfectly well. The chain keeps going. Add quota to that setting only if you would rather a request fail than be served by a different model.

The exhausted key is benched for the cooldown so the next request does not re-spend a second on a balance that is still zero, and the card on Providers says which key and why. It comes back on its own; you do not have to re-enter anything.

Use more than one key safely

Both model and web search providers take several keys in one variable:

EXA_API_KEY="key-a,key-b,key-c"
EXA_API_KEY_ROTATION=failover

Policies are single, round_robin, least_used and failover — failover by default with several keys, single with one.

The order is the failover order. Every policy reads the pool top to bottom: failover serves the first healthy key, single serves the first key and nothing else, and round_robin cycles in that order. Open Manage keys on any provider card and drag a key by its grip, or use Move up / Move down (or the arrow keys on a focused grip). It applies at once and needs no restart, but it rebuilds the pool, so that pool's health counters and benches start again — exactly as they do when you add or remove a key.

You can name a key. Type a name in the box beside it, or in the optional Name field when you add one. A named key then reads as its name wherever a credential is shown — the card, the request log, the Analytics Key filter, the retry ladder, the per-key analytics and the CSV — with its masked label still there on hover and still in the key_label export column beside the new key_name one. Names live in ~/.mcc/credential_names.json, keyed by a hash of the key and never by the key itself; they never reach an upstream request, the request log or a rollup. A name is display only, so renaming a key rewrites no history. Renaming never restarts or rebuilds anything.

Health is tracked per key, and only the provider's own verdict on the key changes it: a 401/403 locks the key out on an escalating ladder, and a 429 benches it for exactly as long as the provider asks via its Retry-After header, never an invented delay, and only for the model that was rate-limited, because a gateway that limits one model says nothing about the key's others. Once CREDENTIAL_MODEL_BENCH_ESCALATION different models are limited on the same key at the same time, the limit is the key's and the key itself is benched. Anything else — a timeout, a 5xx, a 410, a 400 — leaves every key untouched, because the same keys serve every model in your chain and none of those is the key's doing. A model that will not answer is handed to the next model on the chain instead. How long each step of that ladder lasts is CREDENTIAL_LOCKOUT_TIERS (300,3600,86400) on the Limits & Resilience page, and RATE_LIMIT_COOLDOWN_SECONDS beside it is used only when a 429 arrives with no header to obey; the policy itself is the rotation select on each provider's own card.

The 429 cooldown is yours to set, all the way down to nothing. Three settings on that same card, and they only mean anything together. RATE_LIMIT_COOLDOWN_SECONDS is the bench used when the provider published no wait. RATE_LIMIT_COOLDOWN_MAX_SECONDS is the longest wait a provider may ask for in a header and have MCC obey; an hour was hard-coded until 7.22.0 and is still the default, and 0 removes the ceiling. RATE_LIMIT_COOLDOWN_MODE decides what a 429 costs the key at all: provider obeys the header under that ceiling and is exactly what every earlier release did, fixed ignores the header and always uses your number, and off benches nothing — no key bench, no (key, model) bench, no provider-wide pause. Off still rotates to the next key and still moves down the fallback chain, because rotating and benching are separate questions, so the consequence is the plain one: the provider goes on answering 429 and MCC goes on spending attempts on it. There was never a 15 → 60 → 3600 ladder in the code: 15 s is a wait a provider asked for, 60 s is this cooldown, and 3600 s was that hard-coded ceiling.

Rotating away is not the same as marking a key bad. Auth failures, 429s and connection errors move to the next key; anything else raises and the request moves to the next model, so a pool cannot be emptied by a model that is simply broken. The deliberate cost: a key failing 5xx or transport on every request is retried once per request rather than benched, because the failures that could have identified it were the same ones emptying healthy pools thousands of times a day. A 401/403 still locks it out.

Update the server

The version panel announces releases with their notes inline. Update now downloads the wheel, verifies the SHA-256 GitHub publishes for it, and installs it; a mismatch aborts. Extras such as voice support are preserved. Upgrading never restarts the server, so it cannot drop an in-flight stream.

An update has two halves, and since 6.60.0 the banner says so. The wheel — server, CLI, dashboard — updates itself. The desktop app is a compiled binary the wheel pins rather than carries, and nothing used to move it unless you happened to launch from the tray. The version panel now reports it (v6.43.0 → v6.60.0 on next restart), a banner says Desktop app vX available — it updates the next time you restart the app, and Update now's success message names both halves rather than declaring you finished when half of you is not. See Desktop & RTK for the mechanism. Coming from a version before 6.60.0 takes one manual step, because the thing that fetches the app is part of what is being fixed — the window you are running has no swap step in it, so nothing staged beside it would be picked up. Close the app and run mcc-desktop --ensure-shell once (with --target if the copy you launch is not the one in ~/.local/bin). Every update after that is automatic.

Since 6.61.0 you do not take that step, and neither does anyone else. Just after the server becomes ready it compares the desktop app installed on this machine with the release this build pins, and brings it up to date itself — replaced in place when nothing is running it, staged beside it as MyClaudeCode.exe.new when something is, which the app's own next start renames in. One line in the server log either way, and the panel above says the same thing. Turn it off with Update the desktop app automatically on the Desktop card. Nothing is downloaded on a machine that has no desktop app installed.

The installer owns the restart, wherever you pressed Update. Inside the desktop app the flag the window sends now means only “a window is watching, so do not open a browser” — not “I will start the server”. Two owners of “restart the server” is how one update came to start two of them, and how another started none.

The install command restarts the server — by default, since 7.1.0. Every install and every update finishes the job rather than printing a hint: it reads PORT and HOST from the configuration directory it installed for, asks the product what holds that port, stops that one server by its exact process ids inside the graceful shutdown budget, starts mcc-server detached, and waits for /health to answer. A listener answering is what counts as success — not an install that exited 0. 6.73.0 made this possible behind a -Restart switch, which is still accepted and now does nothing; shipping it opt-in kept the failure it was built to close. On 2026-09-11 two installs finished cleanly fifteen minutes apart with no server running through either of them, because nobody had typed the flag. -NoRestart / --no-restart never stops a running server, and -NoStart / --no-start (or MCC_INSTALL_NO_START=1) stops and starts nothing.

…and it opens the desktop app (7.1.0). When the installer starts mcc-server it also starts mcc-desktop, so an update ends with a working window rather than a working port. Only when the app is installed on this machine — the binary and the install receipt this product writes beside it — only when it is not already running (during an update driven from the app it is running and watching, and a second launch would be handed straight back to it), never on a headless box and never in CI. It is found by executable path, never by a process name. -NoDesktop / --no-desktop (or MCC_INSTALL_NO_DESKTOP=1) turns it off.

Exactly one server, and never anyone else's. The restart means the server bound to the port of the configuration directory the install is for. Every other My Claude Code server — another port, another configuration directory, the instances you have agents waiting on — is listed in the transcript and left running. A port held by something that is not ours is reported and never touched, and so is a holder that could not be identified: “cannot tell” is never “ours”. -NoStart / --no-start (or MCC_INSTALL_NO_START=1) starts nothing at all.

Old servers of this port do not outlive an update or a start (7.72.0). The server the installer starts — and any mcc-server you start yourself — looks for My Claude Code servers that own no listening socket anywhere and whose own record in this configuration folder says they served this port: servers from before 7.69.2 that lost their listener never exit, and kept refreshing stale sign-ins and rewriting agent files for days. Each gets SERVER_GRACEFUL_SHUTDOWN_SECONDS + 4 s to exit by itself; what is left is stopped by exact process id, innermost first, and every outcome is one line in the server log. A server on another port, of another configuration folder, one that listens anywhere, or one whose evidence is unclear is never touched — it is named in a Left alone line. To keep a second server on purpose, give it its own PORT or its own configuration folder. Servers the desktop app starts stop nothing here; its own rescue does this. SERVER_STALE_SERVER_ACTION still governs every other server. The first update to 7.72.0 runs your old installer; the old servers are stopped when the new server starts.

One update at a time, and the receipt keeps every episode. Both update paths take one exclusive lock, update.lock, beside the receipt. A second updater does not queue and does not install — it names the owner, points at the transcript that owner is writing, and exits. A lock whose owner is gone is reclaimed rather than waited on. And nobody truncates progress.json any more: every writer appends, and an episode opens with a marker record naming the writer, so a watcher that looks a minute late still sees what happened. That truncation is how, at 15:04 on 2026-09-11, a hand-run install erased the whole record of the update that had finished two minutes earlier.

On Windows the install is deferred. Windows holds the running interpreter open, so the environment cannot be replaced under a live process. The verified wheel is staged and a background helper installs it once you stop the server. Your working install is untouched until then, so a failed update cannot strand you.

If updating used to appear to do nothing, 6.41.0 is the fix. The helper that waits for the server used to poll for a full hour and then give up without installing anything, and the stop it was waiting for could never finish: a client retrying against a draining server kept handing it new work. Both halves are closed now. New requests are refused with 503 from the moment a stop begins, and the helper waits the graceful shutdown budget — not an hour — then terminates the server it was waiting for by its exact process id, never by name, and installs. The tray's Restart Server follows the same budget, and the installer script waits 600 s rather than six hours.

A deferred update is not a silent one. Since 6.50.0 the background helper appends a line per stage to a progress file under the staging directory in ~/.mcc, and the version panel reads the last complete line back. So a Windows update that is waiting for you to stop the server, or installing, or finished, says which — rather than looking like nothing happened. A half-written final line is skipped rather than treated as the end of the story.

A restart no longer destroys the log that would explain it. Until 6.58.1 every server start emptied logs/server.log, so the one file worth opening after a restart went wrong had been erased by that restart. A start now moves the previous log aside as logs/server.<timestamp>.log, and the same SERVER_LOG_RETAIN_FILES that caps rotations caps these — the newest ten survive, older ones are swept on the next start.

The raw diagnostics settings now write to a file you can open. Until 7.113.4 the raw SSE setting printed to a console the desktop app does not have, and the raw API payload setting logged at a level the default log level drops, so turning either one on produced nothing you could read. Both now write one line per event to logs/raw-diagnostics.log beside server.log, tagged with the request id and rotated and pruned the same way, and the file is created only while one of them is on. It holds prompt text, answer text and tool output in clear text.

An update can no longer race itself. Until 6.58.3 the helper moved every launcher aside before installing, mcc-desktop included — the one the desktop window asks for its status on every pass. The window therefore believed My Claude Code was gone and, by design, ran the installer itself: two installers, one tool directory. Now the helper never moves that launcher, and every line it writes carries its own process id, so the window can ask whether an installer is running rather than guess from a stage name. While one is, it says Updating to X… (installer running, N s) and waits.

You can see everything happening during an update (6.71.0). The installer writes two files in updates/ inside your configuration directory as it goes: progress.json, one JSON line per stage with a timestamp and the seconds since the update started, and install-<stamp>.log, everything uv printed, appended a line at a time as it prints it. The desktop window shows the stage timeline (waiting-for-parent → stopping → installing → verifying → starting or handing-off → done), the elapsed time, and the last fifteen lines of that log, refreshed every tick — including through the seconds in which the environment is genuinely gone. This tab cannot: a page in a browser has no way to read a file on your disk and no server to ask while the server is the thing being replaced, so Update now prints both paths here before the server stops and then counts down. That is the reason to run the desktop app during an update.

An open mcc-claude window no longer costs the install its fast path. Windows refuses to rename a running launcher's .exe, and one refusal used to send the whole update down the slow staged path. The fast path now always runs, and a launcher that truly could not be replaced is kept and named — kept: mcc-claude.exe (in use) — restart it to pick up X. It keeps working either way: the launcher is a stub that runs the interpreter in the tool directory the update just replaced.

A failed update brings the previous version back. Starting the server used to happen only on the success branch, so a failed install left a good previous version on disk with nothing running it. The helper now starts one on both branches and the banner says which happened.

Lock it down

The proxy binds this machine only by default (HOST=127.0.0.1), and the token in a freshly written .env is generated on this machine rather than shipped. To reach the server from another machine, set HOST=0.0.0.0 and give ANTHROPIC_AUTH_TOKEN a secret: mcc-server refuses to start on a non-loopback host with an empty token, because that combination lets anyone who can reach the port spend your provider credits.

Troubleshooting

• mcc-server not found after installing — close and reopen your terminal; the installer extends PATH and an open shell will not see it.
• Claude Code still talks to Anthropic — the settings file wins over shell exports. Check /status; see Point Claude Code here.
• 401 from the proxy — the agent's token does not match this server's ANTHROPIC_AUTH_TOKEN.
• Validation fails with 404 — usually the model id, not the key.
• Desktop test buttons fail — the server must be running; they make real calls.
• The server printed “lost its listening socket” and exited with code 75 — from 7.69.2 a server that can no longer accept new connections says so on its console and in logs/server.log, finishes the requests already in flight within SERVER_GRACEFUL_SHUTDOWN_SECONDS, and exits instead of sitting there unreachable while /health still answers on old connections. The desktop app starts a fresh one by itself; from a terminal, run mcc-server again. On Windows the usual cause, a client resetting a connection while the server is busy, no longer closes the socket at all.
• “Not saved: the settings file was busy … nothing was changed” — from 7.69.7 a save that cannot read or replace the settings file (.env) because another program has it open — a second My Claude Code server, a sync tool, an antivirus scan, an editor — retries for about a third of a second and then stops instead of guessing. The file is exactly as it was, the server keeps its settings and the form keeps your edits: press Save again. Before 7.69.7 that moment could rewrite the file with only the setting being saved.
• The previous copy of your settings — from 7.69.7 every save first keeps the file as it was beside it as .env.previous in the config directory (one copy, replaced by each save, never by an empty or unreadable read). It holds your keys like .env does and is never shown here or logged. To go back one save: stop the server, copy .env.previous over .env, start it again.
• Two configs on Windows — installing under both PowerShell and WSL gives separate .mcc directories. The startup log prints which one is in use.
• Update now finishes, but nothing updates and nothing restarts — fixed in 6.41.0; upgrade once by hand (re-run the install command) and it will not recur. If you carried SERVER_GRACEFUL_SHUTDOWN_SECONDS=300 across from an older install, set it back to 20 on Limits & Resilience — that is now how long every restart waits.
• My data is still in a legacy directory — from 6.65.0 the server moves it for you, once, on its first start: ~/.fcc becomes ~/.mcc by a single atomic rename, nothing is copied, merged or deleted, and a ~/.fcc-migrated.txt note says how to move it back. It refuses — changing nothing — while anything still holds the directory, so quit the desktop app before updating: it holds desktop.lock for its whole lifetime. mcc-migrate still runs the same move by hand.
• The desktop app sits on “Starting the server…” — from 6.66.0 it does not. After three attempts, or DESKTOP_SERVER_START_TIMEOUT × (DESKTOP_SERVER_START_RETRIES + 1) seconds, the window replaces the spinner with the server's exit code, its last lines of output, and two paths: logs/server.log and the app's own logs/desktop-server-start.log. It keeps starting the server every ten seconds regardless, and the page goes away by itself the moment one answers. Installer transcripts land beside them as logs/desktop-install-<timestamp>.log.
• macOS refuses to open the downloaded app — the .dmg is unsigned, so Gatekeeper blocks it. Drag the app into Applications, run xattr -d com.apple.quarantine "/Applications/My Claude Code.app" once, then open it. Installing the server with the one-line command and running mcc-desktop avoids this entirely.
• Web search returns nothing useful — open the attempt detail; it shows exactly what was sent and returned.
• “Request exceeds this model's context window.” The session outgrew the model you routed it to. The message names how many tokens were needed and how many the model holds. A fallback chain carries these through to a roomier model automatically; if you have set FALLBACK_SKIP_KINDS=context_length, it will not.
• “This model rejected the request.” The provider answered 400 without saying the request was malformed — a model it does not serve on that endpoint, a parameter that model pins, a field longer than that host allows. A fallback chain carries these to the next model automatically; the attempt detail names the provider’s own words.

Every document that ships with this install — the README, the full written guide, the architecture notes — is on the Docs tab, rendered from the copy bundled with the version you are running. Each one links out to the latest on GitHub.