@finest-ai/mcp

The Finest MCP server. Connect it to your coding agent and it can ask where this codebase's model spend goes and whether one exact existing route's current signed-policy configuration still has route-bound verification and optimizer authority.

Tools

| Tool | What it answers | | --- | --- | | finest_overspend | Estimated monthly model spend attributed by route, largest first, with the optimizer's projected saving and the constraint blocking any route that has none. | | finest_routes | The jobs this codebase asks AI to do: key, job name, task class, status, estimated monthly cost, whether the route can be switched at all. | | finest_verify | Returns the console handoff where a signed-in admin can choose a frozen safe corpus, cap real-provider spend, and request optimizer-recommended verification. It never queues spend itself. | | finest_cheapest_proven | For one exact route, the active signed-policy configuration only when matching immutable verification and a fresh cost-optimizer recomputation still support it. Task class alone never selects a model. | | finest_install | Returns the executable install document (the same content as /llms.txt, both doors: the 2-minute Door 1 key swap with its fail-open shim, and the Door 2 in-process wrap) plus the console URL where a signed-in human issues a Door 1 gateway key. No key material ever passes through MCP, and the tool itself installs and changes nothing. | | finest_approve_flip | Returns the human approval screen. It never records approval or changes traffic. |

Every tool returns a structured result and one human sentence: the structure is for the agent, the sentence is for the person reading over its shoulder.

Configuration

@finest-ai/mcp is not published and no npm coordinate is approved yet. Do not run the registry command. Build this checkout, then point the MCP client at the explicit local artifact (replace the absolute path below):

pnpm --filter @finest-ai/mcp build

{
  "mcpServers": {
    "finest": {
      "command": "node",
      "args": ["/absolute/path/to/finest/packages/mcp/dist/server.js"],
      "env": {
        "FINEST_API_KEY": "fnst_...",       // workspace key, from the console
        "FINEST_API_URL": "https://api.finest.so",       // optional
        "FINEST_CONSOLE_URL": "https://finest.so"        // optional handoff origin
      }
    }
  }
}

Why finest_cheapest_proven is exact-route only

An LLM asked "what's the cheapest model for classification?" will always produce a confident answer. A task class is not enough evidence: two classification routes can have different prompts, schemas, traffic, constraints, provider bindings and price authority. Call finest_routes first, then pass the exact routeId. A genuinely new job has no route-bound proof yet, so the tool returns a tuple-free unavailable state instead of laundering a benchmark into source.

The tool returns a tuple only when the exact route has one active, unexpired signed policy, matching immutable verification over both exact tuples, and a fresh cost-optimizer recomputation still selects that active tuple with positive fully loaded projected savings. The result carries policy, verification, corpus, price-epoch and timestamp sources. It never falls back to a generic benchmark, fleet average or remembered model, and it never tells an agent to hard-code the tuple: the application keeps its incumbent fallback and the SDK applies the signed policy.

Why paid verification and approval are handoffs

A flip changes which model serves live customer traffic. Everything else in Finest exists to make that action safe, and the brief's Invariant 12 says a human is the sole approver.

There is a sharper reason as well: an MCP server acts on tool arguments an LLM produced, and that LLM has been reading the repository, the issue tracker and web pages. Text in any of those can try to instruct it. A production model switch must never be reachable from a string a model read somewhere.

Verification also spends real provider tokens. A string supplied to an agent is not authority for money or traffic, so neither tool attempts a mutation. Each returns an exact console URL; the signed-in admin chooses the corpus, ceiling, evidence and canary there. No special MCP token can bypass that boundary.

Failure behaviour

No tool ever throws. An unreachable control plane returns { ok: false, error: { code: 'unreachable', hint: ... } } with isError set, and the sentence reminds the reader that their application is unaffected. The Door 2 shim is not a cloud proxy: its model calls continue going straight from the application to the provider on the developer's own key. Door 1 traffic is served through the Finest gateway by explicit choice, and its client shim fails open — gateway trouble replays the request directly to the provider on the developer's own key.

Key material never appears in a result, an error, a URL or a log. The workspace key travels in an Authorization header and nowhere else.

Development

pnpm --filter @finest-ai/mcp exec tsc --noEmit
pnpm --filter @finest-ai/mcp test     # drives the server through a real MCP client
pnpm --filter @finest-ai/mcp run build

The test suite connects a real Client over InMemoryTransport and fakes only the network, so declared output schemas are enforced by the SDK on the way out — a tool returning a shape it did not declare fails the suite rather than reaching an editor.

Apache-2.0.