Skip to content

fix(app): offer Claude Code and Codex setup commands next to the CLI installer - #3708

Open
jordan-simonovski wants to merge 3 commits into
mainfrom
jordansimonovski/mcp-manual-setup-commands
Open

jordan-simonovski wants to merge 3 commits into
mainfrom
jordansimonovski/mcp-manual-setup-commands

Conversation

@jordan-simonovski

@jordan-simonovski jordan-simonovski commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Brings back the Claude Code and Codex CLI tabs in the MCP setup panel, next to npx @hyperdx/cli mcp install, so connecting an agent doesn't require installing our CLI. #3622 removed them.

  • The commands are the same as before feat(cli): add hdx mcp install to connect AI agents without pasting a key #3622: the key is inlined in the command and masked in the panel until you click "Reveal key". Having the key in the command, and so in shell history, is accepted.
  • The Codex tab notes that Codex reads CLICKSTACK_ACCESS_KEY each time it starts, so it needs to be set in your shell profile, not only in the shell where you ran the command.
  • The organisation API keys description is now just "Keys owned by the team."

Screenshots or video

Before After
before-mcp after-claude

How to reproduce

Starting point: yarn dev (both sections need the API), register any account.

On main:

  1. Open Team settings, then API & Agents.
  2. Under "Connect your AI Agents", the manual setup tabs are Cursor, VS Code, OpenCode and Other.

On this branch:

  1. Open Team settings, then API & Agents.
  2. Claude Code is the default tab and shows claude mcp add clickstack ... with the key masked.
  3. Select Codex CLI: it shows the export and codex mcp add lines plus the shell profile note.

How to test on Vercel preview

N/A: local mode has no signed-in user, so the MCP panel and organisation keys section don't render.

References

…installer

The commands read the access key from a hidden prompt, so it stays out of
shell history and agent chats. Codex also gets a note that it needs the
variable set wherever it runs.

Refs HDX-6080
@jordan-simonovski
jordan-simonovski requested a review from a team as a code owner November 18, 2026 07:52
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: b8ae566

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

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 18, 2026 8:04am UTC
hyperdx-storybook Ready Ready Preview Nov 18, 2026 8:04am UTC

Request Review

@github-actions github-actions Bot added the review/tier-2 Low risk — AI review + quick human skim label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

🔵 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: 3
  • Production lines changed: 136 (+ 111 in test files, excluded from tier calculation)
  • Branch: jordansimonovski/mcp-manual-setup-commands
  • Author: jordan-simonovski

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

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 106 in total (1.13%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.


function buildClaudeCommand(deployment: DeploymentShape): string {
return `${READ_KEY} && claude mcp add --scope user --transport http ${SERVER_NAME} ${buildUrl(deployment)} --header "Authorization: Bearer $${ACCESS_KEY_ENV_VAR}"`;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 P1 — The Claude Code command fails when a clickstack entry already exists, such as after running the CLI installer or when changing the key

claude mcp add will not overwrite an existing server; the CLI removes the entry first for this reason (packages/cli/src/mcp/install.ts:341-347, and the comment at install.ts:8 says a reinstall should replace a hand-added entry). Remove the old entry inside the same && line, e.g. read -rs K && { claude mcp remove --scope user clickstack >/dev/null 2>&1; claude mcp add ...; }.

Nothing blocks merge automatically, but a maintainer will expect this fixed if it is a real defect in code this PR changes. If it is about surrounding code, reply and say so instead of patching. Do not widen the PR. How to respond

label={SHELL_COMMAND_LABEL}
snippet={snippets.codexCli}
/>
<Text size="xs" c="dimmed">

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — The Codex note tells users to set the variable in their shell profile but gives no way to do it

After the command runs, the key exists only in the current shell, so Codex breaks in every new terminal. Users get no snippet for the profile step and will likely paste the key as plain text into .zshrc. Either give a copyable profile line that reads the key from a secret store or file, or point Codex users to the CLI installer, which writes http_headers into a 0600 ~/.codex/config.toml (packages/cli/src/mcp/install.ts:254-276).

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 P0/P1 in code this PR adds or changes: fix before asking for review.
  • 🟡 P2 in code this PR changes: your call. Fix if small, otherwise reply.
  • 🔵 P3 is collapsed at the bottom: nobody needs to act on it before merge.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    priority. Reply with one sentence; if it is P0, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

5 finding(s): 🔴 0 P0/P1 · 🟡 4 P2 · 🔵 1 P3

4 posted as inline comment(s) on the changed lines. 1 P3 folded at the bottom.

🔵 1 P3 — no action needed before merge
  • 🔵 P3 packages/app/src/components/ClickStackOnboarding/__tests__/installSnippets.test.ts:18 — Tests require the key to be inlined in the copied commands, which locks in the shell-history leak → The exact-match expectations for claudeCode (Bearer k_abcdef123456) and codexCli (export ...="k_abcdef123456"), and the shell-escape tests, would fail if the snippets were fixed to use read -rs. Change them to assert that the copied command does NOT contain DEPLOYMENT.accessKey and that it does contain read -rs CLICKSTACK_ACCESS_KEY. Then a regression back to inlining the key fails. The masking test only checks the on-screen text, not the copied value.

Priority comes from a separate grading pass over the finished review. P3 is folded here instead of posted inline. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

The diff re-adds Claude Code and Codex CLI tabs to the MCP install panel. The snippet builders are pure and well-tested, the AgentHost union keeps its exhaustive-switch guard (id satisfies never), and the key stays masked and reveal-gated in the UI. No correctness, auth, or data-loss defect is introduced on any path reachable with today's server-generated access keys. The findings below are latent, future-only hardening items.

✅ No critical issues found.

🟡 P2 — recommended

  • packages/app/src/components/ClickStackOnboarding/installSnippets.ts:159 — the Claude/Codex snippets embed the shell-escaped key, but RevealSnippet masks by literal-substring match on the raw accessKey, so a key containing ", \, $, or backtick would render in cleartext in the masked view while the escaping exists precisely for those characters.
    • Fix: derive the redaction secret from the same escaped string that lands in the snippet (or pass an explicit [real, redacted] pair) so the masked and embedded forms always match.
    • security-reviewer, correctness-reviewer
🔵 P3 nitpicks (2)
  • packages/app/src/components/ClickStackOnboarding/installSnippets.ts:127 — shellEscape does not neutralize !, which triggers bash history expansion inside double quotes in interactive shells; the "defensive against future key formats" guarantee is therefore incomplete.
    • Fix: single-quote the interpolated value, or narrow the escape helper's documented scope to the characters it actually covers.
  • packages/app/src/components/ClickStackOnboarding/installSnippets.ts:162 — the MCP URL is interpolated unquoted into both the Claude (--transport http ${url}) and Codex (--url ${url}) commands; safe today because it derives from the browser origin, but quoting removes the latent injection surface at zero cost.
    • Fix: wrap the URL in the existing shellQuoteValue helper when building both one-liners.

Reviewers (10): correctness, security, adversarial, kieran-typescript, testing, maintainability, project-standards, agent-native, learnings-researcher, previous-comments.

Testing gaps:

  • No rendered-UI test asserts the key is masked in the multi-line Codex snippet, nor that masking holds for a key containing shell metacharacters — such a test (raw and escaped key both absent from the masked render) would catch the P2 escape/redact mismatch above.

Note (intentional tradeoff, not graded): once pasted and run, the Claude --header "…Bearer <key>" and Codex export CLICKSTACK_ACCESS_KEY="<key>" lines place the user's own access key into shell history. This is a deliberate product decision — the credential is the user's own, masked and reveal-gated in the UI, and never leaked by the diff itself; the CLI installer remains the history-free alternative.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 474 passed • 1 skipped • 1008s

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

Tests ran across 4 shards in parallel.

View full report →

The PM is fine with the access key appearing in the command, so this drops
the read -rs prompt and goes back to the pre-#3622 snippets.
function buildClaudeOneLiner(deployment: DeploymentShape): string {
const url = buildUrl(deployment);
const headers = buildHeaders(deployment);
return `claude mcp add ${SERVER_NAME} --transport http ${url} ${headerArgs(headers)}`;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — Claude Code command puts the raw access key in the command line, so it ends up in shell history

The copied command contains --header "Authorization: Bearer <real key>". Running it saves the key to shell history. That is the reason #3622 removed this tab, and it goes against the PR description, which says the commands begin with read -rs CLICKSTACK_ACCESS_KEY. Emit read -rs CLICKSTACK_ACCESS_KEY && claude mcp add ... --header "Authorization: Bearer $CLICKSTACK_ACCESS_KEY" as MCP.md:56-63 documents, and don't put the key in the snippet at all.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has come up in discussion and has been deemed ok

function buildCodexOneLiner(deployment: DeploymentShape): string {
const url = buildUrl(deployment);
const token = deployment.accessKey || '<accessKey>';
const exportLine = `export ${CODEX_TOKEN_ENV_VAR}=${shellQuoteValue(token)}`;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — Codex snippet writes export CLICKSTACK_ACCESS_KEY="<real key>", which also lands in shell history

Using --bearer-token-env-var keeps the key out of codex mcp add. The export line on the line before it still puts the literal key into history, and its doc comment calls that line "self-contained". Use read -rs CLICKSTACK_ACCESS_KEY && export CLICKSTACK_ACCESS_KEY && codex mcp add ... on one && line, as in MCP.md:71 and the PR description. Pasting it as two lines lets read swallow the next line in shells without bracketed paste.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

function buildClaudeOneLiner(deployment: DeploymentShape): string {
const url = buildUrl(deployment);
const headers = buildHeaders(deployment);
return `claude mcp add ${SERVER_NAME} --transport http ${url} ${headerArgs(headers)}`;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — Claude Code command omits --scope user, so the server is added only for the current directory

Without --scope, claude mcp add uses local scope, which applies only to the directory the user ran it in. MCP.md:61 and the CLI installer (packages/cli/src/mcp/install.ts:343-351) both use --scope user. Add --scope user so the UI, the docs and the CLI agree.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

* `\`, or backtick would otherwise turn a copy-paste install into a
* shell-injection vector.
*/
function shellEscape(value: string): string {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2 — shellEscape and its quoting helpers exist only to inline the key into shell commands

Once the snippets read the key with read -rs and reference $CLICKSTACK_ACCESS_KEY, no secret is interpolated into shell text. At that point shellEscape, shellQuoteValue, shellQuoteHeader and headerArgs can be deleted, along with their escape tests.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — b8ae5664 Deployed Nov 18, 2026 by vercel[bot]
Preview – hyperdx-storybook — b8ae5664 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-2 Low risk — AI review + quick human skim

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant