# 連接 client

透過 stdio 讓 MCP client 連上 KuraDB，或在 daemon 上開啟並呼叫 streamable HTTP endpoint。

## 以 stdio 連線

把任何 MCP client 指向 `kura` 執行檔：

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

Client 接著就會看到 `list_rag` 與 `search_rag`。`kura mcp` 開啟已註冊的資料庫、從 SQLite 重建自己的 vector cache，並在 stdin 與 stdout 上進行 JSON-RPC。診斷訊息走 stderr，因此不會污染協定串流。stdin 關閉時 session 結束，exit code 為 0。

此 process 需要與 daemon 相同 keychain 或環境中的 `OPENAI_API_KEY`；缺少時會在 session 開始前結束。若 key 只存在環境變數中，請透過 client 設定（例如 `env` 區塊）傳入，因為 spawn 此 process 的是 client 而非你的 shell。由於 vector cache 是在 spawn 當下載入，它看到的是一份快照：daemon 之後新索引的檔案，要等該 MCP session 重啟才會出現。

## 以 HTTP 連線

HTTP transport 預設關閉：route 不會掛載，`/mcp` 回 404。要開啟需明確執行：

```bash
kura remote enable
kura remote disable
```

此開關以 `remote` 存在 `~/.config/kuradb/config.json`。Route 在啟動時決定，因此兩個指令都會重啟執行中的 daemon 以套用變更。stdio 不受此設定影響。

開啟後，daemon 會將 MCP handler 掛在與 REST API 相同的 `127.0.0.1` listener 上：

```bash
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"}}}'
```

Response 會帶 `Mcp-Session-Id` header，後續請求必須沿用。未固定 port 的 daemon 每次重啟都綁隨機 port，因此把 URL 寫進 client 設定前先固定：

```bash
kura port set 8080
```