Closes #2280 InsecureTokenEndpointError appeared nowhere in our source, so it fell through to the generic auth-failure path and rendered a "Re-authentication required" banner with a Re-authenticate button. That button can never work: the SDK's assertSecureTokenEndpoint runs inside executeTokenRequest, the error does not extend OAuthError, and auth() special-cases it to rethrow rather than start a fresh /authorize redirect. Clicking re-ran the same flow to the same refusal, under the raw SDK message, which names the three exempt host literals and nothing actionable. A terminal configuration error was being presented as a retryable auth error. Not specific to *.localhost: it fires for any endpoint outside the SDK's exemption — host.docker.internal (#1911), a LAN hostname, a reverse-proxy name, a mistyped scheme. It is now recognized (core/auth/insecureTokenEndpoint.ts, mirroring issuerBinding.ts's brand-plus-name classifier and walking cause / data.cause, since era negotiation and the transport wrappers bury the rejection) and surfaced as the configuration error it is, naming the endpoint and both ways out, with no action affordance. Six paths reach the refusal and all six classify it — the connect handshake, authenticate() during connect, the satisfied-challenge connect retry, the post-redirect callback, the command/background path, the deferred tab-visible resume (which re-armed on every focus, an unbounded loop on a terminal error), and the banner action. They share one wrapper so a seventh cannot omit the banner clear, and every clear is scoped to its own serverId: these paths are asynchronous, so a late continuation for one server must not erase a banner another raised in the meantime. Adds oauth-insecure-token-endpoint-http.json to reproduce it, whose issuer is http://localhost.:8091 — the root-anchored spelling every resolver sends to loopback but which is none of the SDK's exempt literals. transport.strictPort keeps that fixture honest, since its port is hard-coded inside the issuer. Making such an endpoint work has to land in the SDK (typescript-sdk#2591); this changes the reporting, not the outcome. Split out of #2282, where it was tangled with the *.localhost origin work for #1944 — a separate question the reporter is still clarifying. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018MvNbmAtQuWhDvzi4yXDju Signed-off-by: cliffhall <cliff@futurescale.com>
4.3 KiB
| name | description | disable-model-invocation |
|---|---|---|
| test-servers | Run a composable MCP test server by hand — pick the showcase config for a feature or bug, build it, and connect with the right protocol era. Use when a change, a PR or a smoke test needs a real server to exercise it; when reproducing a reported bug by hand; when choosing which fixture or protocol era to run; when a fixture keeps serving stale code after an edit; or when the config or preset you need does not exist yet. | false |
Running a test server
test-servers/ provides composable MCP servers so tests and manual checks
exercise a real server over a real transport instead of mocks. A server is
assembled from presets (fixture factories in
test-servers/src/preset-registry.ts) and configured declaratively with a JSON
file under test-servers/configs/.
The full catalogue of showcase configs — one per feature, each with what to click
and what the broken build did — is
docs/test-servers.md. This skill is how to
run one.
Build first
The servers are spawned as real subprocesses, so the build output must exist:
cd clients/web && npm run test-servers:build # tsc -p test-servers → test-servers/build/
Scripts reach this through scripts/ensure-test-servers.mjs, which builds
unconditionally (once per process per repo root).
⚠️ Unconditional emit is not a clean. A deleted source file leaves its
stale .js behind, existence checks pass against it, and anything still
importing that module silently runs the old code — reported not as staleness but
as a product failure in whatever was being tested. So after deleting or renaming
a source file:
rm -rf test-servers/build
The .tsbuildinfo is pinned inside build/ so that clean actually invalidates
the cache.
Run one
Two processes: the test server, then the Inspector.
# 1. The server, from the repo root, with the config you picked:
node test-servers/build/server-composable.js --config test-servers/configs/<name>.json
# 2. The Inspector, in another terminal (needs a built launcher — `npm run build`):
node clients/launcher/build/index.js --web
Then add the server in the Inspector using the URL the first process announced.
Two mechanics that bite:
- The server announces its URL on stderr, not stdout (
console.errorinserver-composable.ts). Watching stdout alone looks like a server that never started. - The bound port is not necessarily the config's.
createTestServerHttpresolves throughfindAvailablePort(), which walks upward when the configured port is taken — so read the announced URL rather than assuming.
Pick the right protocol era
Each config in docs/test-servers.md says
which era to connect with. The default is legacy; configs setting
transport.modern need Protocol Era = Modern. Connecting with the wrong era
usually looks like a missing capability rather than an error.
Common starting points
| Want to see | Config |
|---|---|
| An MCP App in the Apps tab | mcp-app-http.json (legacy) |
| An App-rendered elicitation | app-elicitation-http.json (legacy) |
Mcp-* headers + the modern error taxonomy |
modern-network-http.json |
A tool result's structuredContent section |
structured-output-http.json (legacy) |
| RFC 6570 resource-template expansion | rfc6570-templates-http.json |
| OAuth token revocation on clear | oauth-revocation-http.json (legacy) |
| A token endpoint the SDK refuses (SEP-2207) | oauth-insecure-token-endpoint-http.json (legacy) |
| Cancelling a call mid-flight | cancellation-modern-http.json (modern) |
Adding a config or preset
- Presets live in
test-servers/src/preset-registry.ts; configs intest-servers/configs/*.json. - A new showcase config gets a row in
docs/test-servers.mdsaying what to do and what the broken build did — the "what it looked like broken" half is what makes the fixture reproducible later. - ⚠️ An
outputSchemaoverride must ride a tool that returns structured content. A conforming client validates the result against the advertised schema, so an override on a preset returning none makes every call fail with "declares an output schema but returned no structured content".