MCP — tools

The bichito MCP server exposes 18 tools split into three groups: install assist (no auth), read (one of the read:* scopes) and mutate (one of the write:* scopes). This page lists them all.

When you don't need every tool, mint a token without the corresponding scope — fewer tools means a smaller surface for the AI to reason over and less risk if the token leaks.

Tokens carry a hive binding chosen at mint time (see Scopes → Scope across hives). Account-wide tokens can pass any team_id to a tool that takes one; hive-scoped tokens MUST match their bound team — passing a different one returns 404.

Install assist

These three tools don't need an MCP token; they work with BICHITO_API_KEY alone. Use them when you want the AI to drop the widget into a project.

get_install_snippet

Returns the install snippet for a given framework, with your API key already filled in.

• Inputs: framework — one of html, react, next, vue, astro, wp.
• Returns: { target_file, code }. The AI then opens target_file and pastes code.
• Required scope: none (uses the project key in BICHITO_API_KEY).

detect_framework

Reads package.json (or index.html for static sites) at the repo root and guesses which framework the project uses.

• Inputs: repo_root — absolute path to the project root.
• Returns: one of the framework strings above, or unknown if nothing matches.
• Required scope: none — runs locally.

verify_api_key

Pings the bichito API to confirm the configured BICHITO_API_KEY works, before the AI pastes it anywhere.

• Inputs: none.
• Returns: { ok: true, project_id, project_name } on success; an error otherwise.
• Required scope: none.

Read

list_honeycombs

Lists every honeycomb (project) the token's user owns.

• Required scope: read:honeycombs.
• Returns: array of { id, team_id, name, description, created_at }.

list_bugs

Lists bichitos with optional filters.

• Inputs (all optional): status, severity, search, honeycomb_id, limit (default 50, max 200), offset.
• Returns: array of bug summaries.
• Required scope: read:bugs.

search runs through the same Postgres FTS as the dashboard — see Inbox → Search for the matching rules.

get_bug

Returns one bichito's full detail (everything the dashboard sidebar shows).

• Inputs: bug_id.
• Returns: the full bug payload including comments and labels.
• Required scope: read:bugs.

get_stats

Cross-team summary: open count + breakdowns by severity and status.

• Inputs: none.
• Returns: { teams: [...], open_count, by_severity, by_status }.
• Required scope: read:teams.

list_labels

Lists the labels available in a hive.

• Inputs: team_id.
• Returns: array of { id, name, color, created_at }.
• Required scope: read:labels.

Triage

resolve_bug

Marks a bichito as resolved. Idempotent — calling on an already-resolved bichito is a no-op.

• Inputs: bug_id.
• Required scope: write:bugs.

mark_spam

Marks a bichito as spam (drops it out of the triage queue).

• Inputs: bug_id.
• Required scope: write:bugs.

assign_me

Assigns the bichito to the user who owns the MCP token.

• Inputs: bug_id.
• Required scope: write:bugs.

comment_on_bug

Adds a comment on a bichito.

• Inputs: bug_id, body (1–10,000 chars).
• Required scope: write:bugs.

update_bug

Sets status and/or severity. Mutually optional — at least one must be provided.

• Inputs: bug_id, optionally status (open / in_progress / resolved / closed / wont_fix), optionally severity (low / medium / high / critical).
• Required scope: write:bugs.

Idempotent: a field already at the requested value is skipped, and the SSE fan-out only fires for fields that actually changed.

Labels

create_label

Creates a new label in a hive.

• Inputs: team_id, name, color (hex #RRGGBB).
• Required scope: write:labels.

update_label

Renames or recolors a label. At least one of name / color must be set.

• Inputs: label_id, optionally name, optionally color.
• Required scope: write:labels.

delete_label

Deletes a label. Cascades to every bichito it was attached to (the label is removed from each).

• Inputs: label_id.
• Required scope: write:labels.

attach_label

Attaches a label to a bichito. Pass either label_id or label_name (the AI usually has the name in hand).

• Inputs: bug_id, optionally label_id, optionally label_name.
• Required scope: write:bugs.
• Idempotent: attaching an already-attached label is a no-op.

detach_label

Removes a label from a bichito.

• Inputs: same as attach_label.
• Required scope: write:bugs.
• Idempotent.

Errors

Every tool returns an error response in the same shape:

{
  "error": "...human message..."
}

Common cases:

• 401 Invalid MCP token — your BICHITO_MCP_TOKEN is wrong or revoked.
• 403 scope required: write:bugs — your token doesn't carry the scope this tool needs.
• 404 Not found — the resource (bichito, label, honeycomb) belongs to another user, or doesn't exist. We mask 403s as 404s for resources you don't own to avoid leaking IDs.
• 429 Too Many Requests — same per-IP limits as the dashboard. Back off and retry.

The MCP package surfaces these errors to the AI as plain text so it can self-correct (e.g. "The label 'regression' doesn't exist — let me create it first.").