Skip to content
KB-1 Docs

Connect an agent through MCP

Use this path when an agent runs on the same machine as KB-1 Local or on a private network you already trust. The daemon exposes one Streamable HTTP MCP endpoint at /mcp on the same port as the local web UI and API.

Local daemon MCP is the stable setup every self-hosted or local-only user can run. KB-1 Cloud now also has a Cloud MCP worker for deployments where it has been enabled by the operator. Use the Cloud MCP URL only when your deployment gives you one; otherwise use the daemon endpoint below. Use Cloud MCP or relay when the agent should reach a self-hosted vault from somewhere other than the daemon machine or a private network you trust.

What this sets up

Section titled “What this sets up”
  • An MCP server named kb1 in your agent client.
  • A connection to http://127.0.0.1:7382/mcp.
  • Agent access to every vault served by that daemon.
  • A verification loop that proves the agent can discover a vault, read a note, check attachment inventory, and make a reversible write.

Prerequisites

Section titled “Prerequisites”
  • A running KB-1 daemon. See Run the local-only daemon.
  • An MCP-capable client such as Codex, Claude Code, Hermes, or another client that supports Streamable HTTP MCP.
  • A vault id from GET /api/vaults or the MCP list_vaults tool.

Keep the daemon bound to 127.0.0.1 unless you deliberately expose it through a private network such as Tailscale. Local-only daemon MCP does not add an application login layer in front of localhost.

Verify the daemon first

Section titled “Verify the daemon first”
Terminal window
curl http://127.0.0.1:7382/api/health
curl http://127.0.0.1:7382/api/vaults

Expected signals:

{"ok":true,"service":"kb1d"}
{"ok":true,"vaults":[{"id":"demo-vault","displayName":"demo-vault"}]}

Add the MCP server

Section titled “Add the MCP server”

For local daemon MCP, use these connection values in your client:

Field Value
Name kb1
Transport Streamable HTTP / HTTP MCP
URL http://127.0.0.1:7382/mcp

Claude Code can add it from the command line:

Terminal window
claude mcp add kb1 --transport http http://127.0.0.1:7382/mcp

For Codex and other MCP clients, add an HTTP MCP server named kb1 with the same URL. If the client has an MCP subcommand, prefer the command shown by that client’s current --help output.

If your KB-1 Cloud deployment has Cloud MCP enabled, your operator may instead give you a Cloud MCP URL such as the deployment’s /mcp endpoint. That path uses Cloud sign-in and approval. After connecting, call list_orgs first, then pass the chosen org and vaultId to vault tools.

Probe the endpoint

Section titled “Probe the endpoint”

This low-level probe should return 200 or 202, an mcp-session-id header, and MCP server information:

Terminal window
curl -i http://127.0.0.1:7382/mcp   -H 'content-type: application/json'   -H 'accept: application/json, text/event-stream'   --data-binary '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"kb1-docs-probe","version":"0.1.0"}}}'

If this fails, the agent client will fail too. Check the port, daemon process, and local firewall before debugging the client.

Run an agent smoke test

Section titled “Run an agent smoke test”

In the agent client, call these tools in order:

  1. list_vaults.
  2. Pick a vault id, such as demo-vault.
  3. vault_info with that vaultId.
  4. read_note with vaultId and a known path such as README.md.
  5. list_attachments with vaultId. An empty list is expected for a fresh starter vault; after adding or importing an asset, run it again to verify attachment discovery.
  6. create_note with vaultId, path: "scratch/agent-smoke.md", and harmless content.
  7. read_note for scratch/agent-smoke.md.
  8. delete_note with permanent: true, or leave the note in .kb1/trash if you want soft-delete behavior.

For local daemon MCP, list_vaults is the only discovery tool that does not take vaultId. For Cloud MCP, call list_orgs, then list_vaults with the chosen org; every vault data tool requires both the Cloud org and explicit vaultId. There is no default vault.

Done looks like

Section titled “Done looks like”
  • The MCP client shows a connected server named kb1.
  • list_vaults returns at least one vault.
  • The agent can read a known note.
  • A scratch write appears in the local UI or on disk under KB1_HOME/vaults/<vault-id>/.
  • The scratch write is deleted or intentionally kept.
Section titled “Troubleshooting links”