MCP tools reference

Derived from the honeycomb knowledge base, captured 2026-06. Tool names and behavior are transcribed from the integrations and MCP specifications. The knowledge base names the tool surface and describes each tool's behavior; it does not publish every tool's full zod input schema. Where an exact field list is not specified, that is noted inline. Confirm the precise input and output schemas against your installed version's MCP server definition.

honeycomb exposes a Model Context Protocol (MCP) server so that coding assistants which speak MCP can ask for memory operations explicitly, as native tools in their own tool list. The server is registered into each MCP-speaking assistant during honeycomb connect, so there is no separate "add an MCP server" step.

Every tool handler is a thin client of the honeycomb daemon (default 127.0.0.1:3850): the tool states what is wanted, and the daemon does the real work and is the only process that talks to the storage backend. MCP traffic is stamped with actor headers so it is identified and scoped like any other client of the daemon. Tool input schemas are defined with zod (the MCP server pins the v3 line for SDK compatibility).

The server binds two transports against one MCP server: a stdio transport when run as a subprocess (node mcp/bundle/server.js), and a streamable-HTTP transport served at /mcp on loopback for HTTP-speaking clients.

#How the tools are grouped

The tool surface splits along a deliberate seam between resolving a known reference and mining for unknown matches:

• Read / resolve tools run deterministic lookups. They return exactly the row asked for; they do not rank.
• Search / mine tools run hybrid lexical-plus-semantic recall, fused by reciprocal-rank, with an honest degraded flag when the semantic path is unavailable.

The tools are organized into clusters by prefix:

The tool names above are transcribed verbatim from the knowledge base. The per-tool documentation below carries the honest name, purpose, input shape, output shape, side effects, and an example for the tools the knowledge base describes in enough detail. Where the knowledge base names a tool but does not detail its full schema, the entry says so plainly.

#Memory cluster

#memory_store

Purpose. Write a memory through the daemon. This is the explicit "remember this" tool an agent calls when it wants a fact persisted.

Input shape. A memory body, plus optional metadata such as importance and tags (the SDK equivalent takes importance and tags). The exact zod field names are not published in the knowledge base; confirm against the installed server definition.

Output shape. A confirmation that the memory was stored (the daemon returns the stored memory's identity). Confirm the exact field shape against your installed version.

Side effects. Writes. A new row lands in the distilled-memory path through the daemon; the daemon de-duplicates by content hash, so storing the same content twice returns the existing memory rather than inserting a duplicate.

Example

{ "content": "we deploy from the release branch, never from main", "importance": 0.9, "tags": "deploy" }

#memory_search

Purpose. The hybrid recall tool: lexical plus semantic candidate collection over the memory tables, fused by reciprocal-rank and shaped (dedup on by default), scoped to what the calling agent is allowed to see. Reach for this on a cold query when you do not already hold a reference.

Input shape. A query string, and (per the SDK equivalent) an optional result limit. Confirm the exact field names and any additional filters against the installed server definition.

Output shape. A ranked, shaped result set. Each hit carries its provenance (source and scope). Recall reports degraded: false when the semantic arm actually ran and degraded: true only on a genuine fallback (embeddings off, model still warming, embed daemon unreachable, a timeout, or a malformed response); in every degraded case it still answers from the lexical arms. Recall never throws and never hangs on the embedding path.

Side effects. Read-only. Runs SELECT queries against the memory tables; writes nothing on the recall path. (Recall may record redacted access tracking on the daemon side, but it creates no memory.)

Example

{ "query": "how do we deploy", "limit": 5 }

#memory_get

Purpose. Resolve a single memory by its path or id. Deterministic: returns exactly that row, no ranking.

Input shape. A memory identifier (path or id). Confirm the exact field name against the installed server definition.

Output shape. The single memory row, or an empty result when no row matches.

Side effects. Read-only.

#memory_list

Purpose. List memories within the caller's scope.

Input shape. Optional scope or filter parameters. Not fully enumerated in the knowledge base; confirm against the installed server definition.

Output shape. A list of memory rows, scoped to what the agent may see.

Side effects. Read-only.

#memory_modify

Purpose. Change an existing memory.

Input shape. A target memory and the change, plus a required reason argument, because every mutation is audited.

Output shape. A confirmation of the change. Confirm the exact field shape against your installed version.

Side effects. Writes. The change lands as an append-only, version-bumped write (the storage layer does not mutate in place), and the proposal is recorded to the memory history audit trail.

#memory_forget

Purpose. Remove a memory from recall.

Input shape. A target memory and a required reason argument (audited, like memory_modify).

Output shape. A confirmation. Confirm the exact field shape against your installed version.

Side effects. Writes. Implemented as a soft delete (an is_deleted flag) rather than a hard row delete, so the audit trail survives. This is an expensive, abuse-prone operation and carries a tighter rate limit in team and hybrid modes.

#memory_feedback

Purpose. Record feedback on a recalled memory (signal that a result was useful or not), feeding the recall-quality loop.

Input shape. A target memory and the feedback signal. Not fully enumerated in the knowledge base; confirm against the installed server definition.

Output shape. A confirmation.

Side effects. Writes a feedback or telemetry record on the daemon side; creates no memory.

#Browse cluster (virtual filesystem)

These three tools are the read-only browse surface backed by the memory virtual filesystem: the team-shared database presented as an ordinary directory. They let an agent explore memory with familiar file operations.

#honeycomb_search

Purpose. Search the memory browse surface. Routed to the daemon's hybrid lexical-plus-semantic search over the sessions and memory tables. This is also the "mine" half of the session-priming pull path.

Input shape. A query string (the search term). The knowledge base does not publish the full field list; confirm against the installed server definition.

Output shape. Returns text content: matching paths and snippets. On no match it reports that there were no matches for the query, and large result sets carry a truncation notice pointing at narrower queries. Confirm the exact wording against your installed version.

Side effects. Read-only. Runs scoped SELECT queries; creates nothing.

Example

{ "query": "release branch deploy" }

#honeycomb_read

Purpose. Read the content at a memory path. Deterministic resolve, not a search.

Input shape. A path to read.

Output shape. Returns text content: the full body at that path, or a "no content found at <path>" message when nothing exists there. A session path is transparently concatenated from its many underlying event rows.

Side effects. Read-only.

Example

{ "path": "/summaries/alice/2026-06-20-deploy.md" }

#honeycomb_index

Purpose. List an index of the browse surface: the most recent memory summaries and raw sessions, so an agent can orient before reading or searching.

Input shape. Optional scope or prefix. Not fully enumerated in the knowledge base; confirm against the installed server definition.

Output shape. Returns text content: a two-section listing (memory summaries and raw sessions) with a per-section truncation notice pointing at search for older rows.

Side effects. Read-only.

#Sessions cluster

#session_search

Purpose. Search session transcripts. Can infer parent lineage from a child session key, which is how OpenClaw resolves a parent session.

Input shape. A query and, optionally, a session key. Confirm the exact field names against the installed server definition.

Output shape. Matching session rows or transcript slices, scoped to the caller.

Side effects. Read-only.

#session_bypass

Purpose. A session-scoped control tool the knowledge base names within the sessions cluster. Its precise contract is not detailed in the knowledge base; confirm the input, output, and any side effects against your installed version before relying on it.

#Prime pull cluster

These two tools carry the historical hivemind_ names and back the session-priming pull path: a session that already holds a primed reference can resolve or mine it cheaply without re-running a full recall.

#hivemind_read

Purpose. Resolve (zoom) a primed reference to its fuller summary or raw detail. Deterministic: returns the row asked for, no ranking.

Input shape. A reference (path or id) to resolve.

Output shape. The fuller content for the primed reference, or an empty result when nothing matches.

Side effects. Read-only.

#hivemind_search

Purpose. Mine for unknown matches, the hybrid recall variant on the prime-pull path. Routes to the same daemon-backed hybrid search as the browse surface.

Input shape. A query string.

Output shape. Ranked matches with provenance; honest degraded flag on fallback.

Side effects. Read-only.

#Goals and KPIs cluster

These two tools write. They are the explicit way an agent records objectives.

#honeycomb_goal_add

Purpose. Create a goal that is surfaced in agent context.

Input shape. The goal text. Per the goal model, a created goal starts in the opened status. Confirm the exact field names against the installed server definition.

Output shape. A confirmation carrying the new goal's identity. Confirm the exact field shape against your installed version.

Side effects. Writes. A row lands in the goals table (created lazily on first use) through the daemon. The goal then also appears as a markdown file in the memory browse surface under the opened status.

Example

{ "text": "cut the cold-start time of the dashboard below 1 second" }

#honeycomb_kpi_add

Purpose. Attach a measurable KPI to an existing goal. Call this only when the user explicitly asks for KPIs.

Input shape. A reference to the parent goal plus the KPI definition (a target and a unit, and a name). The exact field names are not fully published in the knowledge base; confirm against the installed server definition.

Output shape. A confirmation. Confirm the exact field shape against your installed version.

Side effects. Writes. A row lands in the kpis table (created lazily on first use) through the daemon.

#Codebase cluster

These tools surface the codebase-graph query endpoints once a graph exists for the workspace. They read the local graph snapshot; the graph is AST-only (tree-sitter, nine languages), so its answers are grounded in the current checkout.

Input shape. A symbol name or pattern (and, for some, a scope). The knowledge base names the tools and the query semantics but does not publish each tool's exact zod fields; confirm against the installed server definition.

Output shape. Text renderings of the graph query (matches, neighborhoods, dependents). These carry an honest caveat: cross-file call edges are resolved only for relative named and namespace imports, so a symbol reading "incoming (0)" is not proof of dead code, and a snapshot whose source has been edited since the build is stale and should be cross-checked against live source.

Side effects. Read-only. They read the local snapshot and make no network call.

#Agent coordination cluster

The knowledge base names these tools and their roles; it does not publish their exact zod fields. Confirm the input and output shapes against the installed server definition.

#Secrets cluster (value-safe)

These two tools are deliberately value-safe: an agent can list secret names and cause a secret to be used, but it can never read a secret value through MCP (or any other surface).

#secret_list

Purpose. List the names of stored secrets.

Input shape. Optional scope. Confirm against the installed server definition.

Output shape. Secret names only, never values.

Side effects. Read-only.

#secret_exec

Purpose. Run a command with named secrets injected into its environment, without ever exposing the secret values to the agent.

Input shape. A command and the names of the secrets to inject. Confirm the exact field names against the installed server definition.

Output shape. The command's output with any secret value redacted to [REDACTED] before the caller sees it. The call is asynchronous: it queues a job and returns; the result is fetched once the job completes.

Side effects. Spawns a subprocess on the daemon host with the secrets in its environment, under a timeout (5 minutes default, 30 minutes maximum) and a bounded worker pool. It does not return or log the secret values.

#A note on read-only vs writing tools

Honest side-effect classification matters when an assistant picks a tool. In this surface:

• Read-only: memory_search, memory_get, memory_list, honeycomb_search, honeycomb_read, honeycomb_index, session_search, hivemind_read, hivemind_search, all four honeycomb_code_* tools, agent_peers, agent_message_inbox, and secret_list.
• Writes: memory_store, memory_modify, memory_forget, memory_feedback, honeycomb_goal_add, honeycomb_kpi_add, agent_message_send.
• Runs a process (not a memory write): secret_exec.

memory_modify and memory_forget require a reason because they are audited mutations. Confirm the side-effect class of any tool not fully detailed here against your installed version before relying on it.

#Related

• CLI reference
• API reference
• Harness integrations spec
• Recall and retrieval spec
• Security model