Tutorial: Expose tools via MCP

What you build

Claude Desktop with rousseau as an MCP stdio server. From inside a Claude Desktop chat you can ask "find the session where we discussed the retry logic" and Claude will call rousseau_search_sessions, then rousseau_read_session to fetch the full transcript.

Estimated time: 5 minutes.

Prerequisites

• Claude Desktop installed (macOS or Windows). Linux uses the Claude CLI, not Desktop — see the alternative at the bottom.
• Rousseau installed and on $PATH.
• Some existing session history in ~/.local/share/rousseau/sessions.db — run rousseau chat a few times if the file is empty.

Step 1: understand what gets exposed

rousseau mcp (internal/cli/mcp.go) starts a stdio JSON-RPC server that speaks the Model Context Protocol. RegisterRousseauTools (internal/mcp/tools.go) attaches four read-only tools:

There are no write tools; MCP hosts can browse but not mutate. See MCP: Exposed tools for the exact input schemas.

Step 2: wire Claude Desktop

Claude Desktop reads claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a mcpServers entry pointing at your rousseau binary:

{
  "mcpServers": {
    "rousseau": {
      "command": "/usr/local/bin/rousseau",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop.

Step 3: verify

Open a Claude Desktop chat and check that the tools appear in the tool picker. You should see four tools prefixed rousseau_. Try:

Use rousseau_list_sessions to show me my 5 most recent sessions,
then read the top one with rousseau_read_session.

Claude will invoke both tools, and rousseau's MCP server (internal/mcp/server.go) will handle each JSON-RPC envelope over stdin/stdout. Behind the scenes:

1. Claude Desktop calls initialize, then tools/list — rousseau responds with the four tools declared in insertion order.
2. Claude picks a tool and calls tools/call with the arguments — rousseau's handler (from internal/mcp/tools.go) queries SQLite and returns text content.
3. On error, rousseau surfaces the error through the content channel (isError=true), never as a JSON-RPC error — MCP hosts expect this.

Step 4: (optional) attach to Claude CLI / other MCP host

The stdio protocol is host-agnostic. For the Claude CLI:

claude --mcp-config <(cat <<'JSON'
{ "mcpServers": { "rousseau": { "command": "rousseau", "args": ["mcp"] } } }
JSON
)

For Continue.dev, Codeium, or another MCP host, follow their MCP-server registration flow with command: rousseau, args: [mcp]. See MCP: Compatibility for the tested clients.

Step 5: FTS5 syntax cheat-sheet

Because rousseau_search_sessions is a thin wrapper around SQLite FTS5 (internal/state/sqlite/search.go), the query field supports:

Query	Meaning
retry logic	Any doc containing both terms.
"retry logic"	Exact phrase.
retr*	Prefix match.
retry OR backoff	Boolean OR.
retry NOT retries	Exclusion.

Ranking uses BM25 (lower rank = more relevant); the snippet() call in Search gives you a 200-character preview per hit.

Troubleshooting

• "unknown tool" in Claude Desktop. Restart the app. The tool list is only fetched on session start.
• Server exits immediately. rousseau mcp opens the SQLite state file; if the path in state.path isn't writable, Open() fails and the process exits with a non-zero code. Run it from a shell to see the error.
• Empty search results. Confirm the FTS5 index is populated: sqlite3 ~/.local/share/rousseau/sessions.db "SELECT count(*) FROM sessions_fts". EnsureSearch in internal/state/sqlite/search.go back-fills the index on every open, but a corrupted state file may need a manual rebuild.

Related

• MCP — the reference doc.
• MCP: Exposed tools — every tool schema.
• MCP: Compatibility — tested clients.
• Reference: Session store — the SQLite schema behind the tools.