Skip to content
KB-1 Docs

MCP tools

KB-1 has two MCP entry points:

  • Local daemon MCP: the daemon exposes Streamable HTTP MCP at /mcp on the same host and port as the local app and API.
  • Cloud MCP: enabled deployments expose an OAuth-backed Cloud MCP worker that routes tool calls to the selected organization’s daemon.

Local daemon MCP is available anywhere the daemon is running:

http://127.0.0.1:7382/mcp

The server name reported on the wire is kb-1-local-daemon. You can give the connection any convenient client-side name, such as kb1.

Addressing model

Section titled “Addressing model”

For local daemon MCP, list_vaults is the discovery tool. Every other data tool requires an explicit vaultId.

For Cloud MCP, call list_orgs first. Then pass the chosen org to list_vaults and pass both org and vaultId to every vault data tool. Cloud uses org for routing and strips it before forwarding the daemon MCP call.

There is no default vault. This is deliberate: agents must choose the vault they intend to operate on instead of accidentally writing to the first vault on disk.

Tools

Section titled “Tools”
Tool Purpose Writes?
list_orgs Cloud MCP only: list KB-1 Cloud orgs the authenticated user can access. No
list_vaults List every vault served by the daemon as { id, displayName, metadata? }. No
vault_info Return vault root name plus file and folder counts. No
list_files List files and folders, including inline folder metadata. No
list_attachments List binary attachments, optionally scoped to a folder or image/non-image kind. No
read_attachment Read an image as native MCP image content or another binary attachment as base64. No
upload_attachment Upload a binary attachment inline as base64. Current inline uploads are capped at 4 KiB. Yes
search Search notes with optional folder scope, context, limit, and offset. No
read_note Read a Markdown note and return content, stat fields, and baseline. No
create_note Create a Markdown note; overwrite is optional and false by default. Yes
edit_note Apply an anchored splice using a read_note baseline. Yes
append_note Append content, creating the note when missing. Yes
prepend_note Prepend content after frontmatter when present. Yes
delete_note Soft-delete to .kb1/trash by default; permanent removes directly. Yes
move_note Move or rename a note. Wikilinks are not rewritten. Yes
create_folder Create a folder. Yes
delete_folder Soft-delete a folder to .kb1/trash; non-empty folders require recursive: true, and permanent removes directly. Yes
move_folder Move or rename a folder. Wikilinks are not rewritten. Yes
get_folder_metadata Read durable folder color metadata. No
set_folder_metadata Set or clear folder color metadata. Yes

Local daemon mutations are audited as mcp_client with the client name reported by the MCP session when available. Cloud MCP mutations are server-attributed to the approved integration and user, then forwarded to the daemon with trusted x-kb1-actor attribution.

Edit contract

Section titled “Edit contract”

edit_note uses the same anchored splice contract as the REST API:

  • Call read_note first and keep the returned baseline.
  • Send old_text, new_text, and optional before, after, or occurrence.
  • If the document changed, the daemon returns stale_doc with current content and a fresh baseline.
  • If the match is ambiguous, the daemon returns match_count so the agent can add anchors.
  • Persist failures are returned as failures; they are not written as successful audit entries.

Local vs Cloud

Section titled “Local vs Cloud”

Local-only agents use the daemon endpoint directly. Self-hosted Cloud login and Hosted vaults use Cloud for people, organizations, signed entry, routing, presence, and Cloud MCP integration approval when that worker is enabled for the deployment.

Cloud MCP can publish short-lived agent activity into the Cloud collaboration surface. Active human presence is still separate from agent activity; an agent tool call may show where the integration recently acted, but it is not a live browser socket.

Git-backed, best-effort note history is currently available through the local web UI and daemon REST API. It is not yet exposed as an MCP tool.

Section titled “Related docs”