sym-debug-mcp

Stdio MCP server for the Symmetry debugger. Browser-based sign-in on first use — no npm install, no manual login command.

Install

Add this to your MCP host config and restart it:

Claude Code (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sym-debug": {
      "command": "npx",
      "args": ["-y", "sym-debug-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json) — same shape.

That's it. On first invocation, the MCP prints a sign-in URL and code in the host's logs:

=== Symmetry debugger sign-in ===
Open: https://symmetryciam.ciamlogin.com/.../oauth2/v2.0/devicecode
Code: ABC1-DEF2
Waiting for sign-in to complete...

It also tries to open your browser automatically. Sign in with your @getsymmetry.com email; the MCP polls for the token and caches it at ~/.sym-debug/credentials (mode 0600). Subsequent runs reuse the cached token; if it expires, the refresh token gets a new one silently.

Tool calling

Every tool requires env: "prod" | "test". The MCP forwards it as the URL path segment to the debugger.

list_workspaces(env="prod", page=1, page_size=50)
get_business_pulse(env="test")

Tool list is auto-discovered from the debugger's /api/debug/tools/schema endpoint at startup. New endpoints appear without a publish.

Subcommands

If npx -y sym-debug-mcp is invoked with an arg, it skips the MCP server and runs that command:

| Command | What | |---------|------| | signin / login | Run the device-code flow now (useful to pre-warm) | | whoami | Print the cached operator email | | logout | Clear cached credentials |

Optional env

| Var | Default | Purpose | |-----|---------|---------| | SYM_DEBUG_URL | https://sym-api-fagzf6fdbdanbdb4.z03.azurefd.net/api | Override debugger base URL (dev / staging) | | SYM_DEBUG_TOKEN | (creds file) | Bypass interactive sign-in (CI) | | SYM_DEBUG_REGION | centralus | Sets X-Debug-Region header | | AZURE_ENTRA_EXTERNAL_TENANT_NAME | symmetryciam | Override CIAM tenant for sign-in | | AZURE_ENTRA_EXTERNAL_TENANT_ID | (prod tenant) | Override CIAM tenant id | | AZURE_AD_CLIENT_ID | (prod app) | Override CIAM app id | | AGENTS_DISPATCHER_URL | unset | Cloud Agents dispatcher base URL for agent_* tools | | AGENTS_BEARER_TOKEN | unset | Dispatcher control bearer token |

Cloud-agent tools

The MCP also exposes Cloud Agents controls. These do not use the debugger API; they call the dispatcher configured by AGENTS_DISPATCHER_URL and AGENTS_BEARER_TOKEN.

| Tool | What | |---|---| | agent_list | List running/recent agents | | agent_status | Show status, risk, approval, cost, PR, manifest | | agent_stop / agent_reset | Stop or reset an agent through the shared control core | | agent_interrupt | Queue an operator message for the runner | | agent_plan / agent_artifacts | Return manifest and artifact URLs/data | | agent_approve / agent_reject | Approve or reject posted plans; red-risk plans require highRisk=true | | agent_timeline | Show append-only lifecycle events | | agent_cost | Show daily and per-task budget status | | agent_pause / agent_resume | Pause or resume new dispatches | | agent_policy | Show risk, approval, backend verification, and policy status |

Examples:

agent_status(mnemonic="quick-fox-3a8f")
agent_approve(mnemonic="quick-fox-3a8f", highRisk=false)
agent_timeline(mnemonic="quick-fox-3a8f", limit=25)

Auth gate

Two-ring on the server side:

• Outer: CIAM tenant validates the token (symmetryciam).
• Inner: EmployeeRequired rejects any email not ending in @getsymmetry.com (router-level dependency so no endpoint is accidentally ungated).

A non-Symmetry token gets 403.

History

Originally sym-admin-dashboard/mcp/. Relocated 2026-05-09 as part of the debugger MCP consolidation; CLI retired; dashboard archived.