feat(mcp): support env-backed HTTP headers for Codex remotes

[dijdzv]

TL;DR

Add env_headers support for remote MCP dependencies and map it to Codex CLI's env_http_headers.

This lets APM generate Codex remote MCP config that references environment variables for HTTP header values, instead of writing secret values into .codex/config.toml. Existing static headers behavior is preserved as Codex http_headers.

Problem

APM already supports static HTTP headers for remote MCP servers, but Codex has a separate runtime-env header surface:

• static values: http_headers
• environment-backed values: env_http_headers

Without an APM manifest field for the second shape, package authors cannot express "write this header name, but read its value from this environment variable at runtime" for Codex remotes.

Approach

Introduce a generic MCP dependency field:

env_headers:
  Authorization: MCP_AUTH_TOKEN

Then map it to Codex config:

[mcp_servers.my-server.env_http_headers]
Authorization = "MCP_AUTH_TOKEN"

Static headers continue to map to Codex http_headers.

Implementation

• MCPDependency now parses, serializes, displays, and validates env_headers.
• MCPIntegrator carries env_headers through self-defined remote generation and overlay merging.
• The Codex adapter emits env_http_headers for remote MCP config.
• Overlay merging is deterministic: repeated installs replace existing entries for the same header name instead of appending duplicates.
• The Codex adapter accepts both list and dict internal shapes and normalizes header names to strings.
• Docs cover the new manifest field and the generated Codex output.

Validation

uv run --extra dev pytest tests/unit/test_mcp_overlays.py tests/unit/test_codex_adapter_phase3.py tests/unit/integration/test_mcp_integrator.py tests/integration/test_mcp_targets_gating_e2e.py -q

Result: 283 passed in 1.63s

uv run --extra dev ruff check src/ tests/

Result: All checks passed!

uv run --extra dev ruff format --check src/ tests/

Result: 1256 files already formatted

Smoke tested this branch's APM against a temporary project with a streamable HTTP MCP entry using env_headers:

uv run --project /home/dd/github/apm apm install --target codex --only mcp --no-audit

The generated Codex config contained:

[mcp_servers.remote-auth-smoke.env_http_headers]
Authorization = "MCP_AUTH_TOKEN"

codex exec loaded the generated config and successfully called the remote MCP tool.

How to test

1. Create a project with a streamable HTTP MCP dependency that declares env_headers.
2. Run apm install --target codex --only mcp.
3. Confirm .codex/config.toml contains env_http_headers.
4. Set the referenced environment variable and run codex exec with that Codex config.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for “env-backed HTTP headers” (env_headers) across the MCP dependency model, integrator overlays, and Codex target output so secrets can be provided at runtime via environment variables instead of being written into config.

Changes:

• Introduces MCPDependency.env_headers with validation and (de)serialization support.
• Propagates env_headers through MCPIntegrator remote info and overlay merging.
• Maps remote env_headers to Codex env_http_headers, with unit + E2E tests and documentation updates.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/test_mcp_overlays.py	Adds unit coverage for env_headers parsing/serialization, validation, and overlay behavior.
tests/unit/test_codex_adapter_phase3.py	Verifies Codex adapter maps remote env_headers into env_http_headers (list + dict shapes).
tests/integration/test_mcp_targets_gating_e2e.py	Adds E2E coverage ensuring Codex writes env_http_headers into .codex/config.toml.
src/apm_cli/models/dependency/mcp.py	Adds env_headers field, validation for CRLF + env var name format, and dict roundtripping.
src/apm_cli/integration/mcp_integrator.py	Emits env_headers into remotes and merges overlays into cached server info.
src/apm_cli/adapters/client/codex.py	Converts remote env_headers to Codex env_http_headers.
docs/src/content/docs/reference/manifest-schema.md	Documents env_headers schema and expected Codex output.
docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md	Adds producer-facing docs + examples for env_headers.
docs/src/content/docs/consumer/install-mcp-servers.md	Adds consumer install docs describing native env-header binding usage.

[dijdzv]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.