> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Configuration

> Authentication, environment variables, local setup, and troubleshooting for the DevHelm MCP server

The DevHelm MCP server is hosted at `mcp.devhelm.io` — connect from any MCP-compatible client without installing anything. The same code is also [published to PyPI](#run-locally) for local/offline use.

## Authentication

Every request to the MCP server requires a DevHelm API token. Create one from **Settings → API Keys** in the [Dashboard](https://app.devhelm.io).

### Bearer header (recommended)

Send your token in the `Authorization` header. The token never appears in the URL.

```json theme={null}
{
  "mcpServers": {
    "devhelm": {
      "url": "https://mcp.devhelm.io/mcp",
      "headers": {
        "Authorization": "Bearer dh_live_xxxxxxxx"
      }
    }
  }
}
```

### Path-based token

For clients that only accept a URL and don't support custom headers, embed the token in the path:

```json theme={null}
{
  "mcpServers": {
    "devhelm": {
      "url": "https://mcp.devhelm.io/dh_live_xxxxxxxx/mcp"
    }
  }
}
```

<Warning>
  The path-based form puts your token directly in the URL. Treat the entire URL as a secret — don't commit it to version control or share it in plaintext. Use the Bearer header form whenever your client supports it.
</Warning>

## Client setup

Copy the config for your client. All examples use the hosted server with Bearer auth.

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for global access:

    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "url": "https://mcp.devhelm.io/mcp",
          "headers": {
            "Authorization": "Bearer dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```

    After saving, restart the MCP server via the Command Palette → **"MCP: Restart Server"**.
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop config file:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "url": "https://mcp.devhelm.io/mcp",
          "headers": {
            "Authorization": "Bearer dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "url": "https://mcp.devhelm.io/mcp",
          "headers": {
            "Authorization": "Bearer dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add DevHelm as a remote MCP server:

    ```bash theme={null}
    claude mcp add devhelm \
      --transport http \
      --url https://mcp.devhelm.io/mcp \
      --header "Authorization: Bearer dh_live_xxxxxxxx"
    ```
  </Tab>
</Tabs>

## Environment variables

When using the hosted server, configuration is minimal — just the token in your client config. These environment variables apply when [running locally](#run-locally):

| Variable               | Default                  | Description                                                                 |
| ---------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `DEVHELM_API_TOKEN`    | —                        | API token for authentication (required)                                     |
| `DEVHELM_API_URL`      | `https://api.devhelm.io` | API base URL (for self-hosted or testing)                                   |
| `DEVHELM_ORG_ID`       | —                        | Organization ID; required when your token grants access to multiple orgs    |
| `DEVHELM_WORKSPACE_ID` | —                        | Workspace ID; required when your token grants access to multiple workspaces |

## Run locally

If you need offline access or want to develop against a local API, the same server code is published to PyPI as `devhelm-mcp-server`. It speaks MCP over stdio — your client spawns it as a subprocess.

<Note>
  Requires Python 3.11 or later. The package depends on [`devhelm`](https://pypi.org/project/devhelm/) (the Python SDK, ≥ 1.3.0) and [`fastmcp`](https://github.com/jlowin/fastmcp) ≥ 3.2.3.
</Note>

### Install

The fastest way is [`uvx`](https://docs.astral.sh/uv/) (downloads, caches, and runs in one step):

```bash theme={null}
uvx devhelm-mcp-server
```

Or install with pip:

```bash theme={null}
pip install devhelm-mcp-server
```

The package registers a `devhelm-mcp-server` console script (with `devhelm-mcp` as a deprecated back-compat alias).

### Local client config

When running locally, your MCP client spawns the server as a subprocess instead of connecting to a URL:

<Tabs>
  <Tab title="Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "command": "uvx",
          "args": ["devhelm-mcp-server"],
          "env": {
            "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "command": "uvx",
          "args": ["devhelm-mcp-server"],
          "env": {
            "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    ```json theme={null}
    {
      "mcpServers": {
        "devhelm": {
          "command": "uvx",
          "args": ["devhelm-mcp-server"],
          "env": {
            "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Health check

The hosted server exposes a health endpoint:

```bash theme={null}
curl https://mcp.devhelm.io/health
```

```json theme={null}
{"status": "healthy", "service": "devhelm-mcp-server"}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not appearing after adding config">
    Restart your MCP client after saving the configuration. In Cursor, open the Command Palette and search for **"MCP: Restart Server"**. In Claude Desktop, quit and relaunch the app.
  </Accordion>

  <Accordion title="Authentication errors (401 / 403)">
    Verify your API token is valid:

    ```bash theme={null}
    curl -H "Authorization: Bearer dh_live_xxxxxxxx" https://api.devhelm.io/api/v1/monitors
    ```

    If you get a 403 with "workspace not specified", your token has access to multiple workspaces. Set `DEVHELM_ORG_ID` and `DEVHELM_WORKSPACE_ID` environment variables — for local installs in the `env` block of your MCP client config, or as shell env vars for the hosted server's bearer token resolution.
  </Accordion>

  <Accordion title="Connection timeout to mcp.devhelm.io">
    Check that your network allows outbound HTTPS to `mcp.devhelm.io`. Corporate proxies or VPNs may block the connection. If you can't reach the hosted server, [run locally](#run-locally) instead.
  </Accordion>

  <Accordion title="`uvx: command not found` (local only)">
    Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first:

    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    Or skip uv entirely: `pip install devhelm-mcp-server` and use `"command": "devhelm-mcp-server"` in your config.
  </Accordion>

  <Accordion title="`devhelm-mcp-server: command not found` (local only)">
    Ensure your Python `Scripts`/`bin` directory is on `PATH`. If you're using pyenv or a virtual environment, use the full path to the binary or activate the environment before launching your MCP client.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tools reference" icon="wrench" href="/sdk/mcp/tools-reference">
    Complete catalog of all MCP tools with parameters.
  </Card>

  <Card title="MCP overview" icon="robot" href="/sdk/mcp/overview">
    Introduction, example interactions, and full tool coverage.
  </Card>
</CardGroup>