Docs / API & MCP

API & MCP

Firstpass exposes a small HTTP surface — both inbound dialects, deferred feedback, capabilities, health, and Prometheus metrics — plus an MCP stdio server so agents can inspect the router as native tools.

Six HTTP endpoints total: two inbound dialects (POST /v1/messages and POST /v1/chat/completions) that are drop-in replacements for direct provider calls, plus feedback, capabilities, health, and Prometheus metrics. Separately, firstpass mcp is a stdio MCP server for self-audit — it reads the router's own trace store so agents can inspect routing decisions, verify receipts, and rehearse policy changes. It is not an MCP proxy on the routed data plane.

How to read this page The first four sections cover the HTTP surface you point your client at. The MCP server section covers the audit-and-inspection tool — a distinct surface that is easy to confuse with the inbound proxy. Each section has a TL;DR up top and a one-line recap at the bottom.

inbound dialects — Anthropic + OpenAI, drop-in

POST

/v1/feedback closes the calibration loop

stdio

firstpass mcp — self-audit, not a data-plane proxy

MCP tools for inspection, rehearsal, and audit

HTTP endpoints#

All six endpoints at a glance. The two inbound endpoints are protocol-preserving drop-ins — change the base URL, keep the rest of your request body exactly as it is. Feedback, capabilities, health, and metrics are separate paths.

Method & path	Purpose
`POST /v1/messages`	Anthropic-dialect inbound. Runs the cascade, returns a normal response.
`POST /v1/chat/completions`	OpenAI-dialect inbound. Same cascade, OpenAI wire format.
`POST /v1/feedback`	Report a deferred outcome for a past request — drives adaptive calibration.
`GET /v1/capabilities`	What this instance supports — providers, gates, modes.
`GET /healthz`	Liveness / readiness.
`GET /metrics`	Prometheus exposition.

Six endpoints: two inbound proxies, one feedback intake, one capability query, and the standard health + metrics pair.

Chat & messages#

Both inbound endpoints are drop-in replacements for direct provider calls. Send the exact same request body you were already sending; Firstpass rewrites only the model field to whichever rung is selected and forwards everything else verbatim — tools, cache_control, streaming, all of it.

Drop-in for both dialects

Both inbound endpoints are drop-in: keep your existing request body, point it at Firstpass, and it routes, gates, and serves. Override the mode per request with a header (precedence).

bash

curl http://localhost:8080/v1/messages \
  -H "content-type: application/json" \
  -H "x-firstpass-mode: quality" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Write a function to merge two sorted lists."}]
  }'

Key idea The forwarding is verbatim except for model. Firstpass reads model, tools count, and image blocks to decide the rung; it then rewrites model to the selected rung's model string and forwards the entire request body unchanged. Tool schemas, cache_control blocks, and all other fields pass through byte-for-byte. If you set cache_control, provider-side prompt caching still works — Firstpass doesn't interfere with it.

Under the hood SSE streaming is buffered to the gate before the response is served, then re-emitted as SSE. From the client's perspective the response format is identical to what the provider would send — you see the same streaming chunks. The buffering is what lets the gate run on the complete output before it is committed as the served answer.

Both inbound endpoints are drop-in: change only the base URL; the request body is forwarded verbatim with only the model field rewritten to the selected rung.

Feedback#

When a request's true outcome becomes known after the fact — CI green, reviewer approved, user rejected — report it via POST /v1/feedback. This is what drives adaptive calibration: without outcome signals the serve threshold is static; with them it self-tunes to your real workload.

Closing the calibration loop

When a request's true outcome becomes known later — CI went green, a reviewer approved, a user rejected — report it. This is what makes the serve threshold self-tune.

bash

curl http://localhost:8080/v1/feedback \
  -H "content-type: application/json" \
  -d '{ "request_id": "req_9f2c8a41", "outcome": "correct" }'

Key idea The gate alone gives you a proxy quality signal; feedback gives you the real one. The more outcome signals you send, the tighter the conformal calibration gets. High-volume pipelines with reliable automated outcomes (CI pass/fail, unit tests, structured evaluators) benefit most — the threshold tracks your actual workload rather than a generic prior.

POST /v1/feedback ties a deferred real-world outcome to a past request_id and lets the serve threshold self-tune toward your workload.

Capabilities & health#

GET /v1/capabilities returns what this instance supports — configured providers, available gates, and enabled modes. GET /healthz returns 200 when the instance is ready to serve.

bash

curl http://localhost:8080/v1/capabilities   # providers, gates, modes
curl http://localhost:8080/healthz           # 200 when ready

Under the hood Capabilities reflects the resolved configuration — what is actually active at runtime, not just what is configured. Use it to confirm that the providers and gates you expect are wired up before running a workload. Healthz is a simple liveness probe; wire it to your load-balancer or orchestrator readiness check.

/v1/capabilities shows resolved runtime config; /healthz is the liveness probe — returns 200 when ready.

Metrics#

GET /metrics is standard Prometheus exposition. The two key gauges make the served-failure guarantee observable: the current serve threshold and the measured served-failure rate from reported outcomes. Alert on the latter.

GET /metrics is Prometheus exposition. The two gauges that make the guarantee observable:

firstpass_serve_threshold

Current serve threshold; moves with adaptive conformal.

firstpass_realized_served_failure

Measured served-failure rate from reported outcomes — alert on this.

Common mistake Watching only firstpass_serve_threshold and assuming it means the guarantee is holding. The threshold is the target; firstpass_realized_served_failure is the measured outcome. They diverge when the gate is mis-calibrated or feedback volume is low. Alert on the realized rate, not the threshold.

GET /metrics is Prometheus; alert on firstpass_realized_served_failure — that is the actual served-failure rate from outcomes you reported, not just the target threshold.

Request headers#

One header controls routing on a per-request basis: x-firstpass-mode overrides the mode for this request only and takes highest precedence over policy and config defaults.

Header	Effect
`x-firstpass-mode`	Override the routing mode for this request (highest precedence).

Key idea The mode header is useful for testing and pinning: set x-firstpass-mode: observe on a request to run it as a byte-passthrough without touching routing logic, or quality to force the strong rung for a specific call. See routing precedence for the full override order. Mode headers are not forwarded to the upstream provider — they are consumed by Firstpass and stripped before the call goes out.

x-firstpass-mode overrides routing for one request and takes highest precedence — useful for testing, pinning, or bypassing the cascade entirely with observe.

MCP server tools#

firstpass mcp is a stdio MCP server that reads the router's own trace store — inspection, audit, explanation, and off-policy rehearsal as native agent tools. It is a self-audit surface, not an MCP proxy on the routed data plane. Your agent's MCP tool traffic passes through the HTTP inbound endpoints byte-for-byte; firstpass mcp is a separate server you wire up to inspect what the router did.

Audit server, not data-plane proxy

Key idea — audit vs data-plane firstpass mcp and the Firstpass inbound proxy are two separate things. When your agent issues a model call that includes MCP-backed tools, that call arrives at POST /v1/messages or POST /v1/chat/completions as ordinary HTTP. Firstpass forwards the tools array verbatim — it does not speak MCP, intercept MCP connections, or manage MCP servers on your behalf. The firstpass mcp stdio server is a completely separate process you optionally wire up so that an agent can query the router's trace store, verify receipt integrity, and rehearse policy changes as native tool calls — it reads what the router already recorded, after the fact.

firstpass mcp is a stdio MCP server. It gives an agent first-class access to the router's state and controls — inspection, rehearsal, and audit, no HTTP glue:

Tool reference

Tool	Does
`list_traces`	Recent routing decisions.
`get_trace`	The full decision for one request.
`get_savings`	Net savings, gate cost included.
`get_evals`	Gate outcomes and served-failure aggregates.
`explain_route`	Why a request routed as it did.
`rehearse_policy`	Off-policy evaluation of a routing change (IPS/SNIPS/DR).
`verify_receipts`	Re-derive the hash chain and report integrity.
`list_modes`	Available modes and their resolved knobs.
`submit_feedback`	Report a deferred outcome.

Under the hood Each routing decision is stored as a hash-chained Trace — every trace includes a prev_hash linking it to the one before, forming a tamper-evident chain over the full history. verify_receipts re-derives this chain end to end and surfaces any break. rehearse_policy runs off-policy evaluation on historical traces using importance-weighted estimators (IPS/SNIPS/DR) so you can estimate what a proposed routing change would have cost and what its served-failure rate would have been, before you deploy it. See Receipts & audit for the full trace schema.

firstpass mcp is a self-audit stdio server over the trace store — nine tools for inspection, audit, and off-policy rehearsal. It is not on the routed data plane; inbound HTTP traffic flows through the proxy endpoints, not through this server.