Skip to main content

How to Integrate with MCP (Model Context Protocol)

Use SochDB as persistent memory and a queryable knowledge fabric for Claude, Cursor, Goose, and other MCP clients.

Problem​

You want to give your LLM agent (Claude Desktop, Cursor, Goose, etc.) persistent memory and structured retrieval using SochDB.

Solution​

SochDB ships a standalone MCP server, sochdb-mcp. It is a framework-free Model Context Protocol server that speaks JSON-RPC over stdio and makes direct embedded Rust calls into an on-disk SochDB database — there is no separate network database to run. It implements MCP protocol version 2024-11-05 and advertises tools and resources capabilities (no prompts).

Looking for the full agent walkthrough?

This page covers installing and configuring the MCP server. For end-to-end patterns of driving a coding agent against SochDB (memory loops, agentic code search, context packing), see the Coding Agents guide.

1. Build the SochDB MCP server​

The binary is part of the Rust workspace (the core engine, including sochdb-mcp, is AGPL-3.0-or-later).

# Build from source
cargo build --release --package sochdb-mcp

# The binary lands at target/release/sochdb-mcp.
# Optionally copy it onto your PATH:
cp target/release/sochdb-mcp /usr/local/bin/

The server takes a single flag, --db <path>, pointing at the on-disk data directory (default ./sochdb_data). It opens an embedded connection for real persistence:

sochdb-mcp --db ./data

Logs go to stderr only — stdout is reserved for the JSON-RPC protocol stream. For verbose logging set RUST_LOG=sochdb_mcp=debug.

You can smoke-test it without a client by piping a request:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | sochdb-mcp --db ./test_data

2. Configure Claude Desktop​

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform. Use an absolute path to the binary and to the data directory — MCP clients do not expand ~ or resolve relative paths reliably.

{
  "mcpServers": {
    "sochdb": {
      "command": "/usr/local/bin/sochdb-mcp",
      "args": ["--db", "/Users/you/.sochdb/claude_memory"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

3. Configure Cursor​

Add the server to .cursor/mcp.json (project-local) or your global Cursor MCP settings:

{
  "mcpServers": {
    "sochdb": {
      "command": "/usr/local/bin/sochdb-mcp",
      "args": ["--db", "/Users/you/.sochdb/cursor_memory"]
    }
  }
}

4. Configure Goose​

Goose uses a flat per-server entry. Add to your Goose config:

{
  "name": "sochdb",
  "type": "stdio",
  "command": "/usr/local/bin/sochdb-mcp",
  "args": ["--db", "/Users/you/.sochdb/goose_memory"],
  "timeout": 300,
  "env": {}
}
Edit the absolute paths

The example configs bundled in the repo (sochdb-mcp/mcp-claude-desktop.json, mcp-cursor.json, mcp-goose.json) hardcode build-machine paths under /Users/sushanth/sochdb/.... You must replace both the command path (the sochdb-mcp binary) and the --db path with absolute paths on your own machine.

Available MCP tools​

Tool names use underscores (for example sochdb_query, memory_search_episodes). Older dot-named catalogs in the repo's mcp.json and README (such as sochdb.query) are stale — the names below are what the server actually exposes.

Core database tools​

sochdb_get​

Get the value at a path.

Tool: sochdb_get
Arguments:
  path: "users/alice/preferences"

sochdb_put​

Set the value at a path. Commits and double-fsyncs for durability.

Tool: sochdb_put
Arguments:
  path: "users/alice/preferences"
  value: '{"theme": "dark", "language": "en"}'

sochdb_delete​

Delete the value at a path.

Tool: sochdb_delete
Arguments:
  path: "users/alice/old_data"

sochdb_query​

Execute a SochQL query. Uses a hardened parser that enforces prefix-bounded scans and table-name validation for multi-tenant safety.

  • query — the SochQL statement.
  • format — toon or json (default toon).
  • limit — default 100.
Tool: sochdb_query
Arguments:
  query: "SELECT id,name FROM users WHERE score > 80"
  format: "toon"
  limit: 100

sochdb_context_query​

Fetch AI-optimized context with token budgeting; sections are packed in priority order.

  • sections[] — each section has name, priority, and kind (one of literal, get, last, search), plus the relevant fields (text/path/table/query/top_k/where).
  • token_budget — default 4096.
  • format — toon, json, or markdown (default toon).
  • truncation — tail_drop, head_drop, or proportional.
Tool: sochdb_context_query
Arguments:
  sections:
    - name: "user_prefs"
      kind: "get"
      path: "users/alice/preferences"
      priority: 1
    - name: "history"
      kind: "last"
      table: "messages"
      top_k: 10
      priority: 2
  token_budget: 4096
  format: "toon"
  truncation: "tail_drop"

sochdb_list_tables​

List all tables with semantic metadata.

  • include_metadata — default true.
Tool: sochdb_list_tables
Arguments:
  include_metadata: true

sochdb_describe​

Get the detailed schema for a table.

Tool: sochdb_describe
Arguments:
  table: "users"

Memory tools​

These operate on SochDB's episode / entity / event memory schema.

  • memory_search_episodes — search over episodes. Args: query, k (default 5), episode_type (one of conversation, task, workflow, debug, agent_interaction), entity_id.
  • memory_get_episode_timeline — event timeline for an episode. Args: episode_id, max_events (default 50), role (one of user, assistant, system, tool, external), include_metrics (default false).
  • memory_search_entities — search entities. Args: query, k (default 10), kind (one of user, project, document, service, agent, organization).
  • memory_get_entity_facts — facts about an entity. Args: entity_id, include_episodes (default true), max_episodes (default 5).
  • memory_build_context — one-shot optimized LLM context packing. Args: goal, token_budget (default 4096), session_id, episode_id, entity_ids[], include_schema (default false).

Log tools​

  • logs_tail — last N rows from a log table (most recent first). Args: table, limit (default 20), where, columns[].
  • logs_timeline — events in a time range for an entity. Args: entity_id, from_ts/to_ts (microseconds since epoch), limit (default 100), table (default events).

Agentic search tools​

These three tools turn an in-memory document corpus into a code-search surface backed by a trigram index for sublinear lookups.

  • sochdb_grep — indexed grep over the corpus with line-anchored hits. Args: pattern, scope (a doc_id prefix filter), limit (default 50).
  • sochdb_peek — read a line range from a document. Args: doc_id, start_line, end_line.
  • sochdb_expand — expand by plus or minus N lines around a hit. Args: doc_id, line, window (default 5).
Semantic search falls back to keyword

Vector/semantic search in the MCP server is gated behind both the semantic-search Cargo feature (off by default) and the runtime env var SOCHDB_SEMANTIC_SEARCH=1. Even when both are enabled, the vector path is not yet wired to the backend — the server generates embeddings but the actual vector search is disabled in code pending backend support, so memory_search_* currently falls back to a keyword/text scan.

MCP resources & views​

In addition to tools, the server exposes SochDB tables and predefined views as MCP resources:

  • resources/list lists tables as sochdb://tables/<name> with semantic-metadata annotations (role, primary key, cluster key, timestamp column, whether it is backed by a vector index, and embedding dimension).
  • resources/read supports both sochdb://tables/<name> and sochdb://views/<name>.
  • Predefined views: conversation_view, tool_calls_view, error_view, episode_summary_view, entity_directory_view.
  • Resource output is text/x-toon by default, or application/json when format=json.

Example: agent with persistent memory​

Here is how an agent might use SochDB across a session.

Storing a preference​

User: Remember that I prefer dark mode.

Claude uses tool: sochdb_put
  path: "user/preferences/theme"
  value: "dark"

Claude: Noted — I'll remember you prefer dark mode for future sessions.

Recalling information​

User: What theme do I prefer?

Claude uses tool: sochdb_get
  path: "user/preferences/theme"
  result: "dark"

Claude: You prefer dark mode.

Building context​

User: Summarize what we discussed yesterday.

Claude uses tool: sochdb_context_query
  sections:
    - name: "history"
      kind: "last"
      table: "conversations"
      top_k: 20
      priority: 1
  token_budget: 2000

Claude: Based on our conversation yesterday, we discussed...

Troubleshooting​

MCP server not starting​

Run it directly with verbose logging — remember logs go to stderr:

RUST_LOG=sochdb_mcp=debug sochdb-mcp --db ./test_db

Permission denied​

Ensure the database directory is writable:

mkdir -p ~/.sochdb
chmod 755 ~/.sochdb

Client not seeing tools​

  1. Restart the client (Claude Desktop / Cursor / Goose) after editing its config.
  2. Validate the config JSON syntax.
  3. Confirm the command path and the --db path are absolute and correct.

Debug logging via the config​

{
  "mcpServers": {
    "sochdb": {
      "command": "/usr/local/bin/sochdb-mcp",
      "args": ["--db", "/Users/you/.sochdb/debug"],
      "env": {
        "RUST_LOG": "sochdb_mcp=debug",
        "RUST_BACKTRACE": "1"
      }
    }
  }
}

Discussion​

Security considerations​

  • The MCP server runs locally with embedded database access under your user permissions — there is no auth layer in stdio mode.
  • Data is stored unencrypted on disk by default.
  • The sochdb_query parser enforces prefix-bounded scans and table-name validation, which limits cross-tenant access within a shared database.

Performance tips​

  • Prefer one sochdb_context_query over many sochdb_get calls — it packs everything in a single token-budgeted response.
  • Bound result sets with the limit argument on sochdb_query, logs_tail, and friends.
  • Use sochdb_grep + sochdb_peek/sochdb_expand for code-style retrieval instead of scanning whole documents.

See Also​