Repository navigation
feat: Allow fixed request headers in server conformance tests #453
Description
Activity
I'd like to implement a focused, secret-safe version of this capability.
Rather than making a literal bearer token in repeatable
--headerarguments the primary path, I propose an environment-backed or--headers-fileinput parsed once into the server run options, then applied at the shared HTTP transport boundary. The first PR would cover:- propagation to every request made by the server suite, including initialization, tool/resource requests, SSE/reconnect traffic, and cleanup requests;
- a documented precedence rule where a scenario-specific authorization header overrides the fixed default;
- redaction in normal and verbose output (names may be reported, values never are);
- tests for propagation, precedence, invalid input, and log/argument secrecy, plus a pass/fail run against at least one real SDK server.
Do maintainers prefer a JSON headers file, a single environment variable containing JSON, or both with one canonical precedence order? Once that input shape is confirmed, I can submit a small issue-linked PR without changing the scenario model.
AI assistance disclosure: I am using Codex to assist with code-path analysis and implementation planning. I will review the patch and run/report the repository build, tests, and real-SDK conformance evidence myself.
Any implementation that allows us to specify header(s) would be helpful for running conformance against secured systems.
Currently having to use a hacky proxy just to add a header.
Adding a second motivation, since this is the blocker on four checks in the MCP Events suite (#504) and would retire a workaround there too.
Credential hygiene is the argument above. The coverage argument is that some requirements are about the principal, so a runner that cannot vary its credential cannot reach them at all:
sep-9999-subscribe-auth-required—events/subscribeandevents/unsubscribeMUST be called with an authenticated principal, and a server MUST reject a call without one with-32012 Forbidden. Grading it needs the runner to drop its own auth for one probe, which is the mirror image of adding a header.sep-9999-error-forbidden— the-32012row from the error table. Same prerequisite.sep-9999-authz-subscribe-timeand-delivery-time-reverify— authorization checked at subscribe and re-checked at delivery. These need two principals with different permissions.sep-9999-verification-cached-per-principal-url— verification is cached per(principal, url), so one principal's handshake must not waive the challenge for another. Unreachable with one credential.
A fixture control can substitute for a second principal in a narrow way, and mcpkit has built one for the cross-tenant row (
events_conformance_subscribe_as, which registers a subscription on another principal's behalf). It cannot substitute for the absence of a credential, because the harness has no way to make an unauthenticated call. That half only a runner option can supply.Second, smaller thing: without
--headera server behind OAuth cannot be scored at all. Scoringmetronome-mcp.fly.dev— the Events reference implementation, written by the design sketch's author — currently needs a local proxy in front of it purely to inject a bearer token. That proxy is the only reason two implementations can be compared, and running the suite against a second implementation is what found the defect in the specification that PR 7 is now fixing. This option retires it.Happy to do the implementation if the shape is settled. Repeatable
--header 'Name: value'onservercovers every case above except dropping auth, which would want something explicit like--no-authon one probe or a scenario-level opt-out rather than a header.
Problem
Server conformance tests accept the target only through
--url. Servers that require a fixed bearer token must put it in the query string, which exposes the credential in the runner's process arguments and in output that prints the target URL.For example:
conformance server --url 'http://127.0.0.1:3001/?token=SECRET'Environment variables keep the token out of the parent shell command, but the runner still receives the expanded URL as an argument.
Requested capability
Allow callers to add fixed HTTP request headers to server conformance traffic without placing their values in the URL. An interface such as repeatable
--header 'Authorization: Bearer ...'arguments or a header file/environment option would solve this.Requirements:
This was found while running MCP
2026-07-28and2025-11-25server conformance tests against an authenticated endpoint in apify/apify-mcp-server#1173.