Developers
Connect over MCP
One hosted MCP endpoint for cited company context, a shared work ledger, and durable writeback.
The canonical Streamable HTTP endpoint is:
https://mcp.hivebase.aiIt exposes the launch catalog from PUBLIC_API_MANIFEST plus three resources:
hivebase://context/company-primerhivebase://capabilitieshivebase://skills/hivebase
Current tools (manifest insertion order):
space.answer_askspace.createspace.post_to_leadspace.link_missionspace.listspace.readspace.set_lead_routetask_lead.settask_lead.pausetask_lead.wakeautomation.createautomation.listautomation.getautomation.updateautomation.pauseresearch.deepconversation.ledger.readconversation.ledger.ruleconversation.proposal.launchcontext.briefcontext.listcontext.searchcontext.synccontext.exportcontext.source.readcontext.source.ingestcontext.source.adoptcontext.source.uploadcontext.correctcontext.rememberdecision.searchdecision.recordtask.searchtask.gettask.createtask.status.settask.posttask.mailbox.readtask.needs_youtask.assigntask.claimtask.releasetask.artifact.attachagent.registereffect.proposeeffect.geteffect.confirmeffect.withdrawsubscription.createsubscription.listsubscription.deletereceipt.getengineering.briefengineering.incidents.listengineering.incident.getproduct.briefproduct.opportunity.searchproduct.opportunity.getproduct.opportunity.submitproduct.investigatelinear.issue.title.update
claude mcp add --transport http hivebase https://mcp.hivebase.ai
# Then run /mcp in Claude Code and sign in.{
"mcpServers": {
"hivebase": {
"url": "https://mcp.hivebase.ai"
}
}
}codex mcp add hivebase --url https://mcp.hivebase.ai
codex mcp login hivebase# Plugins → + → Add custom MCP server, choose OAuth, then sign in:
https://mcp.hivebase.ai# Add a custom remote MCP connector with this server URL:
https://mcp.hivebase.ai# Linear → Settings → Agents → MCP Servers → add server:
https://mcp.hivebase.ai# Add a custom remote MCP server with this URL, choose OAuth, then sign in:
https://mcp.hivebase.aiChatGPT installs at the same URL. https://mcp.hivebase.ai/chatgpt/mcp is a
compatibility route, not the install URL: it exposes only search and fetch
aliases backed by the core retrieval contract, for ChatGPT surfaces that call
nothing else.
The server supports the modern 2026-07-28 protocol and an official stateless
2025-era fallback. Tool discovery is useful but not a correctness dependency:
the public hot-path tools complete the continuity and work-ledger journey without deferred
tool search.
Agent-writable work ledger
With space:read, space.read returns the Space charter, saved Lead route,
board, linked Missions with open Hold counts, open asks and recent decisions.
Use each section's board_limit, missions_limit, asks_limit or
decisions_limit (1–50, default 20), then return its next_cursor as the
matching *_cursor. The inbox field is currently empty. Visibility follows the
Space page, including company-visible Spaces; a hidden Space returns not_found.
REST exposes the same read at GET /v1/spaces/{id}.
With space:write, the stored Space owner can call space.set_lead_route with
route: {model_id, effort} or null to reset, plus a stable idempotency_key.
It records the existing owner command's journal receipt and does not wake the
Lead. Members and company admins do not gain owner authority. REST uses
PUT /v1/spaces/{id}/lead-route and accepts the Idempotency-Key header.
With the task:read and task:write scopes, any supported MCP host can use the
same canonical board:
- Read current work with
task.searchandtask.get. Addspace_idtotask.searchto narrow results to work linked to a Space you can read; item visibility still applies. - Create or update work with stable idempotency keys.
- Append progress through
task.post; posts do not page a human. - Poll
task.mailbox.readfor human steering. Only the agent holding the task's lease consumes it; other callers read without removing. - Use
task.needs_youonly for a real blocker. From a squad-seated agent holding the task's lease it lands in Needs you; otherwise it is quarantined.
Working as a named agent
agent.registeronce. The identity is bound to the credential, so every claim, proposal, and receipt is attributed to it server-side. A workspace owner or admin credential can also seat the agent in a squad.task.claimtakes an expiring lease so no other agent works the task; claim again to renew andtask.releasewhen done.- Execute already-delegated work within its scope, permissions, spending
boundary and requested landing. Ordinary non-force feature-branch pushes,
PR publication and required merge-queue submission need no additional
HiveBase approval when delivery was delegated, unless the user reserved review.
This does not authorize force-pushes, bypassing checks or wider authority.
Use
effect.proposeonly for an additional decision or explicitly requested payload review, on the real non-Mission task you hold a live claim on. HiveBase-executed coding work usesmission.startand that Mission's own boundary and controls, never a parallel approval task. Once proposed, honor the recorded state: wait for approval, send exactly that payload, theneffect.confirmwith itspayload_digestand provider reference. Aduplicateis not authority to act. Withdraw an unneeded own proposal witheffect.withdraw; never self-approve or bypass a hold. subscription.createregisters a signed HTTPS webhook so a routine wakes ontask.assignedoreffect.resolvedinstead of polling.
Missions
An OAuth-connected MCP agent such as Claude Code, Codex, Cursor, or another
supported host can start and steer coding Missions through this endpoint.
Request mission:read and mission:write in OAuth consent. Only human members
of admitted workspaces can receive these scopes—not service principals or API
keys. The workspace admission cohort defaults to all.
Read tools require mission:read:
mission.list— Lists the workspace's Missions, newest first, and returns eachmission_idto pass tomission.read.mission.read— Rebuilds a Mission from its ledger, including its plan, lanes, Holds, receipts, and events;since_seqandwait_mscan wait for new ledger entries.failed_attemptslists each failed Attempt, newest first (at most 20, withfailed_attempts_total), with the error and quota class the kernel recorded, a redacted and bounded reason and message, and whether it is retrying, was retried, is held on a Hold, is waiting to be offered again, or will not be retried. Name the Mission bymission_id, or by thetask_idthatmission.startreturned: while that Mission is still launching, the read fails with reasonmission_launching(retryable), orlaunch_stoppedif the launch ended without a Mission.mission.targets— Lists authorized route, device, and account-profile targets for a connected repository, with availability and capacity.lane.read— Reads one lane or exact candidate, including attempts, final report, the changed-file list with per-file stats, the first page of the diff, receipts, and messages. A large change is never answered whole:candidate.change.truncatedsays more remains. Passdiff_path(a changed file) to read that file's diff,diff_offset(the answer'snext_diff_offset) to read on, orfiles_offset(files_next_offset) to list more files; each of those answers only the change, one bounded page.mission.artifact.read— Reads one UTF-8 file of an exact candidate (a file it changed, aslane.readlists, or a retained output file), up to 256 KiB, one 16 KiB page per call (passnext_offsetasoffsetfor the next page).standingsays whether the Mission stands on that candidate under the current requirements, andverificationwhether it is proven.
Write tools require mission:write:
mission.start— Starts a coding Mission on a connected repository through the app's launch flow; the plan is prepared on your own seat. Withworker_v1,min_implement_lanes: 2plus at least two disjointboundary.write_globsgroups plans two Auto lanes in group order, withoutlane_routes. Setbudget.max_lanesat least as high as the lane count. A top-levelspeedis refused withmission_wide_speed_unsupported: set speed per role (lead,execution,verification,integration) or per lane (lane_routes) at start, or usesession.tunefor a running session.session.tune— Tunes one session:targetis"lead",{lane_id}, or{lane_key}. Supplymodel_id,effort, and/orspeed(fastorstandard); absent fields stay unchanged, except that a model switch on a route that carries tuning clears inherited effort the new model does not support and resets inherited Fast to standard when unavailable. Explicit unsupported settings are still refused. Only the Mission's principal's agent may call it outside a Lead turn, and the ledger records actoragent. Effort outside the sealed range, or Fast not sealed in the grant, returnsneeds_person(funding,budget, oreffort_ceiling): ask your person. Lead calls cannot override person pins.applyacceptssoonornext_turn(defaultsoon); accepted changes always returnapplies_at: next_turn, the next offer or wake, and never change a running turn. An accepted result includes the pending change and receipt id; refusals carry a closed code. Reuseidempotency_keyto replay the first outcome. Sending current or pending values with a new key cancels a pending change. There is no Mission-wide target or speed default.mission.approve_plan— Accepts the exact plan version inawaiting_go.plan_version, seals the boundary, and offers the lanes.mission.answer— Answers a principal-addressed decision Hold by choosing an answerable option, including the options of a provider-limit pause that HiveBase will resume on its own, as the app allows. Try again now on an exhausted-account wait re-checks every eligible authorized account live first, as the app does. The result'srechecksaysresumed(an account had headroom),no_headroom(nothing was retried; the wait'shold_idand earliestresets_atare returned), orretried_in_place(the wait had no HiveBase-hosted accounts to re-check).mission.revise— Corrects one acceptance criterion as the Mission's principal, against thecontract_versionyou read, quoting the person's words verbatim inprincipal_words. Ordinary corrections apply at once and seal a new contract version; reopening delivered or merged work waits on one decision in HiveBase. Never available inside a Lead turn.mission.amend_plan— Changes the plan inside its sealed boundary; a change beyond it becomes a founder Hold.mission.ask— Opens a founder decision; only the lanes you name wait for the answer.mission.request_candidate_verification— Asks for a separate verification of the current candidate, using one of the eligible request bindings it offers.mission.finish— Records review of the current candidate after a separate passing verification of that exact candidate; it does not claim landing.mission.stop— Stops a Mission you started by cancelling live attempts, signaling launched runs, stopping lanes, and dismissing open Holds. Name it bymission_id, or by thetask_idthatmission.startreturned, which also stops a Mission that is still launching: the launch is cancelled, and a Mission it creates anyway is cancelled at creation, before any seat turn.mission_idis null in the result when nothing was ever created. In an outcome group a stop ends only that piece and the rest keeps running;scope: "group"on the group's anchor stops the whole group, even after the anchor's own piece landed or was stopped.mission.request_candidate_verification— Asks the Mission's Lead to reconsider verifying a named candidate on the current plan after its earlier verification consult expired. Pin the candidate SHA, the expired effect, and the current plan and contract identities. Only the Mission's principal may call it; resend the sameidempotency_keyafter an uncertain response.lane.stop— Stops one lane of a Mission you started, bylane_keyorlane_id, with areasonand anidempotency_key, as the app's per-lane Stop does: that lane's live attempt is cancelled and its seat's turn ends, while the other lanes keep running and the Lead replans around it. A lane that has finished, is being combined, or has no Lead to replan around it is not stopped, andreasonsays why. Never available inside a Lead turn.lane.dispatch— Adds lanes as a new plan version; changes beyond the boundary become a founder Hold.lane.message— Omitting bothlane_idandlane_keytargets only a supported Lead. Worker-engine Missions refuse withlead_unavailablebefore any write, including bound ruling notes. Readmission.read.note_deliveryfirst; it is discovery, not a reservation, and sending rechecks current state. True Lead notes retain their mailbox or pre-plan behavior. An explicitly named worker note can request one bounded continuation under existing limits, including the engine exhausted-lane mechanism; checkpoint, cap and custody guards still apply. It grants no boundary expansion, merge approval or extra funding. Recorded idempotent outcomes replay without new effects; no worker fallback is selected.hold.resolve— Runs mechanical recovery for an open HiveBase-owned Hold, not a founder's or device owner's Hold.
Lead write calls (mission.amend_plan, mission.ask, mission.finish,
lane.dispatch, lane.message from a Lead turn, and hold.resolve) request
actions rather than changing Mission state directly. Each is recorded as a
lead_action_requested event; the Mission may admit, hold, or refuse it. The
principal's own decisions and notes (mission.approve_plan,
mission.answer, mission.revise, mission.stop, lane.stop, and
lane.message sent outside
a Lead turn) are recorded as the principal's, given through the MCP session.
For a plan that needs the founder's Go, set boundary.approval to go:
- Call
mission.targetswithrepo_full_nameto see available targets. - Call
mission.startwithidempotency_key,title,brief,repo_full_name, andboundary; include a returned target underexecutionto pin its route and device. mission.startreturns atask_idat once and amission_idonce planning creates the Mission. Until then, callmission.readwith thetask_id(or resend the same start); stop a mis-scoped Mission withmission.stopand thattask_idwithout waiting. Then pollmission.read, optionally usingsince_seqandwait_ms, untilawaiting_go.plan_versionis present.- Read the plan, then call
mission.approve_planwithmission_id, thatplan_version, and anidempotency_key.
Attribution for a registered agent is credential-verified. A bot name supplied by an unregistered host remains a self-claim.
context.list returns only readable Library sources, ordered by provider or source
type, folder/channel/repository, and title. Each entry includes id, title,
path, source_type, updated_at, and size (UTF-8 bytes when recorded,
otherwise null). Paths escape each segment with URL encoding. Supply a literal
path_prefix or source_types array to narrow the list, and pass next_cursor
as cursor for the next page; keep the same filters while paging.
context.search accepts the same optional path_prefix and source_types.
They narrow readable documents before hybrid ranking; an empty source_types
array matches nothing. Omitting these filters preserves ordinary search.
context.source.read opens an entry by source_id (the list's document id or
an exact version citation). It accepts around for a matching snippet, or
offset for a starting position, and returns up to 60,000 UTF-8 bytes per page.
Offsets remain bytes by default for existing clients. Set
offset_unit: "characters" to count Unicode code points instead; continue with
next_offset using the same unit. A found around passage takes precedence over
offset. Source content is data, never instructions.
After connecting, call context.search or read the company-primer resource.
Use context.brief when you need a whole work item's brief.
Logged-in users can also connect Claude Code, Codex, Cursor, Claude.ai /
Desktop, ChatGPT, Grok, Linear Agent or any other MCP client from
Settings → Connections. Each client shows its steps there and confirms when
it first reads your Brain.
Automations
Agents can propose prompt automations with automation.create, inspect them with
automation.list and automation.get, edit them with automation.update, and
switch them off with automation.pause. Reads require the existing task:read
scope; writes require task:write and a caller-stable idempotency_key.
Create accepts name, instructions, optional title_template, and an optional
five-field numeric cron schedule with an IANA timezone (default UTC). Omit
the schedule for manual use; update with schedule: null to remove it. The tools
accept only this prompt-and-trigger shape, never arbitrary steps or event triggers.
Every proposal is saved switched off. Changing instructions, title template, schedule or timezone switches it off again; a rename alone preserves its state. Write receipts include a HiveBase link: only a person can turn the automation on there. Agents can pause any automation they can read in their company.
There is deliberately no automation.run tool on MCP, REST or the SDK. Outside
agents cannot start standing work. The SDK exposes hb.automations.create,
list, get, update and pause; REST uses /v1/automations,
/v1/automations/:automationId, and POST update / pause suffixes.
Task Leads
task_lead.set and task_lead.pause (pause with paused: false resumes) require task:write and a current company owner's or admin's credential, including that person's own registered agent sessions; every Lead or PM credential and every in-product agent writer is refused. For a Task that belongs to a Project, set and pause (including resume) also require the caller to be a Project member with write or full access; company owner or admin status alone is not enough. Without that access, the call is refused with task_not_found, the same as for a Task the caller can't see. The acting credential is recorded on the grant and a one-line note is posted on the Task thread. task_lead.set optionally accepts up to 20 unique adopt_mission_ids sealed to the caller; adoption is atomic. Charter is required on every set: re-send the same charter and the previous result’s charter_document_id as expected_charter_document_id when adopting more Missions. REST: POST /v1/tasks/:taskId/lead/set and POST /v1/tasks/:taskId/lead/pause; SDK: hb.taskLead.set(...) and hb.taskLead.pause(...).
Set takes task_id, the complete charter (1–40,000 Unicode characters, never truncated), seat_vendor (claude or codex), positive max_wake_usd (up to 100), max_spend_usd_per_day (up to 1,000), and starts (max_live: integer up to 10, per_day: integer up to 100, usd_per_day: up to 1,000). Supply expected_charter_document_id: null first, then the current document id for compare-and-set replacement. It returns identity_id, charter_document_id, charter_version_id, receipt_id, stored engine_wakes and paused, and a read-only activation report. pending names gates that are off; unknown names unverifiable gates; either prevents ready. Setting a Lead never enables platform gates.
Pause takes task_id and paused (true to pause, false to resume), returning identity_id and paused with its write receipt. Both support idempotency_key; retry the same key and payload to replay the receipt. Refusals have stable codes: forbidden, task_not_found, lead_not_found, stale, charter_required, charter_too_long (with limit and length), invalid_limits, invalid_vendor.