MCP tool reference

"core","true","true","Returns recent API calls made by this token — tool name, WU cost, HTTP status, timestamp, and latency. Use to audit WU spend, verify your agent is calling the right tools, or debug unexpected failures. Free (0 WU)."

"admin","true","true","Generates a new API key inheriting the current key's scopes and revokes the current one after a configurable grace window (default 10 min, in-flight requests still complete). Returns the new key exactly once — store immediately. Use for periodic key rotation or suspected compromise."

"core","true","true","Returns details about the currently authenticated token: user ID, company ID, granted scopes, token kind (api_key vs oauth), rate limit, WU balance, and key label. Free (0 WU). Use to verify your API key is working and inspect what permissions you have."

"core","true","true","What needs human attention right now — supervisor approvals, stale tasks, blocked work, and pending Brain proposals. Call at session start before taking writes. Free (0 WU)."

"core","true","true","PREFERRED ENTRY POINT for external agents — one call returns grouped evidence for a topic: source-backed context snippets, recent decisions, and overlapping in-flight tasks, with partial-failure metadata when one slice cannot load. Use this whenever you'd otherwise chain 2+ read calls to assemble context. Toggle include_decisions / include_tasks to narrow scope. Free (0 WU)."

"core","true","true","Incremental sync: list workspace entities changed since a timestamp (tasks, Brain docs, decisions, signals, projects). Use after being offline or for changelog generation — pair with context.attention for what needs action now. Free (0 WU)."

"core","true","true","Fetch the relationship graph around an entity — related docs, tasks, signals, and decisions. Use after context.search or task.get to see connected work before acting. Free (0 WU)."

"core","true","true","Record a lightweight observation into the company knowledge pipeline (signals → Brain extraction). Use for session takeaways that should inform future agents — lower ceremony than context.save. OAuth writes require connector confirmation. Free (0 WU)."

"core","true","true","Save a durable Brain document from an external agent session (title, body, category, confidence). Use for substantive knowledge worth citing later — use context.observe for lighter-weight notes. OAuth writes require connector confirmation. Free (0 WU)."

"core","true","true","Search workspace context for source-backed snippets on a topic — the granular evidence retrieval primitive. For a complete brief that also pulls decisions + related tasks in one call, use context.brief instead. Returns extractive snippets with source metadata; it does not generate an answer. Free (0 WU)."

"core","true","true","Walk the decision graph from a root decision, following both supersession (later decisions that replaced this one) and dependency (decisions this one builds on) edges. Use to reconstruct the chain of strategic evolution or check whether a decision is still current. Returns nodes + typed edges, depth-capped (1-6, default 3). RLS-filtered. Free (0 WU)."

"core","true","true","Backfill the outcome of a past decision — set outcome_status (success, failure, mixed) and outcome_summary describing what actually happened. Use this when a decision recorded via decision.record has played out and you want to close the loop for the WS-7 calibration loop. The outcome feeds adaptive learning: future decisions get better recommendations. For marking a decision as superseded by a newer one, use decision.supersede instead. Free (0 WU)."

"core","true","true","Record an immutable decision event with structured context, judgment, and entity references. Decisions are embedded for hybrid search via decision.search and strategic decisions auto-emit a Brain signal. Use this to build an auditable decision log that the AI can reference in future context assembly. 2 WU."

"core","true","true","Search past decisions using hybrid retrieval — semantic similarity combined with structured filters (category, significance, surface, entity type, date range). Or pass `ids` to hydrate specific decisions by ID (skips semantic search; up to 50). Use this to find precedent before making new decisions, or to assemble context for strategy and planning. For recording new decisions, use decision.record. Free (0 WU)."

"core","true","true","Mark a past decision as superseded by a newer one. Use when a later decision invalidates or replaces an earlier strategic call (pricing reversal, hiring strategy shift, product direction change). The supersession chain becomes navigable via decision.graph for downstream agents and UI. Both decisions must already exist in the workspace decision store and belong to the same company. Free (0 WU)."

"coding","true","true","List all GitHub repositories connected to this workspace — returns repo full names, default branches, primary languages, and the last indexing timestamp. Use this before repo.tree or repo.search to find the correct repo_full_name. Repositories are indexed for semantic code search using voyage-code-3 embeddings. Free (0 WU)."

"coding","true","true","Semantic search across all indexed source code in connected repositories using voyage-code-3 embeddings. Returns ranked code chunks with file paths, line ranges, and similarity scores. Use this to find relevant implementations before writing code or answering architecture questions. Prefer this over grep-style search for conceptual queries. 1 WU (repo_search)."

"coding","true","true","Look up a specific symbol (function, class, type, or variable) across all indexed repositories by exact or partial name. Returns the file path, line number, signature, and a short surrounding context. Use this when you know the symbol name but not the file location — faster than repo.search for exact lookups. Free (0 WU)."

"coding","true","true","Get the file and directory tree for a connected repository up to a configurable depth. Use this to understand the project structure before reading specific files or running repo.search. Returns file paths with language hints derived from extensions. Free (0 WU)."

"admin","true","true","Creates a webhook subscription that POSTs a signed JSON payload to your callback URL whenever the specified events occur. This is the canonical subscription API — use this instead of the older webhook.create. Returns a signing_secret exactly once — store it immediately. Use the X-HiveBase-Signature header to verify payloads on your server. After creating, use subscription.test to fire a test ping and verify your endpoint."

"admin","true","true","Deactivates a webhook subscription. No further events will be delivered to its callback URL. Free (0 WU)."

"admin","true","true","Lists all active webhook subscriptions for this company — includes ID, callback URL, event types, label, failure count, and last delivery timestamp. Free (0 WU)."

"admin","true","true","Fires a test 'ping' event to the subscription's callback URL to verify your endpoint is reachable and correctly verifying signatures. Returns accepted immediately — check your server logs for receipt. Free (0 WU)."

"core","true","true","Add a plain-text comment to a task's activity feed. Use this for status updates, notes, or follow-up context — not for changing task fields (use task.update for that). Comments appear in the task's timeline alongside agent activity and system events. Free (0 WU)."

"core","true","true","Create the task object, with optional policy-aware execution. Use execution.mode=none to only create, auto to let workspace policy decide, or now to start execution immediately through HiveBase/cloud agents. Check task.list first to avoid duplicates."

"core","true","true","Get a single task by ID with full metadata, assignees, comments, and enrichment context. Use this after task.list to drill into a specific task. To modify it, use task.update or task.comment.add. Free (0 WU)."

"core","true","true","List tasks with optional filters (status, assignee, project, inbox status). Use this to find existing tasks before creating duplicates with task.create. For full detail on a specific task, follow up with task.get. Free (0 WU)."

"core","true","true","Find overlapping in-flight or recent tasks before starting duplicate work. Pass task_id for title-token overlap or q for text search. Use with context.search when planning from an external IDE. Free (0 WU)."

"core","true","true","Approve a gated execution plan for a task that is awaiting plan approval. This starts the queued cloud fleet or single-task execution subject to workspace policy."

"core","true","true","Cancel the active execution run for a task. This marks active agent sessions as cancelled and leaves the task available for a later run or manual follow-up."

"core","true","true","Get the current execution status for a task, including the latest agent session, fleet metadata when present, PR URL, and whether a plan approval gate is waiting."

"core","true","true","Poll execution milestones for a task run. For cloud code fleets this returns fleet milestones and is cursor-resumable; for single-agent tasks it returns the latest session snapshot."

"core","true","true","Start execution for an existing task. For normal code tasks this delegates the task to a HiveBase coding agent; for cloud fleets, prefer task.create with execution.mode=now so the execution parent is created by the unified pipeline."

"core","true","true","Update one or more fields on an existing task (name, status, priority, assignees, dates, etc.). Use task.get first to read current values before patching. For adding discussion to a task, use task.comment.add instead. Free (0 WU)."

"core","true","true","Look up your HiveBase workspace and get a magic link to open it in the browser (for OAuth-based agents like Claude Desktop and ChatGPT) or a direct workspace URL (for static-key agents like Cursor). Free (0 WU). Idempotent — calling within a 24h window for the same agent reuses the same magic link. For brand-new users with no workspace yet, the cold-start path is OAuth: agents that hit this tool before /authorize completes will not have a token. Call workspace.status afterward to check whether onboarding is finished."

"core","true","true","Canonical onboarding-readiness check for HiveBase. Returns is_onboarded (boolean), integrations_connected (list of platform strings like 'slack', 'linear', 'github'), workspace_url, and workspace_name. Free (0 WU). Safe to poll. Call this after workspace.lookup to decide whether to prompt the user to finish setup or proceed with their request."