Connect the Hue MCP server

The Hue MCP server is a hosted Model Context Protocol server at https://app.hue.run/api/mcp. There is nothing to install: point an MCP client at the URL with a read-only key and the agent can search traces, inspect spans, verify delivery, read datasets and experiment results and search these docs, all scoped to one project. This release is read-only.

Create a read-only key

An owner or admin opens Settings → Integrations & API keys, chooses the project and creates a key with the Read-only scope. Save it in your secret manager and expose it to the agent’s machine as HUE_MCP_KEY. Keep this key separate from the application’s HUE_API_KEY, which is a Read and write key. A read-only key cannot send telemetry, change datasets or start evaluation runs, so a leaked agent key cannot alter your project. It should never be wired into application code or committed. See project keys.

The server speaks Streamable HTTP and is stateless. It serves both current MCP protocol revisions, so Claude Code, Codex, Cursor, Windsurf and Gemini CLI connect without extra flags. Clients that only support stdio need a remote-capable MCP client. https://mcp.hue.run/mcp becomes the canonical address once that host is live; https://app.hue.run/api/mcp stays valid for key authentication.

Connect your client

Paste this into your coding agent. It connects the server and confirms the connection in one step.

Connect me to the Hue MCP server.

It is a remote MCP server (Streamable HTTP) at https://app.hue.run/api/mcp.
Authenticate with a bearer token read from the HUE_MCP_KEY environment
variable — reference the variable, do not write the key into a config file.

Register it under the name "hue" using whatever MCP configuration my client
uses, then call get_project_context and tell me which Hue project it reached.

Prefer to set it up yourself? Every snippet below references the HUE_MCP_KEY environment variable; never paste a literal key into a configuration file that other people or tools can read.

Claude Code
Codex
Cursor
Windsurf and Gemini CLI

Add a project-scoped .mcp.json next to your application code. Claude Code expands ${HUE_MCP_KEY} from the developer’s environment and asks for approval before using a project-scoped server.

.mcp.json

{
  "mcpServers": {
    "hue": {
      "type": "http",
      "url": "https://app.hue.run/api/mcp",
      "headers": { "Authorization": "Bearer ${HUE_MCP_KEY}" }
    }
  }
}

Or add it for all your projects from the command line. Single quotes keep the reference unexpanded in your settings file:

claude mcp add --transport http --scope user hue https://app.hue.run/api/mcp \
  --header 'Authorization: Bearer ${HUE_MCP_KEY}'

Run /mcp inside Claude Code to confirm the connection. Tools appear as mcp__hue__<tool>.

Codex reads the key from an environment variable at connection time:

codex mcp add hue --url https://app.hue.run/api/mcp --bearer-token-env-var HUE_MCP_KEY

The equivalent ~/.codex/config.toml entry:

config.toml

[mcp_servers.hue]
url = "https://app.hue.run/api/mcp"
bearer_token_env_var = "HUE_MCP_KEY"

Add the server to .cursor/mcp.json in the repository or to your global Cursor MCP settings:

.cursor/mcp.json

{
  "mcpServers": {
    "hue": {
      "url": "https://app.hue.run/api/mcp",
      "headers": { "Authorization": "Bearer ${env:HUE_MCP_KEY}" }
    }
  }
}

Cursor limits the number of tools it loads across servers; Hue registers thirteen.

Windsurf uses serverUrl in ~/.codeium/windsurf/mcp_config.json:

mcp_config.json

{
  "mcpServers": {
    "hue": {
      "serverUrl": "https://app.hue.run/api/mcp",
      "headers": { "Authorization": "Bearer ${env:HUE_MCP_KEY}" }
    }
  }
}

Gemini CLI stores the expanded header, so run this only on a machine where the key may live in that settings file:

gemini mcp add --transport http hue https://app.hue.run/api/mcp -H "Authorization: Bearer $HUE_MCP_KEY"

Other clients — VS Code, GitHub Copilot’s coding agent, Amp, Zed, JetBrains Junie, OpenCode — take the same url and Authorization header in their own configuration format. Hosted assistants that require OAuth, such as claude.ai connectors and ChatGPT, are not supported in this release.

Verify the connection

Ask the agent:

Use the Hue MCP: call get_project_context, then show my 5 most recent error traces with links.

get_project_context returns the project the key reaches, its capabilities and whether the connection is read-only. If it reports a different project than you expected, the key was created in the wrong project.

What you can do

Investigate a failure. “Show the error traces from the last 24 hours”, “open the slowest span of that trace”, “what did the model see before it failed?” (recorded content requires include_content: true and the application must have captured it). Tools: search_traces, get_trace, get_span, list_sessions. Confirm delivery. “Did trace 0af7651916cd43dd8448eb211c80319c arrive with spans a and b, with model and usage recorded?” Tools: verify_trace. Read evaluations. “List my datasets”, “show the cases in the latest version of the regression set”, “summarize the last experiment and list the failing cases”, “compare it against the baseline experiment”. Tools: list_datasets, get_dataset, list_scorers, list_experiments, get_experiment. Look things up. “How do I flush spans in a Next.js streaming route?” Tools: search_hue_docs, load_hue_guide (data-model, investigate). Every trace_id argument accepts a Hue id, the 32-hex OpenTelemetry trace id or a Hue trace link. Time windows accept ISO-8601 or relative values such as 15m, 24h or 7d (up to 90 days). Results are paginated with opaque cursors and bounded by max_chars; truncated results say so and suggest a narrower request.

Content and safety

Recorded prompts, outputs, tool arguments and raw attributes are omitted unless a tool is called with include_content: true. By default the server returns metadata (model, provider, usage, tool names, status, timing) and the names of recorded attributes. Content reads are recorded in the project’s audit log.
Names, generated titles, session keys, metadata and judge explanations come from your application and its end users. They are length-capped, and every result that carries them starts with a notice that they are data, not instructions; recorded content is wrapped in delimited blocks.
Credential-shaped strings are redacted from results and from documentation queries before those leave Hue.
The key is the tenant. Ids from another project, and projectId parameters on pasted links, resolve to not_found.
Add ?read_only=true to the URL to hide and reject any write tool regardless of the key.
Requests are limited to 1 MiB, ten failed authentications per minute for one key id return 429, and a saturated server returns 503 with Retry-After.

Troubleshooting

401 means the key is missing, malformed, revoked or expired. 403 means the key has no read access: create a key with the Read-only scope. 405 on GET and 404 for Mcp-Session-Id are expected: the server accepts stateless POST requests only. See troubleshooting.

What is next

This release has no write tools. Additive dataset writes (add_dataset_cases, add_trace_to_dataset) and experiment comparison come later, then OAuth sign-in for hosted assistants. Tool names stay stable; renamed tools keep their old name for at least ninety days.

Getting started

For agents

SDKs

Integrations

Evaluations

Guides

API reference

Connect the Hue MCP server

Create a read-only key

Connect your client

Verify the connection

What you can do

Content and safety

Troubleshooting

What is next

​Create a read-only key

​Connect your client

​Verify the connection

​What you can do

​Content and safety

​Troubleshooting

​What is next

Create a read-only key

Connect your client

Verify the connection

What you can do

Content and safety

Troubleshooting

What is next