[lorem-dev]

Summary

In locksmith mcp run --url (proxy mode), vault-resolved HTTP headers are now sent only after the remote MCP server responds 401/403. Servers that authorise the MCP initialize handshake without auth (a common pattern - capability negotiation usually does not require credentials) no longer trigger a vault prompt at all for that connection.

This builds on the lazy-fetch + session-refresh work already on develop and goes one step further: even the first MCP request from the AI client (initialize) no longer pays the auth cost up front.

Behaviour

Configured headers split into two groups based on the template syntax:

• Static headers (no { token, e.g. User-Agent: MyClient): sent on every request from the very first one.
• Templated headers (contain {key:...} or {vault:... path:...}): resolved and attached only after the server signals it needs them.

State machine:

unauthenticated  ──first request without auth──▶  200 → stay unauthenticated
                                            └▶  401/403 → resolve auth → retry once → switch to
                                                                                       ↓
                                                                                  authenticated (sticky)
authenticated    ──every subsequent request carries the cached auth headers──▶  forever

StreamableHTTP and SSETransport both retry on 401/403. AutoTransport delegates to its inner transport; the 404/405-driven fallback path is orthogonal to auth-retry.

What changed

Commit	Description
b99ca82	refactor(mcp): plumb HeaderResolver through Transport (no behaviour change)
8fecc77	feat(mcp): Streamable HTTP transport retries with auth on 401/403
7000673	feat(mcp): SSE transport retries with auth on 401/403
1d6d64c	feat(mcp): defer templated proxy headers to first 401/403 (proxy.go wiring + E2E tests + runLoop shutdown hardening)
a82fd42	docs: describe lazy auth-header deferral for proxy mode (README + configuration.md)
ff4da22	docs(architecture): describe auth-header deferral and SSE GET limit
c09e163	docs(changelog): record lazy auth-header deferral in proxy mode

Side fix in 1d6d64c: runLoop now closes the transport explicitly on stdin EOF / send error and drains pending server messages. Real StreamableHTTP transports never close msgCh on their own, so the prior loop would deadlock when stdin EOFs against a non-mock transport. The new end-to-end tests in proxy_test.go exposed it.

Known limitations

• SSE GET stream not reopened with auth after late resolve. If a server accepts the long-lived GET /sse without credentials but then demands them on POST /messages, the existing GET is left as-is and notifications on it may stop arriving. Workaround: configure such servers with --transport http (Streamable HTTP has no long-lived GET).
• Local mode unchanged. Env vars are baked into the child at exec; lazy auth is fundamentally not possible without changing the MCP server contract. The existing lazy-fetch (resolve on first stdin line) is as deep as local mode can go.
• JSON-RPC-level auth errors are not detected. Servers that return HTTP 200 with a JSON-RPC error payload signalling auth must surface 401/403 instead.

Configuration

No new flags, no new config fields. The deferral kicks in automatically for any header whose template contains a { token. Plain static headers behave as before.

Test plan

• make lint clean (golangci-lint v2 strict ruleset).
• make test-race clean across the workspace.
• make test-coverage shows >= 90% per package.
• New tests cover: 200 path, missing resolver, 401 retry, 403 retry, sticky auth, retry-after-resolve still fails, SSE Connect retry, SSE Send retry, proxy E2E (templated deferred, static always-sent, no-templates no-resolver).
• Manual: configure an MCP server in ~/.config/locksmith/config.yaml with a templated Authorization header against a real backend; observe that no vault prompt fires on locksmith mcp run --server <name> startup, only when the server returns 401/403.
• Manual: confirm a server that always requires auth still works (pays one extra HTTP round-trip on the first message).