---
updatedAt: 2026-09-29T21:08:27.000Z
agentTools:
  projectIndex: https://docs.hud.io/llms.txt
---

# API Key & Remote MCP

Connect to Hud MCP without the IDE extension - run the server standalone with an API key, or use Hud's hosted server over HTTPS.

<Callout icon="📘" theme="info">
  ### Most users should use the [local MCP via the Hud IDE extension](/docs/install-mcp) 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.
</Callout>

***

## 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`](https://www.app.hud.io/settings/api-keys?environment=production)

<Callout icon="📘" theme="info">
  **No API key in your account?** Not every account has one provisioned yet. [Contact us via the in-app chat](https://www.app.hud.io/?support_chat=true) or email [support@hud.io](mailto:support@hud.io) and we'll issue one for you.
</Callout>

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):**

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

**Remote - OAuth (interactive use):**

```json
{
  "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):**

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

***

## Claude Code

**Standalone (API key):**

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

**Remote - OAuth (interactive use):**

```bash
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):**

```bash
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:

```json
{
  "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.

***

<HTMLBlock>{`
<b>Need Help?</b>
<a href="https://www.app.hud.io/?support_chat=true" target="_blank">Chat with our support team</a>

or email us at
<a href="mailto:support@hud.io" target="_blank">support@hud.io</a>.
`}</HTMLBlock>