API Key & Remote MCP

📘
Most users should use the local MCP via the Hud IDE extension or npm
Remote MCP exists for cases where that isn't possible - typically because you can't install the Hud IDE extension, or because your workflow runs in an environment that doesn't support local MCP servers.

How it works

There are two ways to connect, and most clients support both:

Standalone - the client launches the Hud MCP server as a local process (npx), authenticating with an API key in the HUD_MCP_KEY environment variable.
Remote (hosted) - the client connects to Hud's hosted server at https://mcp.hud.io/mcp, authenticating with either OAuth (interactive, for humans) or an API key in the X-Hud-Mcp-Key header (for machines, CI, and agentic workflows).

Both API-key methods use the same key. Pick your client below.

Get your API key

Your API key lives in your Hud account settings:

👉 app.hud.io/settings/api-keys

📘
No API key in your account? Not every account has one provisioned yet. Contact us via the in-app chat or email [email protected] and we'll issue one for you.

Treat the key like a password - never commit it to source control or share it in a public channel.

Cursor

Add Hud to your Cursor mcp.json (project-level at <project>/.cursor/mcp.json or user-level at ~/.cursor/mcp.json).

Standalone (API key):

{
  "mcpServers": {
    "hud": {
      "command": "npx",
      "args": ["-y", "hud-mcp"],
      "env": {
        "HUD_MCP_KEY": "<Your API key>"
      }
    }
  }
}

Remote - OAuth (interactive use):

{
  "mcpServers": {
    "hud": {
      "type": "http",
      "url": "https://mcp.hud.io/mcp",
      "auth": {
        "CLIENT_ID": "XyvD6NaPGbrpOL9mxglq7KUYuPXbyNB4"
      }
    }
  }
}

Toggle hud on in Cursor Settings → Tools & MCP; Cursor opens a browser tab to sign you in. The CLIENT_ID is identical for all users and should not be changed.

Remote - API key (automations, Cursor Background Agents, headless setups):

{
  "mcpServers": {
    "hud": {
      "type": "http",
      "url": "https://mcp.hud.io/mcp",
      "headers": {
        "X-Hud-Mcp-Key": "<Your API key>"
      }
    }
  }
}

Claude Code

Standalone (API key):

claude mcp add hud -e HUD_MCP_KEY=<Your API key> -- npx -y hud-mcp

Remote - OAuth (interactive use):

claude mcp add --scope user -t http hud \
  --client-id XyvD6NaPGbrpOL9mxglq7KUYuPXbyNB4 \
  --callback-port 2425 \
  https://mcp.hud.io/mcp

Then go into Claude Code and authenticate by running /mcp and following the OAuth flow. The CLIENT_ID is identical for all users and should not be changed.

Remote - API key (CI, scripted agents, containers):

claude mcp add -t http hud https://mcp.hud.io/mcp \
  -H "X-Hud-Mcp-Key: <Your API key>"

Other MCP clients

Any client that can launch a command runs the standalone server the same way - point it at npx -y hud-mcp and set HUD_MCP_KEY in its environment:

{
  "mcpServers": {
    "hud": {
      "command": "npx",
      "args": ["-y", "hud-mcp"],
      "env": {
        "HUD_MCP_KEY": "<Your API key>"
      }
    }
  }
}

For clients that connect over HTTP instead, use https://mcp.hud.io/mcp with the client-id:XyvD6NaPGbrpOL9mxglq7KUYuPXbyNB4 or with API key using they X-Hud-Mcp-Key header.

Need Help? Chat with our support team or email us at [email protected].