v0.0.17 improves recovery from temporary startup failures and adds optional request diagnostics. It also updates the bundled cloudflared companion to 2026.10.2.
Startup recovery and readiness
- OAuth startup discovery now retries timeouts, HTTP 429/5xx responses, and malformed successful metadata responses with exponential backoff capped at 30 seconds. Temporary failures fetching advertised authorization-server metadata also retry, so startup does not publish a partial target catalog.
- Unscoped polling and poll scopes that include
harpoonwait until startup discovery and target registration finish. A replica whose catalog is unavailable leaves queued work for healthy replicas./readyzstays non-ready while that catalog is pending or failed. - HTTP MCP initialization probes now retry HTTP 429/5xx responses. With the default startup configuration, those retries continue in the background with backoff capped at 30 seconds. The optional
--mcp.startup-wait-timeoutstill bounds its startup wait and additionally retains retries for connection-refused and missing Unix-socket errors. - These retries apply to startup discovery and initialization only. They do not replay tunneled MCP commands or application requests.
Upgrade behavior: deployments that previously began polling despite failed OAuth discovery may now remain unready until discovery recovers. A permanent startup-catalog configuration failure requires correcting the configuration and restarting the client. If an explicitly configured MCP startup-wait deadline expires, readiness remains non-ready until restart; OAuth discovery may still continue, and successful catalog registration independently controls polling eligibility. A configured startup-wait timeout does not bypass the catalog requirement. Explicit poll scopes excluding harpoon do not wait for the Harpoon catalog. Plain MCP servers with no OAuth metadata can still complete startup with an empty catalog; permanent configuration and trust errors remain errors. Custom embedded integrations using a legacy publication-only registration bus retain their existing polling behavior. /healthz remains the process-liveness endpoint.
Optional diagnostics
- Add local JSONL tracing with
--tracing.enabledand--tracing.file. Tracing is disabled by default. It records dispatch, MCP forwarding, and response-upload spans only when a compatible service supplies a valid sampled trace parent. Records contain span identifiers, timing, and status, without request payloads, credentials, or headers. Use a new trace file for each run. Optional MCP metadata trace forwarding remains separately controlled by--mcp.forward-trace-context. - Add
--forward-request-idto select automatic forwarding of the original inboundX-Request-Idtomcp,harpoon, and/or eligible queuedoauthrequests, or disable it withnone. The default remainsmcp. Existing caller-owned headers and origin/redirect restrictions are preserved; startup OAuth discovery does not inherit an inbound request ID. - Extend MCP health details to recognize
server/discoverfor the self-contained2026-07-28protocol. Stdio health observations distinguish modern discovery from legacy initialization and retain bounded protocol, capability, and tool-list information. Reading health endpoints does not initiate protocol requests.
Compatibility and packaging
- Accept namespaced tunnel IDs in addition to existing IDs. Preserve the complete ID returned by the service. Use namespaced IDs only with a service that supports them, and retain legacy IDs when older clients must connect.
- Improve the managed Cloudflare startup error when runtime credentials return HTTP 404, with guidance to check managed provisioning or disable managed mode.
- Fix Codex app-server startup/shutdown races and clean up failed initialization before retrying.
- Update cloudflared from 2026.8.2 to 2026.10.2 in the full client and the runtime-with-cloudflared distribution, with refreshed package metadata and SBOMs.
Local tracing and expanded request-ID forwarding are optional. Existing configurations retain their defaults. Remove newly added tracing options before downgrading to a version that does not support them.