Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/mcp-manual-claude-codex.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@hyperdx/app': patch
---

Bring back the Claude Code and Codex CLI commands in the MCP setup panel, next to the `hdx mcp install` command, so connecting an agent no longer needs another CLI installed.
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@ import { useMemo, useState } from 'react';
import { Group, SegmentedControl, Stack, Text } from '@mantine/core';
import {
IconBraces,
IconBrandOpenai,
IconBrandVisualStudio,
IconCode,
IconRobot,
IconTerminal2,
} from '@tabler/icons-react';

import { CopySnippet } from './CopySnippet';
Expand All @@ -13,23 +15,30 @@ import {
buildAllSnippets,
buildCliInstallCommand,
type BuiltSnippets,
CODEX_TOKEN_ENV_VAR,
type DeploymentShape,
} from './installSnippets';

// ChatGPT is intentionally absent: no native MCP yet, and bridges are a
// user-side decision better tracked in docs than in this UI. Claude Code
// and Codex are configured through shell commands, which would put the key
// in shell history, so the CLI installer above covers them instead.
type AgentHost = 'cursor' | 'vscode-copilot' | 'opencode' | 'other';
// user-side decision better tracked in docs than in this UI.
type AgentHost =
| 'claude-code'
| 'cursor'
| 'vscode-copilot'
| 'codex-cli'
| 'opencode'
| 'other';

interface HostChoice {
id: AgentHost;
label: string;
}

const CHOICES: HostChoice[] = [
{ id: 'claude-code', label: 'Claude Code' },
{ id: 'cursor', label: 'Cursor' },
{ id: 'vscode-copilot', label: 'VS Code' },
{ id: 'codex-cli', label: 'Codex CLI' },
{ id: 'opencode', label: 'OpenCode' },
{ id: 'other', label: 'Other' },
];
Expand All @@ -50,7 +59,7 @@ interface McpInstallPanelProps {
* block) for the chosen host. The access key is masked in every snippet.
*/
export default function McpInstallPanel({ deployment }: McpInstallPanelProps) {
const [host, setHost] = useState<AgentHost>('cursor');
const [host, setHost] = useState<AgentHost>('claude-code');

const snippets = useMemo(() => buildAllSnippets(deployment), [deployment]);

Expand Down Expand Up @@ -96,10 +105,14 @@ export default function McpInstallPanel({ deployment }: McpInstallPanelProps) {

function HostIcon({ id }: { id: AgentHost }) {
switch (id) {
case 'claude-code':
return <IconTerminal2 size={16} />;
case 'cursor':
return <IconCode size={16} />;
case 'vscode-copilot':
return <IconBrandVisualStudio size={16} />;
case 'codex-cli':
return <IconBrandOpenai size={16} />;
case 'opencode':
return <IconBraces size={16} />;
case 'other':
Expand All @@ -120,6 +133,15 @@ interface HostInstallProps {

function HostInstall({ host, snippets, accessKey }: HostInstallProps) {
switch (host) {
case 'claude-code':
return (
<CopySnippet
label="Paste in your terminal:"
snippet={snippets.claudeCode}
accessKey={accessKey}
/>
);

case 'cursor':
return (
<DeeplinkInstall
Expand Down Expand Up @@ -147,6 +169,21 @@ function HostInstall({ host, snippets, accessKey }: HostInstallProps) {
/>
);

case 'codex-cli':
return (
<Stack gap="xs">
<CopySnippet
label="Paste in your terminal:"
snippet={snippets.codexCli}
accessKey={accessKey}
/>
<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

Codex reads {CODEX_TOKEN_ENV_VAR} each time it starts, so also set
it in your shell profile.
</Text>
</Stack>
);

case 'opencode':
return (
<CopySnippet
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,16 @@ function codeText(): string {
}

describe('McpInstallPanel secret masking', () => {
it('masks the access key in the default (Claude Code) command snippet', () => {
renderPanel();

const text = codeText();
// The raw key must never appear in the rendered snippet...
expect(text).not.toContain(ACCESS_KEY);
// ...but the masked stand-in (visible prefix + dots) should.
expect(text).toContain(defaultRedact(ACCESS_KEY));
});

it('masks the access key in the JSON fallback (Other) snippet', async () => {
const user = userEvent.setup();
renderPanel();
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import {
buildAllSnippets,
CODEX_TOKEN_ENV_VAR,
type DeploymentShape,
SERVER_NAME,
} from '@/components/ClickStackOnboarding/installSnippets';
Expand All @@ -9,6 +10,34 @@ const DEPLOYMENT: DeploymentShape = {
accessKey: 'k_abcdef123456',
};

describe('buildAllSnippets > Claude Code', () => {
it('emits the documented Claude Code MCP install one-liner', () => {
const { claudeCode } = buildAllSnippets(DEPLOYMENT);

expect(claudeCode).toBe(
`claude mcp add ${SERVER_NAME} --transport http https://hyperdx.example.com/api/mcp --header "Authorization: Bearer k_abcdef123456"`,
);
});
});

describe('buildAllSnippets > Codex CLI', () => {
it('emits the current OpenAI Codex CLI mcp add command with a bearer-token env var', () => {
const { codexCli } = buildAllSnippets(DEPLOYMENT);

expect(codexCli).toBe(
`export ${CODEX_TOKEN_ENV_VAR}="k_abcdef123456"\n` +
`codex mcp add ${SERVER_NAME} --url https://hyperdx.example.com/api/mcp --bearer-token-env-var ${CODEX_TOKEN_ENV_VAR}`,
);
});

it('does NOT use the deprecated --transport or --header flags', () => {
const { codexCli } = buildAllSnippets(DEPLOYMENT);

expect(codexCli).not.toContain('--transport');
expect(codexCli).not.toContain('--header');
});
});

describe('buildAllSnippets > Cursor', () => {
it('emits a cursor:// URL with a URL-safe base64-encoded config that round-trips', () => {
const { cursor } = buildAllSnippets(DEPLOYMENT);
Expand Down Expand Up @@ -129,13 +158,56 @@ describe('buildAllSnippets > JSON block', () => {
});
});

describe('buildAllSnippets > placeholder fallbacks', () => {
it('falls back to <accessKey> in the snippet when the key is empty', () => {
const { claudeCode } = buildAllSnippets({ ...DEPLOYMENT, accessKey: '' });

expect(claudeCode).toContain('Bearer <accessKey>');
});

it('falls back to <accessKey> in the Codex export when the key is empty', () => {
const { codexCli } = buildAllSnippets({ ...DEPLOYMENT, accessKey: '' });

expect(codexCli).toContain(`export ${CODEX_TOKEN_ENV_VAR}="<accessKey>"`);
});

it('escapes shell metacharacters in header values', () => {
// Today's access keys are UUIDv4 with no metacharacters; the
// escape is defensive against future formats that allow `"`,
// `$`, `\`, or backtick. Any of those would otherwise turn a
// copy-paste install into a shell-injection vector.
const { claudeCode } = buildAllSnippets({
...DEPLOYMENT,
accessKey: 'k"$`\\suffix',
});

expect(claudeCode).toContain('Bearer k\\"\\$\\`\\\\suffix"');
});

it('escapes shell metacharacters in the Codex export value', () => {
// The bearer token lands on the right-hand side of an `export`,
// so the same shell-injection defense applies to the Codex
// snippet's quoted value.
const { codexCli } = buildAllSnippets({
...DEPLOYMENT,
accessKey: 'k"$`\\suffix',
});

expect(codexCli).toContain(
'export ' + CODEX_TOKEN_ENV_VAR + '="k\\"\\$\\`\\\\suffix"',
);
});
});

describe('buildAllSnippets > host coverage', () => {
it('returns a populated string for every supported host', () => {
const all = buildAllSnippets(DEPLOYMENT);

expect(all).toMatchObject({
claudeCode: expect.stringContaining(`claude mcp add ${SERVER_NAME}`),
cursor: expect.stringContaining('cursor://'),
vscode: expect.stringContaining('vscode:mcp/install'),
codexCli: expect.stringContaining(`codex mcp add ${SERVER_NAME}`),
openCode: expect.stringContaining(`"${SERVER_NAME}"`),
jsonBlock: expect.stringContaining(`"${SERVER_NAME}"`),
});
Expand All @@ -144,6 +216,8 @@ describe('buildAllSnippets > host coverage', () => {
it('keys the JSON block on the same fixed server name in every output', () => {
const all = buildAllSnippets(DEPLOYMENT);

expect(all.claudeCode).toContain(SERVER_NAME);
expect(all.codexCli).toContain(SERVER_NAME);
expect(all.cursor).toContain(`name=${SERVER_NAME}`);
expect(all.vscode).toContain(SERVER_NAME);
expect(all.openCode).toContain(`"${SERVER_NAME}"`);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
// Per-host snippet builders for the "Connect your AI assistant"
// section. Each builder takes a `DeploymentShape` (URL + access
// key) and returns the install primitive for one host: a deep link
// or a JSON config block. Nothing here emits a shell command with the
// key in it, since that lands in shell history; `hdx mcp install`
// covers the CLI-configured hosts instead.
// key) and returns the install primitive for one host: a CLI
// one-liner, a deep link, or a JSON config block.
//
// Pure functions only. Component-level state (host picker) lives
// in `McpInstallPanel.tsx`. Keeping the builders here makes unit
Expand All @@ -22,6 +20,17 @@
*/
export const SERVER_NAME = 'clickstack';

/**
* Environment variable the Codex CLI snippet reads the bearer token
* from. The current `codex mcp add` command has no `--header` flag;
* for a Streamable HTTP server with bearer auth it accepts
* `--bearer-token-env-var <NAME>` and reads the token from that env
* var at connect time (see https://developers.openai.com/codex/mcp).
* We emit an `export` line for the same name so the copy-paste is
* self-contained.
*/
export const CODEX_TOKEN_ENV_VAR = 'CLICKSTACK_ACCESS_KEY';

export interface DeploymentShape {
/** Origin used to build the MCP URL, e.g. `https://example.com/api`. */
apiUrl: string;
Expand All @@ -30,10 +39,14 @@ export interface DeploymentShape {
}

export interface BuiltSnippets {
/** Claude Code CLI one-liner. */
claudeCode: string;
/** Cursor `cursor://` deep link. */
cursor: string;
/** VS Code + Copilot `vscode:mcp/install` deep link. */
vscode: string;
/** OpenAI Codex CLI one-liner. */
codexCli: string;
/** OpenCode JSON config under an `mcp` block (uses `type: "remote"`). */
openCode: string;
/** Canonical `mcpServers` JSON block for any other host. */
Expand Down Expand Up @@ -104,6 +117,69 @@ function buildUrl(deployment: DeploymentShape): string {
return `${base}/mcp`;
}

/**
* Escape a value for safe inclusion inside a double-quoted shell
* argument. Defensive: today's `accessKey` is a UUIDv4 with no
* shell metacharacters, but a future format that permits `"`, `$`,
* `\`, 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

return value.replace(/(["\\$`])/g, '\\$1');
}

/**
* Wrap a value in double quotes with the metacharacters escaped,
* for use as a standalone shell argument (e.g. the right-hand side
* of an `export`).
*/
function shellQuoteValue(value: string): string {
return `"${shellEscape(value)}"`;
}

/**
* Quote and escape a header value for safe inclusion inside a
* double-quoted `--header "Name: value"` shell argument.
*/
function shellQuoteHeader(name: string, value: string): string {
return `--header "${name}: ${shellEscape(value)}"`;
}

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


function headerArgs(headers: Record<string, string>): string {
return Object.entries(headers)
.map(([key, value]) => shellQuoteHeader(key, value))
.join(' ');
}

/**
* Claude Code `mcp add` one-liner: `claude mcp add <name>
* --transport http <url> --header "..."`. Claude passes the bearer
* token inline as an `Authorization` header.
*/
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

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

}

/**
* OpenAI Codex CLI `mcp add` command. Unlike Claude Code, the
* current Codex CLI (see https://developers.openai.com/codex/mcp)
* does not accept `--transport` or `--header`; its Streamable HTTP
* form is `codex mcp add <name> --url <url>` and bearer auth is
* supplied via `--bearer-token-env-var <ENV_VAR>`, which reads the
* token from the named environment variable rather than embedding
* it in the command. We prepend an `export` for that variable so
* the snippet is a self-contained copy-paste.
*/
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

const addLine = `codex mcp add ${SERVER_NAME} --url ${url} --bearer-token-env-var ${CODEX_TOKEN_ENV_VAR}`;
return `${exportLine}\n${addLine}`;
}

/**
* Cursor `cursor://` deep link. Documented Cursor MCP install
* scheme: name in the query string, config as base64-encoded JSON.
Expand Down Expand Up @@ -202,8 +278,10 @@ export function buildCliInstallCommand(deployment: DeploymentShape): string {
*/
export function buildAllSnippets(deployment: DeploymentShape): BuiltSnippets {
return {
claudeCode: buildClaudeOneLiner(deployment),
cursor: buildCursorDeeplink(deployment),
vscode: buildVSCodeDeeplink(deployment),
codexCli: buildCodexOneLiner(deployment),
openCode: buildOpenCodeJsonBlock(deployment),
jsonBlock: buildMcpJsonBlock(deployment),
};
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,7 @@ export default function OrgApiKeysSection() {
<Box>
<Text size="md">Organization API keys</Text>
<Text size="sm" c="dimmed">
Keys owned by the team. They keep working when the person who
created them leaves.
Keys owned by the team.
</Text>
</Box>
<Button variant="primary" onClick={() => setIsCreateOpen(true)}>
Expand Down
Loading
Loading