Use KB-1 from Codex

Codex should use KB-1 through the daemon’s MCP endpoint. That keeps agent reads and writes on the same service boundary as the local web UI and API.

This tutorial uses the local daemon endpoint. If your vault is self-hosted with Cloud login, the browser team experience goes through Cloud, but local Codex on the daemon machine can still use localhost MCP.

Prerequisites

A running KB-1 daemon at http://127.0.0.1:7382.
Codex with MCP client support enabled.
A test vault such as demo-vault.

Add the server in Codex

Add an MCP server with these values:

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

Codex surfaces and CLI flags can change. Use the current Codex MCP settings or codex --help output for the exact place to add an HTTP MCP server; do not use a stdio command for KB-1 Local.

Restart Codex after adding the server if the tool list does not appear.

First prompt

Ask Codex for a read-only check first:

Use the kb1 MCP server. List my KB-1 vaults, choose demo-vault if it exists, and read README.md. Do not write anything yet.

Expected result:

Codex calls list_vaults.
Codex passes vaultId: "demo-vault" or another listed id to read_note.
Codex summarizes the note without claiming Cloud access was required.

Write a scratch note

After read-only access works, ask for a reversible write:

Use the kb1 MCP server and vaultId demo-vault. Create scratch/codex-smoke.md with a short note that says this is a Codex MCP smoke test, then read it back.

Check the local UI or disk:

kb1_home="${KB1_HOME:-$HOME/.kb1}"
ls "$kb1_home/vaults/demo-vault/scratch"

Clean up when done:

Use the kb1 MCP server and vaultId demo-vault. Delete scratch/codex-smoke.md permanently.

Editing existing notes

For edits, Codex should use the baseline loop:

read_note the target path.
Use the returned baseline in edit_note.
If edit_note returns stale_doc, reread the returned current content and retry with the fresh baseline.
If it returns match_count, add before, after, or occurrence anchors before retrying.

This protects against stale or ambiguous edits instead of letting the agent silently overwrite a human’s work.

Done looks like

Codex can list vaults and read a known note.
Codex can create, read, and clean up a scratch note.
Existing-note edits use read_note baseline plus edit_note, not a blind full-file rewrite.
Every data tool call includes the intended vaultId.