MCP Server Configuration

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 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.

Bearer header (recommended)

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

{
  "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:

{
  "mcpServers": {
    "devhelm": {
      "url": "https://mcp.devhelm.io/dh_live_xxxxxxxx/mcp"
    }
  }
}

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.

Client setup

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

Cursor
Claude Desktop
Windsurf
Claude Code

Add to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json for global access:

{
  "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”.

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "devhelm": {
      "url": "https://mcp.devhelm.io/mcp",
      "headers": {
        "Authorization": "Bearer dh_live_xxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop after saving.

Add to your Windsurf MCP settings:

{
  "mcpServers": {
    "devhelm": {
      "url": "https://mcp.devhelm.io/mcp",
      "headers": {
        "Authorization": "Bearer dh_live_xxxxxxxx"
      }
    }
  }
}

Add DevHelm as a remote MCP server:

claude mcp add devhelm \
  --transport http \
  --url https://mcp.devhelm.io/mcp \
  --header "Authorization: Bearer dh_live_xxxxxxxx"

Environment variables

When using the hosted server, configuration is minimal — just the token in your client config. These environment variables apply when running 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

For the hosted server, pass org_id and workspace_id as query parameters if needed: https://mcp.devhelm.io/mcp?org_id=123&workspace_id=456

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.

Requires Python 3.11 or later. The package depends on devhelm (the Python SDK, ≥ 0.4.0) and fastmcp ≥ 2.0.

Install

The fastest way is uvx (downloads, caches, and runs in one step):

uvx devhelm-mcp-server

Or install with pip:

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:

Cursor
Claude Desktop
Windsurf

{
  "mcpServers": {
    "devhelm": {
      "command": "uvx",
      "args": ["devhelm-mcp-server"],
      "env": {
        "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "devhelm": {
      "command": "uvx",
      "args": ["devhelm-mcp-server"],
      "env": {
        "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "devhelm": {
      "command": "uvx",
      "args": ["devhelm-mcp-server"],
      "env": {
        "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
      }
    }
  }
}

Health check

The hosted server exposes a health endpoint:

curl https://mcp.devhelm.io/health

{"status": "healthy", "service": "devhelm-mcp-server"}

Troubleshooting

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.

Authentication errors (401 / 403)

Verify your API token is valid:

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. For hosted, append ?workspace_id=YOUR_ID to the URL. For local, set DEVHELM_WORKSPACE_ID in the env block.

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 instead.

`uvx: command not found` (local only)

Install uv first:

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.

`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.

MCP Server Configuration

Authentication

Bearer header (recommended)

Path-based token

Client setup

Environment variables

Run locally

Install

Local client config

Health check

Troubleshooting

Next steps

Tools reference

MCP overview

Documentation Index

​Authentication

​Bearer header (recommended)

​Path-based token

​Client setup

​Environment variables

​Run locally

​Install

​Local client config

​Health check

​Troubleshooting

​Next steps

Tools reference

MCP overview

Authentication

Bearer header (recommended)

Path-based token

Client setup

Environment variables

Run locally

Install

Local client config

Health check

Troubleshooting

Next steps