fix(mcp): update Codex CLI install snippet to current mcp add syntax

[brandon-pereira]

The Codex CLI install snippet in the "Connect your AI assistant" panel (and MCP.md) was stale: it used --transport http ... --header "Authorization: Bearer ...", which the current Codex CLI rejects outright with error: unexpected argument '--transport' found. Copy-pasting it never worked.

The current Codex CLI supplies bearer auth for a Streamable HTTP server via --bearer-token-env-var <ENV> rather than an inline header, so Codex now emits a self-contained two-line snippet — export CLICKSTACK_ACCESS_KEY="<key>" followed by codex mcp add clickstack --url <url>/mcp --bearer-token-env-var CLICKSTACK_ACCESS_KEY. Claude Code keeps its existing --transport/--header command; the two hosts no longer share a builder. MCP.md gains a matching Codex CLI section with a note about why the old flags fail.

Scoped to the OSS bearer-token path only — the ClickHouse Cloud x-service-id / http_headers variant is intentionally out of scope here.

Closes DOC-914.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jul 21, 2026 5:43pm
hyperdx-storybook	Ready	Preview, Comment	Jul 21, 2026 5:43pm

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 1
• Production lines changed: 74 (+ 39 in test files, excluded from tier calculation)
• Branch: brandon/brandon-codex-docs-improvements
• Author: brandon-pereira

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[greptile-apps]

Greptile Summary

This PR updates the Codex CLI MCP install instructions to use the current bearer-token environment variable flow.

• Adds a patch changeset for the app snippet update.
• Adds a Codex CLI section to MCP.md.
• Splits Claude and Codex install snippet generation.
• Updates Codex snippet tests for the new two-line command.
• Updates the Team Settings test to match the new Codex command text.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/app/src/components/ClickStackOnboarding/installSnippets.ts	Updates Codex snippet generation while keeping Claude on its existing command shape.
packages/app/src/components/ClickStackOnboarding/tests/installSnippets.test.ts	Covers the new Codex command format, placeholder behavior, and token escaping.
packages/app/src/components/TeamSettings/tests/McpServerSection.test.tsx	Updates the Codex tab assertion for the new command syntax.
MCP.md	Documents the Codex CLI bearer-token environment variable setup.
.changeset/codex-mcp-bearer-token-syntax.md	Adds a patch changeset for the app-facing snippet change.

_{Reviews (2): Last reviewed commit: "fix(mcp): update Codex CLI install snipp..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: c9adf53

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/app	Patch
@hyperdx/api	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

E2E Test Results

✅ All tests passed • 243 passed • 1 skipped • 1049s

Status	Count
✅ Passed	243
❌ Failed	0
⚠️ Flaky	0
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

MCP Eval Results — ✅ PASS

Advisory only (Milestone 1 CI skeleton) — this check does not block merges.

Pipeline ran end to end: 1/1 run(s) reached a final answer across 1 scenario(s).

Scenario	Runs completed	Combined score
latency-spike	1/1	77%

Batch: 2026-07-21T17-46-14-274Z · Commit: a205483 · View workflow run →

[github-actions]

Deep Review

✅ No critical issues found.

This is a well-scoped docs/snippet fix. The new Codex builder emits syntactically correct, self-contained output; MCP.md was updated in lockstep and is byte-consistent with buildCodexOneLiner; the shell-escaping guard is complete for the double-quoted context (", \, $, `); and a changeset (@hyperdx/app patch) is present and correctly formed. The remaining items are recommendations only.

🟡 P2 -- recommended

• packages/app/src/components/TeamSettings/__tests__/McpServerSection.test.tsx:117 -- the updated Codex test regex /codex mcp add clickstack --url .*--bearer-token-env-var/s asserts only the add line, never the new export CLICKSTACK_ACCESS_KEY="..." line nor the coupling between the exported name and the --bearer-token-env-var argument, so dropping the export line or renaming CODEX_TOKEN_ENV_VAR on one side would leave the test green.
  • Fix: Add an assertion that the export CLICKSTACK_ACCESS_KEY="k_test" line renders and extend the add-line match to include the trailing --bearer-token-env-var CLICKSTACK_ACCESS_KEY so the export-name/flag-name coupling is verified.

🔵 P3 nitpicks (2)

• MCP.md:55 -- the emitted export sets the token only in the current shell, but --bearer-token-env-var makes the Codex CLI resolve the token from the environment at each connect, so a later Codex run in a fresh shell (where the export is gone) can silently fail MCP auth.

  • Fix: Add a one-line note in the Codex CLI section advising the reader to persist CLICKSTACK_ACCESS_KEY (e.g. in their shell profile) if they want the server to keep authenticating across sessions.

• packages/app/src/components/ClickStackOnboarding/installSnippets.ts:127 -- the shellEscape/shellQuoteValue path newly exercised by the Codex export line is only reachable with a token containing ", \, $, or `, and the sole render test uses k_test, so the injection-hardening branch is never covered.

  • Fix: Add a builder/render test with a token like a"b$c\d asserting the export line escapes to export CLICKSTACK_ACCESS_KEY="a\"b\$c\\d".
  • _{testing, security}

---

Reviewers (5): correctness, security, testing, maintainability, project-standards.

Testing gaps:

• No assertion pins buildCodexOneLiner output against the documented snippet in MCP.md, so future divergence between the panel and the docs would go undetected.
• The shell-metacharacter escaping branch in installSnippets.ts remains uncovered.