@hue-run/sdk 0.10.0 → 0.11.1

package/dist/cli/mcp.d.ts

@@ -1,7 +1,9 @@
 /**
- * `hue mcp install`: writes or prints the coding-agent configuration for Hue's MCP server. Every
- * shape mirrors the snippets Hue shows in Settings and references the `HUE_MCP_KEY` environment
- * variable (or a VS Code password input); a key value is never written.
+ * `hue mcp install`: writes or prints the coding-agent configuration for Hue's MCP server. The
+ * shapes are those of Hue's published connection guide (https://docs.hue.run/agents/mcp-server),
+ * kept as a separate copy here. Key configurations reference the `HUE_MCP_KEY` environment
+ * variable (or a VS Code password input); sign-in configurations hold no credential. A key value
+ * is never written.
  */
 /** Streams, environment and working directory for {@link runMcpCommand}; tests inject these. */
 export interface McpCommandIo {
@@ -12,10 +14,30 @@ export interface McpCommandIo {
     cwd?: string;
 }
 export declare const DEFAULT_MCP_URL = "https://mcp.hue.run/mcp";
-/** Prompt to paste into the agent after installation; identical to the one Hue shows. */
-export declare const MCP_VERIFY_PROMPT = "Use the Hue MCP: call get_project_context, then show my 5 most recent error traces with links.";
-export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|cursor|codex|vscode|windsurf|gemini>\n                       [--url URL] [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. The configuration references the\nHUE_MCP_KEY environment variable; a key value is never written.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --url URL       Hue MCP endpoint (default https://mcp.hue.run/mcp)\n  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs\n                  `claude mcp add --scope user`\n  --dry-run       Print the resulting file content or command without writing or running\n  --print         Print the configuration snippet only\n  -h, --help      Show this help\n\nFiles: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the\ncurrent directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the\nsnippet for its user configuration file.";
-/** Canonical Hue client snippets; the JSON values are also the merge entries for config files. */
+/**
+ * Prompt to paste into the agent after installation. `list_projects` answers for every credential:
+ * a project key or earlier connection returns its one project, and an organization connection
+ * lists them, after which each call takes `project_id`. It reads what needs attention and falls
+ * back to recent traces, so a project without errors still proves the read path.
+ */
+export declare const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.";
+/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and the `observe` profile. */
+export declare const MCP_TOOLSETS: readonly ["all", "observe", "project", "traces", "evals", "environments", "intents", "docs"];
+/**
+ * The header form of `?toolsets=`. Only the sign-in Codex TOML uses it, as Hue's guide does, to
+ * keep that URL bare; every other configuration carries the selection in its URL.
+ */
+export declare const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
+export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>\n                       [--auth key|oauth] [--read-only] [--toolsets NAMES] [--url URL]\n                       [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. A key configuration references the\nHUE_MCP_KEY environment variable; a key value is never written. A sign-in configuration holds\nonly the URL: the client opens Hue in a browser, where you approve access to the projects of\none organization.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --auth MODE     key: reference HUE_MCP_KEY (the default, except for conductor)\n                  oauth: URL only, sign in with Hue in the client (claude-code, codex and\n                  conductor; the default for conductor)\n  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A\n                  sign-in connection has Read and write access; use a Read key for read-only\n  --toolsets NAMES\n                  Tools to list, comma-separated: all, observe (production reads),\n                  project, traces, evals, environments, intents or docs, added to the\n                  URL as ?toolsets=. Defaults: all for claude-code, codex and conductor,\n                  which search their own tools; observe for cursor. Without a selection\n                  Hue lists the production reads and search_hue_tools, which reaches\n                  every other tool\n  --url URL       Hue MCP endpoint (default https://mcp.hue.run/mcp)\n  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs\n                  `claude mcp add --scope user`\n  --dry-run       Print the resulting file content or commands without writing or running\n  --print         Print the configuration snippet only\n  -h, --help      Show this help\n\nFiles: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the\ncurrent directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the\nsnippet for its user configuration file. conductor registers the server for its Claude Code\n(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.";
+/**
+ * A URL as a POSIX shell word for printed commands: `?` is a zsh glob and `&` ends a command, so a
+ * URL with a query (such as `?read_only=true`) is single-quoted. Executed commands pass argv.
+ */
+export declare function shellWord(value: string): string;
+/**
+ * Canonical Hue client snippets for a key configuration; the JSON values are also the merge
+ * entries for config files.
+ */
 export declare function renderMcpSnippets(url: string): {
     claudeCodeServer: {
         type: string;
@@ -67,6 +89,43 @@ export declare function renderMcpSnippets(url: string): {
         display: string;
     };
 };
+/**
+ * Sign-in snippets: the server URL and nothing secret. The client discovers Hue's OAuth metadata
+ * from it and sends it, query included, on every request; the token's resource ignores the query,
+ * so `?toolsets=` selects tools here as it does for a key.
+ */
+export declare function renderMcpSignInSnippets(url: string): {
+    claudeCodeServer: {
+        type: string;
+        url: string;
+    };
+    claudeCodeProjectJson: string;
+    claudeCodeCli: {
+        args: string[];
+        display: string;
+    };
+    codexCli: {
+        args: string[];
+        display: string;
+    };
+    codexToml: string;
+};
+/**
+ * Parses a comma-separated `--toolsets` value into Hue's canonical form, or returns an error.
+ * Unknown names are refused: Hue ignores them and would list its default, hiding a typo.
+ */
+export declare function parseToolsets(value: string): {
+    toolsets: string;
+} | {
+    error: string;
+};
+/**
+ * `?toolsets=` lists only the selected tools; commas stay readable. Without a selection the
+ * parameter is removed, so the connection lists Hue's default.
+ */
+export declare function toolsetsMcpUrl(url: string, toolsets: string | undefined): string;
+/** `?read_only=true` hides and rejects Hue's write tools for any key. */
+export declare function readOnlyMcpUrl(url: string): string;
 /** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */
 export declare function parseMcpUrl(value: string): string | null;
 /**

package/dist/cli/mcp.js

@@ -10,37 +10,110 @@ const SERVER_NAME = "hue";
 const ENV_VAR = "HUE_MCP_KEY";
 const INPUT_ID = `${SERVER_NAME}-mcp-key`;
 const MAX_CONFIG_BYTES = 1024 * 1024;
-/** Prompt to paste into the agent after installation; identical to the one Hue shows. */
-export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call get_project_context, then show my 5 most recent error traces with links.";
-const CLIENT_IDS = ["claude-code", "cursor", "codex", "vscode", "windsurf", "gemini"];
+/**
+ * Prompt to paste into the agent after installation. `list_projects` answers for every credential:
+ * a project key or earlier connection returns its one project, and an organization connection
+ * lists them, after which each call takes `project_id`. It reads what needs attention and falls
+ * back to recent traces, so a project without errors still proves the read path.
+ */
+export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show that project's traces from the last 24 hours that need attention or have errors, with links; if there are none, show its 5 most recent traces. For an organization connection, pass the project's id as project_id on each call after list_projects.";
+const CLIENT_IDS = [
+    "claude-code",
+    "codex",
+    "conductor",
+    "cursor",
+    "vscode",
+    "windsurf",
+    "gemini",
+];
 const CLIENT_LABELS = {
     "claude-code": "Claude Code",
-    cursor: "Cursor",
     codex: "Codex",
+    conductor: "Conductor",
+    cursor: "Cursor",
     vscode: "VS Code",
     windsurf: "Windsurf",
     gemini: "Gemini CLI",
 };
-export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|cursor|codex|vscode|windsurf|gemini>
-                       [--url URL] [--scope project|user] [--dry-run] [--print]
+/** Clients whose browser sign-in with Hue works against the deployed server. */
+const OAUTH_CLIENTS = ["claude-code", "codex", "conductor"];
+/** Toolset names Hue's MCP server accepts: `all`, its catalog groups and the `observe` profile. */
+export const MCP_TOOLSETS = [
+    "all",
+    "observe",
+    "project",
+    "traces",
+    "evals",
+    "environments",
+    "intents",
+    "docs",
+];
+/**
+ * The header form of `?toolsets=`. Only the sign-in Codex TOML uses it, as Hue's guide does, to
+ * keep that URL bare; every other configuration carries the selection in its URL.
+ */
+export const TOOLSETS_HEADER = "X-Hue-MCP-Toolsets";
+/**
+ * Toolsets a client's configuration selects unless `--toolsets` says otherwise. Claude Code,
+ * Codex and Conductor's agents defer MCP tools behind their own tool search, so listing every tool
+ * costs them little. Cursor caps the tools it loads, so it names the production reads. The other
+ * clients list Hue's default: the production reads, and `search_hue_tools` with its executors,
+ * which reach every other tool.
+ */
+const DEFAULT_TOOLSETS = {
+    "claude-code": "all",
+    codex: "all",
+    conductor: "all",
+    cursor: "observe",
+};
+/** Codex runs a server's tool calls one at a time without it; each Hue call is independent. */
+const CODEX_PARALLEL = "supports_parallel_tool_calls = true";
+export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|codex|conductor|cursor|vscode|windsurf|gemini>
+                       [--auth key|oauth] [--read-only] [--toolsets NAMES] [--url URL]
+                       [--scope project|user] [--dry-run] [--print]
 
-Configure a coding agent to use the Hue MCP server. The configuration references the
-${ENV_VAR} environment variable; a key value is never written.
+Configure a coding agent to use the Hue MCP server. A key configuration references the
+${ENV_VAR} environment variable; a key value is never written. A sign-in configuration holds
+only the URL: the client opens Hue in a browser, where you approve access to the projects of
+one organization.
 
 Options:
   --client NAME   Coding agent to configure (required)
+  --auth MODE     key: reference ${ENV_VAR} (the default, except for conductor)
+                  oauth: URL only, sign in with Hue in the client (claude-code, codex and
+                  conductor; the default for conductor)
+  --read-only     key only: add ?read_only=true to the URL so write tools are hidden. A
+                  sign-in connection has Read and write access; use a Read key for read-only
+  --toolsets NAMES
+                  Tools to list, comma-separated: all, observe (production reads),
+                  project, traces, evals, environments, intents or docs, added to the
+                  URL as ?toolsets=. Defaults: all for claude-code, codex and conductor,
+                  which search their own tools; observe for cursor. Without a selection
+                  Hue lists the production reads and search_hue_tools, which reaches
+                  every other tool
   --url URL       Hue MCP endpoint (default ${DEFAULT_MCP_URL})
   --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs
                   \`claude mcp add --scope user\`
-  --dry-run       Print the resulting file content or command without writing or running
+  --dry-run       Print the resulting file content or commands without writing or running
   --print         Print the configuration snippet only
   -h, --help      Show this help
 
 Files: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the
 current directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the
-snippet for its user configuration file.`;
+snippet for its user configuration file. conductor registers the server for its Claude Code
+(user scope) and Codex agents with their CLIs, printing the command for a CLI not on PATH.`;
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
-/** Canonical Hue client snippets; the JSON values are also the merge entries for config files. */
+/**
+ * A URL as a POSIX shell word for printed commands: `?` is a zsh glob and `&` ends a command, so a
+ * URL with a query (such as `?read_only=true`) is single-quoted. Executed commands pass argv.
+ */
+export function shellWord(value) {
+    return /^[\w@%+=:,./-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * Canonical Hue client snippets for a key configuration; the JSON values are also the merge
+ * entries for config files.
+ */
 export function renderMcpSnippets(url) {
     const bearer = (reference) => `Bearer ${reference}`;
     const claudeCodeServer = {
@@ -57,7 +130,7 @@ export function renderMcpSnippets(url) {
     const vscodeInput = {
         type: "promptString",
         id: INPUT_ID,
-        description: "Hue coding-agent key",
+        description: "Hue Read or Read and write API key",
         password: true,
     };
     const windsurfServer = {
@@ -80,15 +153,15 @@ export function renderMcpSnippets(url) {
                 "--header",
                 `Authorization: Bearer \${${ENV_VAR}}`,
             ],
-            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${url} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
         },
         cursorServer,
         cursorJson: json({ mcpServers: { [SERVER_NAME]: cursorServer } }),
         codexCli: {
             args: ["mcp", "add", SERVER_NAME, "--url", url, "--bearer-token-env-var", ENV_VAR],
-            display: `codex mcp add ${SERVER_NAME} --url ${url} --bearer-token-env-var ${ENV_VAR}`,
+            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)} --bearer-token-env-var ${ENV_VAR}`,
         },
-        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n`,
+        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n${CODEX_PARALLEL}\n`,
         vscodeServer,
         vscodeInput,
         vscodeJson: json({ servers: { [SERVER_NAME]: vscodeServer }, inputs: [vscodeInput] }),
@@ -98,19 +171,78 @@ export function renderMcpSnippets(url) {
             args: [
                 "mcp",
                 "add",
+                "--scope",
+                "user",
                 "--transport",
                 "http",
                 SERVER_NAME,
                 url,
-                "-H",
-                `Authorization: Bearer $${ENV_VAR}`,
+                "--header",
+                `Authorization: Bearer \${${ENV_VAR}}`,
             ],
             // Single quotes keep the reference literal when a person runs this in a shell where the
-            // key is exported; Gemini CLI resolves $HUE_MCP_KEY from its settings at runtime.
-            display: `gemini mcp add --transport http ${SERVER_NAME} ${url} -H 'Authorization: Bearer $${ENV_VAR}'`,
+            // key is exported; Gemini CLI expands ${HUE_MCP_KEY} from its settings at connection time.
+            display: `gemini mcp add --scope user --transport http ${SERVER_NAME} ${shellWord(url)} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+        },
+    };
+}
+/**
+ * Sign-in snippets: the server URL and nothing secret. The client discovers Hue's OAuth metadata
+ * from it and sends it, query included, on every request; the token's resource ignores the query,
+ * so `?toolsets=` selects tools here as it does for a key.
+ */
+export function renderMcpSignInSnippets(url) {
+    const toolsets = new URL(url).searchParams.get("toolsets");
+    const claudeCodeServer = { type: "http", url };
+    return {
+        claudeCodeServer,
+        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeCli: {
+            args: ["mcp", "add", "--transport", "http", "--scope", "user", SERVER_NAME, url],
+            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${shellWord(url)}`,
+        },
+        codexCli: {
+            args: ["mcp", "add", SERVER_NAME, "--url", url],
+            display: `codex mcp add ${SERVER_NAME} --url ${shellWord(url)}`,
         },
+        // The header form of the same selection, for a TOML entry that keeps its URL bare.
+        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${toolsetsMcpUrl(url, undefined)}"\n${toolsets ? `http_headers = { "${TOOLSETS_HEADER}" = "${toolsets}" }\n` : ""}${CODEX_PARALLEL}\n`,
     };
 }
+/**
+ * Parses a comma-separated `--toolsets` value into Hue's canonical form, or returns an error.
+ * Unknown names are refused: Hue ignores them and would list its default, hiding a typo.
+ */
+export function parseToolsets(value) {
+    const names = [...new Set(value.split(",").map((name) => name.trim()))];
+    if (names.some((name) => !name))
+        return { error: "--toolsets takes comma-separated names, such as observe or traces,docs." };
+    const unknown = names.filter((name) => !MCP_TOOLSETS.includes(name));
+    if (unknown.length)
+        return {
+            error: `Unknown toolset${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Choose from ${MCP_TOOLSETS.join(", ")}.`,
+        };
+    return { toolsets: names.join(",") };
+}
+/**
+ * `?toolsets=` lists only the selected tools; commas stay readable. Without a selection the
+ * parameter is removed, so the connection lists Hue's default.
+ */
+export function toolsetsMcpUrl(url, toolsets) {
+    const parsed = new URL(url);
+    parsed.searchParams.delete("toolsets");
+    if (!toolsets)
+        return parsed.href;
+    const query = parsed.search.slice(1);
+    parsed.search = `${query ? `${query}&` : ""}toolsets=${toolsets}`;
+    return parsed.href;
+}
+/** `?read_only=true` hides and rejects Hue's write tools for any key. */
+export function readOnlyMcpUrl(url) {
+    const parsed = new URL(url);
+    parsed.searchParams.set("read_only", "true");
+    return parsed.href;
+}
 class ConfigError extends Error {
     constructor(message) {
         super(message);
@@ -264,6 +396,9 @@ function parseMcpArguments(argv) {
         strict: true,
         options: {
             client: { type: "string" },
+            auth: { type: "string" },
+            "read-only": { type: "boolean", default: false },
+            toolsets: { type: "string" },
             url: { type: "string" },
             scope: { type: "string" },
             "dry-run": { type: "boolean", default: false },
@@ -276,26 +411,48 @@ function displayPath(cwd, path) {
     const shown = relative(cwd, path);
     return shown && !shown.startsWith("..") && !isAbsolute(shown) ? shown : path;
 }
-function planFor(client, scope, url) {
+const notOnPath = (executable, label) => `${executable} is not on PATH. Run this where ${label} is installed:`;
+/** `auth: "oauth"` is only planned for {@link OAUTH_CLIENTS}; the caller refuses the others. */
+function planFor(client, auth, scope, url) {
     const snippets = renderMcpSnippets(url);
+    // Claude Code and Codex take the same plan shape with or without a key.
+    const shared = auth === "oauth" ? renderMcpSignInSnippets(url) : snippets;
+    const claudeUser = {
+        executable: "claude",
+        label: "Claude Code",
+        ...shared.claudeCodeCli,
+        fallback: [notOnPath("claude", "Claude Code")],
+    };
+    const codex = {
+        executable: "codex",
+        label: "Codex",
+        ...shared.codexCli,
+        fallback: [
+            "codex is not on PATH. Add this to ~/.codex/config.toml (or run the command where Codex is installed):",
+            shared.codexToml.trimEnd(),
+        ],
+    };
     switch (client) {
         case "claude-code":
             return scope === "user"
-                ? {
-                    kind: "cli",
-                    executable: "claude",
-                    args: snippets.claudeCodeCli.args,
-                    display: snippets.claudeCodeCli.display,
-                    snippet: `${snippets.claudeCodeCli.display}\n`,
-                    fallback: ["claude is not on PATH. Run this where Claude Code is installed:"],
-                }
+                ? { kind: "cli", commands: [claudeUser], snippet: `${claudeUser.display}\n` }
                 : {
                     kind: "file",
                     file: ".mcp.json",
                     key: "mcpServers",
-                    entry: snippets.claudeCodeServer,
-                    snippet: snippets.claudeCodeProjectJson,
+                    entry: shared.claudeCodeServer,
+                    snippet: shared.claudeCodeProjectJson,
                 };
+        case "codex":
+            return { kind: "cli", commands: [codex], snippet: shared.codexToml };
+        case "conductor":
+            // Conductor has no MCP configuration of its own: its Claude Code and Codex agents read their
+            // user configuration in every workspace.
+            return {
+                kind: "cli",
+                commands: [claudeUser, codex],
+                snippet: `${claudeUser.display}\n${codex.display}\n`,
+            };
         case "cursor":
             return {
                 kind: "file",
@@ -304,18 +461,6 @@ function planFor(client, scope, url) {
                 entry: snippets.cursorServer,
                 snippet: snippets.cursorJson,
             };
-        case "codex":
-            return {
-                kind: "cli",
-                executable: "codex",
-                args: snippets.codexCli.args,
-                display: snippets.codexCli.display,
-                snippet: snippets.codexToml,
-                fallback: [
-                    "codex is not on PATH. Add this to ~/.codex/config.toml (or run the command where Codex is installed):",
-                    snippets.codexToml.trimEnd(),
-                ],
-            };
         case "vscode":
             return {
                 kind: "file",
@@ -331,27 +476,51 @@ function planFor(client, scope, url) {
                 snippet: snippets.windsurfJson,
                 hint: "Merge this into ~/.codeium/windsurf/mcp_config.json (Windsurf > Settings > MCP); the command does not write to your home directory.",
             };
-        case "gemini":
-            return {
-                kind: "cli",
+        case "gemini": {
+            const gemini = {
                 executable: "gemini",
-                args: snippets.geminiCli.args,
-                display: snippets.geminiCli.display,
-                snippet: `${snippets.geminiCli.display}\n`,
-                fallback: ["gemini is not on PATH. Run this where Gemini CLI is installed:"],
+                label: "Gemini CLI",
+                ...snippets.geminiCli,
+                fallback: [notOnPath("gemini", "Gemini CLI")],
             };
+            return { kind: "cli", commands: [gemini], snippet: `${gemini.display}\n` };
+        }
     }
 }
-function nextSteps(client) {
+function nextSteps(client, auth) {
     const label = CLIENT_LABELS[client];
-    const lines = client === "vscode"
-        ? [
+    const approve = "Sign in to Hue and approve the connection. It can read and write every active project in the organization you choose, within your role; for read-only access, use a Read project key with --auth key.";
+    let lines;
+    if (auth === "oauth")
+        lines =
+            client === "claude-code"
+                ? [`In Claude Code, run /mcp, select ${SERVER_NAME} and choose Authenticate. ${approve}`]
+                : client === "codex"
+                    ? [
+                        `If Codex did not open Hue in your browser, run: codex mcp login ${SERVER_NAME}`,
+                        approve,
+                    ]
+                    : [
+                        `In Conductor, open MCP status from the plug icon or /mcp-status, refresh, and use ${SERVER_NAME}'s authentication action. ${approve}`,
+                        "Start a new agent session if the Hue tools do not appear. Hue has not yet verified signed-in Conductor end to end; if the tools still do not load, rerun with --auth key.",
+                    ];
+    else if (client === "vscode")
+        lines = [
             `${label} prompts for the key (input ${INPUT_ID}) when the server starts; paste the ${ENV_VAR} value that hue login stored in .env.hue.`,
-        ]
-        : [
+        ];
+    else if (client === "conductor")
+        lines = [
+            `Conductor agents read ${ENV_VAR} from the login-shell environment Conductor captures, so export it there, not only in a terminal; hue login stores it in .env.hue. Sign-in (--auth oauth) needs no variable.`,
+        ];
+    else
+        lines = [
             `Export ${ENV_VAR} in the shell that starts ${label}; hue login stores it in .env.hue:`,
             "  set -a; . ./.env.hue; set +a",
+            `An app started from the Dock or a launcher does not see that shell's variables; start ${label} from the shell${OAUTH_CLIENTS.includes(client) ? ", or sign in instead with --auth oauth" : ""}.`,
         ];
+    // `codex mcp add` has no option for it, so a registered server gets the line by hand.
+    if (client === "codex" || client === "conductor")
+        lines.push(`If codex mcp add registered ${SERVER_NAME}, add this line under [mcp_servers.${SERVER_NAME}] in ~/.codex/config.toml so Codex runs Hue's tool calls in parallel:`, `  ${CODEX_PARALLEL}`);
     return [...lines, "Then ask your agent:", `  ${MCP_VERIFY_PROMPT}`];
 }
 /**
@@ -387,20 +556,45 @@ export async function runMcpCommand(argv, io = {}) {
     const client = parsed.values.client;
     if (!client || !CLIENT_IDS.includes(client))
         return fail(`${client ? `Unknown client: ${client}.` : "--client is required."} Choose one of ${CLIENT_IDS.join(", ")}.\n\n${MCP_USAGE}`, 2);
+    const clientId = client;
+    const auth = parsed.values.auth ?? (clientId === "conductor" ? "oauth" : "key");
+    if (auth !== "key" && auth !== "oauth")
+        return fail(`--auth must be key or oauth.\n\n${MCP_USAGE}`, 2);
+    if (auth === "oauth" && !OAUTH_CLIENTS.includes(clientId))
+        return fail(clientId === "cursor"
+            ? "--auth oauth is not available for cursor: Hue does not yet accept Cursor's sign-in callback. Use a key (the default), or sign in from claude-code or codex."
+            : `--auth oauth is available for ${OAUTH_CLIENTS.join(", ")}. Use a key (the default) for ${clientId}.`, 2);
     const scope = parsed.values.scope ?? "project";
     if (scope !== "project" && scope !== "user")
         return fail(`--scope must be project or user.\n\n${MCP_USAGE}`, 2);
-    if (scope === "user" && client !== "claude-code")
+    if (scope === "user" && clientId !== "claude-code")
         return fail("--scope user is only available with --client claude-code.", 2);
-    const url = parseMcpUrl(parsed.values.url ?? DEFAULT_MCP_URL);
+    let url = parseMcpUrl(parsed.values.url ?? DEFAULT_MCP_URL);
     if (!url)
         return fail("--url must be an HTTPS URL such as https://mcp.hue.run/mcp (plain HTTP is accepted for loopback test servers only).", 2);
-    const plan = planFor(client, scope, url);
+    // A sign-in connection's access is chosen when it is approved; read_only is not part of it.
+    if (auth === "oauth" &&
+        (parsed.values["read-only"] || new URL(url).searchParams.has("read_only")))
+        return fail("A sign-in connection has Read and write access and cannot be made read-only by its URL. For read-only access, use a Read project key (--auth key), or add --read-only to a key configuration.", 2);
+    if (parsed.values["read-only"])
+        url = readOnlyMcpUrl(url);
+    // --toolsets wins over a selection already in --url, which wins over the client's default.
+    // Both sources are validated: Hue ignores an unknown name and would list its default.
+    const requested = parsed.values.toolsets ?? new URL(url).searchParams.get("toolsets");
+    let toolsets = DEFAULT_TOOLSETS[clientId];
+    if (requested !== null) {
+        const selected = parseToolsets(requested);
+        if ("error" in selected)
+            return fail(`${parsed.values.toolsets === undefined ? "In --url: " : ""}${selected.error}\n\n${MCP_USAGE}`, 2);
+        toolsets = selected.toolsets;
+    }
+    url = toolsetsMcpUrl(url, toolsets);
+    const plan = planFor(clientId, auth, scope, url);
     if (parsed.values.print) {
         stdout.write(plan.snippet);
         return 0;
     }
-    const steps = nextSteps(client);
+    const steps = nextSteps(clientId, auth);
     if (plan.kind === "manual") {
         out(plan.hint);
         stdout.write(plan.snippet);
@@ -410,25 +604,30 @@ export async function runMcpCommand(argv, io = {}) {
     }
     if (plan.kind === "cli") {
         if (parsed.values["dry-run"]) {
-            out(`Would run: ${plan.display}`);
+            for (const command of plan.commands)
+                out(`Would run: ${command.display}`);
             return 0;
         }
-        const executable = await findExecutable(plan.executable, env);
-        if (!executable) {
-            for (const line of plan.fallback)
-                out(line);
-            out(plan.display);
-            for (const line of steps)
-                out(line);
-            return 0;
+        let failed = false;
+        for (const command of plan.commands) {
+            const executable = await findExecutable(command.executable, env);
+            if (!executable) {
+                for (const line of command.fallback)
+                    out(line);
+                out(command.display);
+                continue;
+            }
+            out(`Running: ${command.display}`);
+            const code = await runClientCli(executable, command.args, { cwd, env, stdout, stderr });
+            if (code === 0) {
+                out(`Registered the "${SERVER_NAME}" MCP server (${url}) with ${command.label}.`);
+                continue;
+            }
+            failed = true;
+            stderr.write(`${command.executable} ${code === null ? "could not be started" : `exited with code ${code}`}. Run this command yourself:\n${command.display}\n`);
         }
-        out(`Running: ${plan.display}`);
-        const code = await runClientCli(executable, plan.args, { cwd, env, stdout, stderr });
-        if (code === null)
-            return fail(`${plan.executable} could not be started. Run this command yourself:\n${plan.display}`);
-        if (code !== 0)
-            return fail(`${plan.executable} exited with code ${code}. Run this command yourself:\n${plan.display}`);
-        out(`Registered the "${SERVER_NAME}" MCP server (${url}) with ${CLIENT_LABELS[client]}.`);
+        if (failed)
+            return 1;
         for (const line of steps)
             out(line);
         return 0;

package/dist/client.d.ts

@@ -129,11 +129,14 @@ export declare class HueClient {
      * `hue.tool()` call saw: OpenAI Responses `mcp_call`, `web_search_call`, `file_search_call` and
      * `code_interpreter_call` items, and Anthropic Messages `mcp_tool_use` / `server_tool_use`
      * blocks with their result blocks. Each becomes an `execute_tool {name}` child span of the active
-     * (or given) context with `gen_ai.tool.type` `extension` and `gen_ai.tool.call.id`; MCP calls add
+     * (or given) context with `gen_ai.tool.type` `extension`, `gen_ai.tool.call.id` and
+     * `hue.tool.call.position` (the item's 0-based position in the response); MCP calls add
      * `mcp.server.name` (the provider's label, or the `servers` entry for it). Arguments and results
-     * follow `captureContent`; a failed call carries `error.type` and ERROR status. An OpenAI
-     * `mcp_list_tools` item becomes a `tools/list` child span carrying that server's tools as
-     * `gen_ai.tool.definitions`. Call it inside `hue.model()` so the spans nest under the model call
+     * follow `captureContent`; a failed call carries `error.type` and ERROR status, and with content
+     * capture a failed OpenAI MCP call's status description is the provider's scrubbed, bounded error
+     * text. An OpenAI `mcp_list_tools` item becomes a `tools/list` child span carrying that server's
+     * tools as `gen_ai.tool.definitions`, or without content capture only `hue.tool.names` and
+     * `hue.tool.definitions.sha256`. Call it inside `hue.model()` so the spans nest under the model call
      * and `provider` defaults to its provider; pass `request` to record each server's host as
      * `server.address`. The spans have no duration of their own: the provider ran the tools inside
      * the model request. Unreadable items are skipped and counted; nothing is thrown.