Set up the MCP server

The server is published on npm as dungbeetle-mcp — run it with npx -y dungbeetle-mcp, no install step needed (it also ships with dungbeetle-server as the dungbeetle-mcp binary). stdout is the JSON-RPC channel; diagnostics go to stderr. Missing credentials exit non-zero with guidance.

Using Claude Code, Cursor, Codex, or Gemini CLI? Those pages have the exact config for each tool.

Recommended: an agent token

Mint a scoped, revocable agent token with the device flow — no secret is ever copy-pasted out of the web UI:

dungbeetle login --label "My agent"

Approve the printed code at /ui/connect, then launch over stdio with the token:

DUNGBEETLE_AGENT_TOKEN=dbat_… \
npx -y dungbeetle-mcp

This gives MCP calls a real agent identity: reviews are attributed "<label> (agent, on behalf of <owner>)", scopes limit what the tools can do, and you can revoke the token at /ui/agents at any time.

Alternative: repository client credentials (CI-style)

The MCP server also accepts the same Basic pair dungbeetle push uses — useful in CI where a shared, all-or-nothing repository secret is already provisioned:

DUNGBEETLE_CLIENT_ID=cid_… \
DUNGBEETLE_CLIENT_SECRET=csec_… \
npx -y dungbeetle-mcp

Client credentials carry no agent identity (actions attribute to the repository owner) and no scope limits — prefer an agent token for anything interactive.

Configure an MCP client

Most clients take a command + env. For example, a mcp.json / client config:

{
  "mcpServers": {
    "dungbeetle": {
      "command": "npx",
      "args": ["-y", "dungbeetle-mcp"],
      "env": {
        "DUNGBEETLE_AGENT_TOKEN": "dbat_…"
      }
    }
  }
}

In Claude Code: claude mcp add dungbeetle --env DUNGBEETLE_AGENT_TOKEN=… -- npx -y dungbeetle-mcp — see Claude Code for the project-scoped variant.

Self-hosting

dungbeetle login and dungbeetle-mcp default to the hosted cloud (https://dungbeetle.dev). On a self-hosted server, pass --server <url> to the CLI and add "DUNGBEETLE_SERVER_URL": "https://your-server" to the env block above.

Coming soon: a hosted connector (remote MCP over streamable HTTP with OAuth), so clients can connect without running a local binary.