Skip to main content
This page is written for your coding agent. Open the agent in your application’s repository and send it the prompt from Quickstart. To set up Hue yourself, follow the Quickstart steps instead. If the user has a trial organization provisioned by Hue, use the trial World setup instead of the tracing procedure below. An owner or admin opens Worlds and chooses Create world. They copy the prompt from Create world with your agent into a trusted coding agent. Follow that prompt without installing tracing or an MCP connection. Follow these steps in order. Stop and wait for the user only in step 2, or when a check fails and a step says to ask them. Never ask the user to paste a Hue key into the chat, and never print, log or commit one.

​
1. Inspect and plan

Read the repository’s own instructions (such as AGENTS.md, CLAUDE.md or CONTRIBUTING.md), then find, without changing anything:
  • The language, framework, package manager and the versions in use.
  • Every request path that calls a model or a tool, and how streamed responses finish.
  • Existing OpenTelemetry or Langfuse setup, other exporters, and any redaction or data policy for prompts and responses.
  • How the application loads local secrets: an ignored env file (such as .env.local or .env), a secret manager its scripts or configuration use (such as Doppler, 1Password or Infisical), or neither. Check only which variables are present, never their values.
Choose the integration: the TypeScript SDK for Node.js or Bun, the Python SDK for Python, or the application’s existing OpenTelemetry or Langfuse setup, which stays in place. With AI SDK 6, the TypeScript SDK’s hueExperimentalTelemetry; with AI SDK 7, hueTelemetry. The skill’s Choose the integration section has the details, and you can read it before installing it (step 4). Tell the user your plan in passing: that setup needs a Hue account and a key they create themselves, the integration you will use, the files you expect to change, the capture policy you propose and the request you will use to verify. Don’t wait for them to agree; continue with step 2.

​
2. Get your Hue API key

This setup uses one Read and write project key, stored as HUE_API_KEY. It sends traces, checks what Hue stored and runs evaluations. Claude Code, Codex, Conductor and Cursor connect to the Hue MCP server in step 7 by signing in with Hue and need no key. A client that connects with a key instead reads the same key as HUE_MCP_KEY: VS Code, Windsurf and Gemini CLI, a client that runs without a browser, and any client when the user asks for a key. Change nothing in the repository until a key exists. If the application’s secret workflow already provides a Read and write key as HUE_API_KEY, and as HUE_MCP_KEY when the client connects with a key, go to step 3. A .env.hue that hue login wrote holds a Read and write key, because hue login refuses other presets; any other existing HUE_API_KEY may be a legacy tracing key, so ask the user which preset it is. If it is Read and write but the client connects with a key and HUE_MCP_KEY is missing, ask the user to add HUE_MCP_KEY with the same value, then go to step 3. Otherwise, tell the user, in this wording or close to it:
Hue needs a Read and write API key from your Hue account. You create and store it yourself, so please don’t paste it into this chat.
  1. Sign in at https://app.hue.run, select the project that should receive this application’s traces, open Settings → API keys (https://app.hue.run/settings/integrations) and create a Read and write key. Members ask an owner or admin for one.
  2. Store it as HUE_API_KEY (and HUE_MCP_KEY, if your coding agent connects with a key) in your secret manager, or run this in your own terminal from the repository root and paste the key at its hidden prompt: npx -y @hue-run/sdk@latest login --gitignore
  3. Tell me when it’s stored. You can ignore the next steps it prints; I’ll do those.
A Hue account is required. When you have one, send the setup prompt again.
When the application uses no secret manager, offer only the hue login command in item 2. Then stop and wait until the user says the key is stored. If the user says they have no Hue account, tell them a Hue account is required, change nothing and end the setup. Don’t run hue login yourself: it waits for the key at a hidden prompt. If the user pastes a key into the chat, don’t use it; ask them to delete that key in Hue and store a new one. hue login checks the key against Hue, writes it to .env.hue as both HUE_API_KEY and HUE_MCP_KEY, with HUE_BASE_URL and HUE_MCP_URL for the CLI, and adds the file to .gitignore if it isn’t ignored yet. It refuses a Read key or a legacy tracing key and never prints the key. The SDKs don’t read HUE_BASE_URL; Hue Cloud is their default. If the application loads another ignored env file, add --env-path with that file’s path to the command in your message; add --force if the file already holds different values for these variables. Without Node.js, the user adds a HUE_API_KEY= line with the key to an ignored env file in an editor, and a HUE_MCP_KEY= line with the same key for a client that connects with a key.

​
3. Check the key

Run this check without echoing the key. It sends the key only to app.hue.run and prints the key’s project, not the key:
Load HUE_API_KEY without printing it, and expand it only after it is loaded: with an env file, sh -c 'set -a; . ./<env-file>; set +a; curl …', where <env-file> is the file the key is in, such as .env.hue or .env.local; with a secret manager, its runner, such as doppler run -- sh -c 'curl …'. 200 means the key works: tell the user the project name in the response and continue. 401 means the key is missing, mistyped, revoked or expired: ask the user to check it or store a new one, then check again. 404 means the key’s project is archived. If the user can’t sign in to Hue, they don’t have an account yet: tell them a Hue account is required.

​
4. Install the Hue skill

The Hue skill holds the tracing procedure for each SDK and framework. Install it into the repository so later sessions have it, after telling the user it adds the skill’s files and a skills-lock.json:
<agent> is the skills CLI’s id for the coding agent you are, such as claude-code, codex, cursor, github-copilot, windsurf or gemini-cli; an id it doesn’t know makes it list the valid ones. If the user declines, Node.js is unavailable, the CLI has no id for you or the command fails, read the skill with curl from https://docs.hue.run/skill.md?v=0.8.28 instead. Either way, read it from the start.

​
5. Add tracing

Follow the skill from Choose the integration through Verify delivery, for the application’s language and framework. Its Get a Hue API key section only confirms that the key from steps 2 and 3 is present; don’t start this page again from the skill. Come back after Verify delivery, for step 6. Hold the skill’s Handoff; this page ends the setup.
  • Instrument every request path that calls a model or tool, with model and tool child spans and the application’s session identifier.
  • Capture content with captureContent: true / capture_content=True, written explicitly, or keep the application’s existing pattern if it reads HUE_CAPTURE_CONTENT and treats only false as the opt-out. Explain that this sends prompts, responses and tool inputs and outputs to Hue. Honor an explicit metadata-only choice or an existing policy that forbids sending that content to another service, and keep existing redaction either way.
  • If the application already exports to Langfuse or another OpenTelemetry destination, add Hue’s processor where the existing provider is constructed, keep the existing exporters and AI SDK integration, and don’t upgrade the framework only to add an exporter.
  • The SDKs don’t load env files: run the application through its existing env loading or secret manager, and keep reading HUE_API_KEY from the environment in code. If it has neither, load the env file in its start command, for example node --env-file-if-exists=.env.hue or uv run --env-file .env.hue, so traces don’t silently stop.

​
6. Verify a real request

Run one real request through the changed path, end its spans and flush. In a running server, capture the request span’s traceId during setup, in a log line or a response header, and verify it from a diagnostic client as the skill’s Verify delivery describes; a null receipt means no trace with that ID reached the loaded key’s project before the deadline. Then confirm, in the trace Hue stored, that:
  • The model and tool spans sit under the request span, which is the trace root unless the request arrived with propagated parent context.
  • With content capture, the request span’s input and output are the real request and reply, and the model and tool spans carry their messages, arguments and results.
  • Any image, audio or document the request handled shows as stored; see verify uploaded media.
Use the skill’s Verify delivery checks. Setup is not complete until the stored trace shows this content, unless the user chose metadata-only capture. Report any request path you did not exercise. Before the application runs on a production server, tell the user to create a separate Read and write key for that server’s secret store; production code reads it from the same HUE_API_KEY variable.

​
7. Connect the Hue MCP server

This is the last change because most clients load a new MCP server only when they start. From the repository root, run the command for the user’s client; for a Codex or Conductor sign-in, the user runs it. If you ask the user to choose a client, always include Other MCP client. For an unlisted client, follow the Any MCP client tab of Connect your client: use sign-in with Hue when the client supports Streamable HTTP and OAuth, or the project-key settings when it cannot sign in. A client that can neither sign in nor edit its configuration from the repository connects with those settings: Streamable HTTP to https://mcp.hue.run/mcp with the header Authorization: Bearer <HUE_MCP_KEY>, read from the env file, never the key itself. After connecting, verify the MCP connection; the project API check in step 3 does not test MCP transport. Do not pass an unlisted client name to hue mcp install --client. Claude Code, Codex, Conductor and Cursor sign in with Hue. The command is this, where <client> is claude-code, codex, conductor or cursor:
Run it yourself for claude-code and cursor. Don’t run it yourself for codex or conductor: it runs codex mcp add, which opens the Hue sign-in in the browser at once and waits up to 5 minutes for the user to approve it. Give the user the command in your final message instead, to run from the repository root in their own terminal. VS Code, Windsurf and Gemini CLI connect with the key. Run this, where <client> is vscode, windsurf or gemini:
hue mcp install configures these three clients with a key. To sign in instead, use the sign-in settings in the Any MCP client tab of Connect your client. A sign-in connection can read and write every active project in the organization the user approves, within their role. When Claude Code, Codex, Conductor or Cursor connects with a key for a reason step 2 names, run npx -y @hue-run/sdk@latest mcp install --client <client> --auth key for claude-code, codex, conductor or cursor: without --auth key, the command may sign these clients in instead (Conductor always; Claude Code, Codex and Cursor unless HUE_MCP_KEY is set or an existing entry uses a key). That connection reads HUE_MCP_KEY, which hue login already stored. For read-only access, the user creates a Read key and stores it as HUE_MCP_KEY instead, in the secret manager or with npx -y @hue-run/sdk@latest login --keys coding-agent --force --gitignore (with the same --env-path, if step 2 used one), which replaces only HUE_MCP_KEY and HUE_MCP_URL in the env file; then run the same mcp install command for the client, with --auth key for claude-code, codex, conductor or cursor. With --auth oauth, the command writes only the server URL. With a key, it writes a server named hue that references HUE_MCP_KEY and never the key itself; VS Code’s entry instead prompts for the key when the server starts. .mcp.json (Claude Code) and .cursor/mcp.json (Cursor) are safe to commit; with a key, each teammate then needs their own key. For Codex and Conductor, the command runs codex mcp add, which writes ~/.codex/config.toml, and for Conductor also claude mcp add --scope user; if your sandbox blocks that, ask the user to approve it. VS Code prompts for the key when the server starts, and for Windsurf the command prints a snippet to merge into the file it names. Without Node.js, use the user’s client tab in Connect your client, or the Any MCP client tab’s project-key settings for VS Code, Windsurf or Gemini CLI.

​
8. Finish

The user restarts the client to load the server, so finish with one message that gives the user:
  1. A summary: the installed package and version, the files you changed, the capture policy, the request you verified and its trace link, and anything not yet verified.
  2. How to restart the client and finish connecting:
    • With --auth oauth, there is no key to load. The user restarts the client and completes sign-in with its authentication action. In Claude Code: claude --continue, approving the hue server when asked, then /mcp, select hue and choose Authenticate. In Codex: the user first runs the install command you gave them, in a terminal where they can use a browser, and approves the sign-in it opens; if that sign-in did not finish, they run codex mcp login hue once rather than codex mcp add again, then codex resume --last. In Conductor: the user first runs the install command the same way, then opens MCP status from the plug icon or /mcp-status, refreshes and uses hue’s authentication action, then starts a new agent session if the Hue tools don’t appear. In Cursor: the user turns on hue in Cursor’s MCP settings and uses its login action, or runs cursor-agent mcp login hue. On Hue’s consent page, the user checks the organization and chooses Allow. Add that if sign-in doesn’t complete or the Hue tools don’t load, they can connect with the key instead: run the key command with --auth key after codex mcp remove hue for Codex, or claude mcp remove hue -s user and codex mcp remove hue for Conductor; for Cursor, the key command replaces the entry in .cursor/mcp.json.
    • With a key in VS Code, the user restarts the server and pastes the key from the env file at VS Code’s prompt.
    • With a key in another client, load the key into the shell that starts the client, for example with set -a; . ./.env.hue; set +a for the env file the key is in, or start the client through the secret manager’s runner. Then restart it from that shell: claude --continue for Claude Code, approving the hue server when asked; codex resume --last for Codex; or quit Cursor, reopen it with cursor . and turn on hue in its MCP settings.
  3. The prompt to send after the restart, the same one Connect uses: Use Hue MCP: call list_projects and confirm which project to inspect. Then call get_project_context and show its 5 most recent error traces with links. For an organization connection, pass the project's id or slug as project_id on each call after list_projects. For a pinned connection, confirm connection.pinned is true and do not pass project_id.
  4. What they can ask next, for example “What needs attention in the last 24 hours, and why?” or “Turn this trace into a case and evaluate my agent against it”. Hue MCP lists what the agent can do.