Stdio MCP Mode with Smart Daemon Detection

MentisDB 0.9.2 introduces a smarter stdio MCP mode that makes connecting Claude Desktop, Cursor, and other MCP-spawning clients effortless. The stdio process now auto-detects a running daemon, proxies to it if found, or launches one in the background if not. Zero configuration, shared live state.

The Problem

Previously, mentisdbd --mode stdio created its own independent MentisDbService instance every time it started. This worked fine as a standalone process, but meant:

• Each Claude Desktop session got its own in-memory chain cache
• Changes made by one session weren't visible to another until disk reload
• If you had a daemon running on port 9471, the stdio process ignored it entirely
• Claude Desktop users needed Node.js + mcp-remote just to connect to a local daemon

The mcp-remote bridge works, but it's an extra dependency chain: Node.js ≥ 20, npm install, TLS self-signed cert handling, NODE_TLS_REJECT_UNAUTHORIZED. For a tool that runs on localhost, that's a lot of friction.

How Stdio Mode Works Now

When mentisdbd --mode stdio starts, it follows a three-step flow:

Step 1: Detect

The stdio process hits http://127.0.0.1:9471/health with a 500ms timeout. If it gets a 200 response, a daemon is already running.

Step 2: Launch (if needed)

If no daemon responds, the stdio process launches one in the background:

• Unix: nohup mentisdbd & — the daemon outlives the stdio process
• Windows: start /B mentisdbd — detached background process

It then polls the health endpoint for up to 10 seconds, waiting for the daemon to become responsive.

Step 3: Proxy

Once a daemon is confirmed, the stdio process acts as a lightweight JSON-RPC proxy:

Static methods (initialize, ping, resources) are served from the stdio process itself. Dynamic methods (tools/list, tools/call) are forwarded to the daemon's HTTP MCP endpoints. This minimizes latency for handshake operations while ensuring all tool execution hits the live daemon state.

Fallback

If daemon launch fails (e.g., binary not found, permission denied), the stdio process falls back to the original local mode — creating its own MentisDbService with state shared only via disk files. This ensures Claude Desktop still works even when the daemon can't start.

Claude Desktop Configuration

The entire Claude Desktop config is now three lines:

{
  "mcpServers": {
    "mentisdb": {
      "command": "mentisdbd",
      "args": ["--mode", "stdio"]
    }
  }
}

That's it. No Node.js. No mcp-remote. No TLS config. No daemon pre-start. Just point Claude Desktop at the mentisdbd binary and go.

You can also run the setup wizard to write this automatically:

mentisdbd setup claude-desktop

Other MCP Clients

Any MCP client that spawns stdio subprocesses benefits from this:

• Cursor — add mentisdbd --mode stdio as an MCP command
• VS Code Copilot — configure stdio transport in MCP settings
• Any MCP host — if it can spawn a process and pipe JSON-RPC over stdin/stdout, it works

HTTP-based clients (Claude Code, Codex, Qwen Code) continue to use the streamable HTTP MCP endpoint at http://127.0.0.1:9471 as before. The stdio mode is specifically for clients that spawn subprocesses.

Why Proxy Instead of Local?

The proxy approach solves several problems at once:

• Shared state — all stdio sessions see the same live chain cache, not stale disk reads
• Single daemon — one process handles all writes, avoiding concurrent file access
• Webhook delivery — the daemon's webhook manager runs once, not per-session
• Vector sidecars — managed sidecars stay synchronized across all clients
• Lower memory — stdio proxy processes are tiny compared to full MentisDbService instances

Upgrade

cargo install mentisdb --force

Then update your Claude Desktop config to use stdio mode. If you were previously using mcp-remote, you can remove the Node.js and mcp-remote dependencies entirely.

Environment Variables

The stdio proxy respects the same environment variables as the daemon:

• MENTISDB_BIND_HOST — the host to check for a running daemon (default: 127.0.0.1)
• MENTISDB_MCP_PORT — the port to check (default: 9471)
• MENTISDB_DIR — used when falling back to local mode

If you run the daemon on a non-standard port, the stdio process will detect and proxy to it automatically.