Connect a Client

Point an MCP client at KuraDB over stdio, or enable and call the streamable HTTP endpoint on the daemon.

Connect over stdio

Point any MCP client at the kura binary:

{
  "mcpServers": {
    "kuradb": {
      "command": "kura",
      "args": ["mcp"]
    }
  }
}

The client then sees list_rag and search_rag. kura mcp opens the registered databases, restores its own vector cache from SQLite, and speaks JSON-RPC over stdin and stdout. Diagnostics go to stderr, so they never corrupt the protocol stream. Closing stdin ends the session with exit code 0.

The process needs OPENAI_API_KEY from the same keychain or environment as the daemon; without it, it exits before the session starts. When the key lives only in an environment variable, pass it through the client entry (for example an env block), because the client, not your shell, spawns the process. Because it loads the vector cache at spawn time, its view is a snapshot: files indexed by the daemon afterwards appear only after the MCP session restarts.

Connect over HTTP

The HTTP transport is off by default: the route is not mounted, so /mcp returns 404. Turn it on explicitly:

kura remote enable
kura remote disable

The flag is stored as remote in ~/.config/kuradb/config.json. Routes are mounted during startup, so both commands restart a running daemon to apply the change. Stdio is never affected by this setting.

Once enabled, the daemon mounts the MCP handler on the same 127.0.0.1 listener as the REST API:

BASE="$(cat ~/.config/kuradb/endpoint)"
curl -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

The response carries an Mcp-Session-Id header that subsequent requests must repeat. Because an unpinned daemon binds a random port on every restart, pin one before writing the URL into a client configuration:

kura port set 8080