MCP tools

The current stable Bee release provides a local stdio MCP server. Start it in the intended checkout with bee mcp serve; your MCP client launches this process and exchanges JSON-RPC over stdio. bee mcp serve --discovery exposes a compact search/schema/invoke view over the same fixed tool catalog. A separate bee design mcp --stdio --root /absolute/path/to/checkout host serves the four design/visual read tools. Restart a long-lived server after upgrading Bee; bee --version should match the documentation version.

The core host fixes its checkout and selected Bee instance at startup. Its skill reads need an initialized Bee and configured skill bridge. Plan reads need an existing live native collaboration binding; the MCP host never joins, claims or launches work. Context packets and local artifact reads can work offline. The local artifact CLI must write under the selected instance root’s artifacts directory for the MCP artifact tools to find it. MCP tool responses are bounded; an output-budget error means no partial evidence was delivered. JSON-RPC frames are limited to 512 KiB and tool results to 256 KiB. Returned source/skill text is data, not authority or proof that an agent read it.

Tool	What it returns	Effect and main constraint
bee_skill_search	Provider search matches for query, limit 1–20	Read only; configured bridge required. Matches are not read receipts.
bee_skill_get	One complete skill body by path	Read only; does not resolve prerequisites. Over 256 KiB fails.
bee_skill_resolve	Complete dependency-first chain by path	Read only; omitted bodies/oversized chain fail. Read every returned body.
bee_plan_show	One exact planId in current checkout/space	Read only; rechecks live native binding, never joins or refreshes it.
bee_plan_next	Ready contracts for planId, limit 1–5	Read only; hasMore/omitted counts disclose bounded projection. Never claims steps.
bee_context_packet	Selected source packet from manifestJson	Read only; offline, no graph refresh or provider call. budgetBytes 512–262144 covers the entire tool result.
bee_artifact_search	Literal line matches from retained artifacts	Read only; text, limit, offset, budgetBytes; counts precede paging. No ingest/source reread.
bee_artifact_query	Filtered/projected JSON artifact rows	Read only; id, queryJson (≤64 KiB), budgetBytes; no SQL/code evaluation.
bee_artifact_read	Base64 pages of verified exact bytes	Read only; id, offsetBytes, lengthBytes 1–65536. Join pages and check sourceSha256.
bee_representation_encode	Complete bee-json-v1 packet for json	Read only; optional encoding, budgetBytes. Preserves JSON values/number spellings, not whitespace/order.
bee_representation_decode	Complete JSON values from packet	Read only; bounded expansion. Oversized output fails without clipping.
bee_context_compress	Optional local prose compression result	Local write possible: may retain original and metadata. Requires enabled compression and contentKind: "prose"; ratePercent 10–90.
bee_compression_recover	Exact retained prose and verified sha256	Read only; original must exist in this instance; budgetBytes applies.
bee_design_list	Imported bundle IDs, states and dependencies	Read only in fixed checkout; no HTML dump. Bundle path is relative to host root.
bee_design_slice	Source/dependency context for one id	Read only; budgetBytes 512–65536. complete: false means implementation context is incomplete.
bee_design_verify	Hash/dependency and mapping integrity	Read only; not screenshot comparison or design approval.
bee_visual_report	Assessment of existing spec and evidence	Read only; no browser launch. Caller evidence is untrusted; acceptance: false.

The last four tools are exposed by bee design mcp --stdio --root /absolute/path/to/checkout (the core bee mcp serve hosts the other 13). See the design workflow for import/visual setup. Source mutation, design import/map, browser capture, compression settings/setup, artifact ingestion, provider calls and plan writes remain CLI operations, not MCP tools.

A source packet call

Pass a JSON selection manifest as the manifestJson string. Each selection has an id, repository-relative path, representation (index, outline, or body), and optional symbol/range/hash, required, and dependsOn. Select only what the task needs:

{
  "selections": [
    {"id": "entry", "path": "src/Bee/Program.cs", "representation": "outline", "required": true}
  ]
}

Call bee_context_packet with that serialized object and budgetBytes: 32768. The host uses a 15-second deadline and will return needs_refinement when required content or metadata cannot fit. Narrow selections or increase the budget within the limit; never interpret omitted required content as read. See context and provider tools for the matching CLI packet workflow.

Recover exact artifact bytes

Use bee_artifact_read with the id returned by artifact add. Start with offsetBytes: 0; follow nextOffsetBytes until it is null. Each response identifies id, sourceSha256, sourceBytes, offsetBytes, nextOffsetBytes and base64. Concatenate decoded pages in offset order, then compare SHA-256 to sourceSha256. The MCP tool writes no recovery file. The CLI artifact get can write a new file if you explicitly need one.

Effect and trust boundaries

The 16 tools other than bee_context_compress are annotated read only. Compression is annotated as a write because a successful call can persist a hash-verified original and local metadata, even though its main response is text. Disabled compression returns the original. It accepts at most 64 KiB/8,192 local tokenizer tokens, has no implicit setup/download/cloud fallback and always marks lossy output semanticRisk: true. Use compression recover to check the original.

The design MCP host accepts only paths within its fixed root. Design list/slice/verify responses use schemaVersion, ok, data or error, trusted: false, and acceptance: false. bee_visual_report instead returns a diagnostic assessment with decision, findings, limitations, trusted: false, and acceptance: false. A successful integrity read does not approve a design. Skill calls contact the configured skill bridge and are marked open-world because they read an external provider. Plan reads identify owner-reported state; reported_complete is still an owner report, not independent QA. For all tools, a successful call proves only that this read or local operation returned; verify any claimed task outcome against the actual files, process and tests.