MCP endpoints

The MCP package is a thin client over a dedicated set of HTTP endpoints under /api/v1/mcp/.... Every endpoint:

• Authenticates via X-MCP-Token: mcp_… (see Auth).
• Checks a scope (or set of scopes) against the token's allowance.
• Returns the same JSON shape as the dashboard's equivalent route.

You don't need to call these directly if you use the npm package — but they're public and stable, so feel free to script against them from any language.

Why a separate router?

Cleanliness. Mixing JWT-based and MCP-based auth on the same routes would force every handler to figure out which auth mode it's in, and we'd lose the per-scope check that's the whole point of MCP tokens. Keeping them in their own namespace lets us evolve scopes / rate-limits independently.

The endpoints

Bichitos

GET    /api/v1/mcp/bugs                          List, with filters. Scope: read:bugs.
GET    /api/v1/mcp/bugs/{id}                     Detail. Scope: read:bugs.
PATCH  /api/v1/mcp/bugs/{id}                     Set status / severity. Scope: write:bugs.
POST   /api/v1/mcp/bugs/{id}/resolve             Mark resolved. Scope: write:bugs.
POST   /api/v1/mcp/bugs/{id}/spam                Mark spam. Scope: write:bugs.
POST   /api/v1/mcp/bugs/{id}/assign-me           Assign to the token's user. Scope: write:bugs.
POST   /api/v1/mcp/bugs/{id}/comments            Comment. Scope: write:bugs.

PATCH /bugs/{id} body:

{ "status": "in_progress", "severity": "high" }

Both fields optional; at least one must be provided.

Honeycombs

GET    /api/v1/mcp/honeycombs                    List. Scope: read:honeycombs.

(Create / update via MCP isn't exposed yet — let us know if you want it.)

Stats

GET    /api/v1/mcp/stats                         Cross-team summary. Scope: read:teams.

Returns { teams, open_count, by_severity, by_status }.

Labels

GET    /api/v1/mcp/teams/{team_id}/labels        List. Scope: read:labels.
POST   /api/v1/mcp/teams/{team_id}/labels        Create. Scope: write:labels.
PATCH  /api/v1/mcp/labels/{label_id}             Rename / recolor. Scope: write:labels.
DELETE /api/v1/mcp/labels/{label_id}             Delete (cascade). Scope: write:labels.

POST   /api/v1/mcp/bugs/{bug_id}/labels          Attach. Scope: write:bugs. Body: { label_id?, label_name? }.
DELETE /api/v1/mcp/bugs/{bug_id}/labels?label_id=...&label_name=...
                                                 Detach. Scope: write:bugs.

label_name is a convenience: pass either the id or the name (lookup happens in the bug's team).

Install assist

These don't need an MCP token — they use the project X-API-Key for verify_api_key, and run locally for the others.

The npm package implements them client-side; there's no remote endpoint for detect_framework or get_install_snippet.

Activity

Mutations through the MCP endpoints record via: "mcp" in the activity payload — the timeline UI distinguishes them. Same SSE fan-out as dashboard mutations: open inbox tabs see the changes live.

Errors

Standard error shape (see Errors). Most common:

• 401 Invalid MCP token — X-MCP-Token missing, malformed, or revoked.
• 403 This MCP token does not have the 'X' scope — token is valid but doesn't carry the scope the route needs.
• 404 Not found — the resource is in a team / honeycomb the token's user doesn't own.