Agent access fails

Agent failures usually come from one of four places: wrong URL, daemon not running, missing vaultId, or an edit contract rejection.

Check the URL

Agents should connect to the daemon front door:

http://127.0.0.1:7382/mcp

Do not point agents at the internal Vite dev server port. If you changed KB1_PORT, update the MCP URL too.

Check the daemon

curl http://127.0.0.1:7382/api/health
curl http://127.0.0.1:7382/api/vaults

No health response means the daemon is not reachable. No vaults means the agent has nothing to target.

Check MCP initialize

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-agent-debug","version":"0.1.0"}}}'

You should see 200 or 202 and an MCP session id header.

Check tool usage

Call list_vaults first.
Pass the exact vaultId to every data tool.
Use read_note before edit_note.
Handle stale_doc by retrying with the fresh baseline.
Handle match_count by adding anchors or an occurrence.

Check client config

Restart the agent after changing MCP settings.
Make sure the server name is the one your prompt references, such as kb1.
If the client supports multiple transports, choose HTTP or Streamable HTTP.
If the agent runs on another machine, localhost points at that machine, not the daemon host.