MCP Setup and Tools

Use RetainDB MCP when your main workflow lives in an MCP-compatible client and you want retrieval, local code exploration, and durable memory without building your own wrapper first.

Environment note: MCP calls use the API URL in RETAINDB_API_URL and default to https://api.retaindb.com when unset.

Start with the primary agent verbs

These are the first tools to learn:

• search for grounded retrieval over stored RetainDB context
• search_code for meaning-based local code search in the live workspace
• grep for exact local text search
• read for opening a local file after search
• explore for browsing the repo tree
• research for deeper synthesis over indexed sources
• remember for durable facts, preferences, and decisions
• record for session-oriented conversation capture
• learn for adding text, files, repos, or sources
• share_context for handing context to another agent or teammate

When the namespaced tools matter

The namespaced tools remain the canonical advanced surface:

• search_code -> code.search_semantic
• grep -> code.search_text
• research -> research.oracle
• remember -> memory.add
• learn -> context.add_text, context.add_document, or context.add_source
• share_context -> context.share
• use context.query, context.evidence_answer, or memory.search when you want the explicit advanced contract instead of the primary shorthand

Live workspace vs stored project retrieval

• grep and explore read the live local workspace directly
• search_code is also live local search, and now returns richer workspace diagnostics plus fallback details when lexical rescue was needed
• index.workspace_run only refreshes local workspace freshness metadata; it does not prove that stored project retrieval already contains this repo
• index.local_scan_ingest or another real source ingest path is what makes project-backed retrieval ready for local repo evidence
• search and context.get_relevant prefer verified project repo sources, but now auto-fallback to live local workspace retrieval for repo-grounded queries when the bound project lacks this repo
• context.evidence_answer and context.claim_verify still fail closed unless the evidence is explicitly repo-grounded

What you need before setup

• a RetainDB API key starting with rdb_
• an optional default project slug or id
• an MCP host such as Claude Desktop or Claude Code

Basic MCP server config

{
  "mcpServers": {
    "retaindb-context": {
      "command": "npx",
      "args": ["-y", "@retaindb/mcp-server@latest"],
      "env": {
        "RETAINDB_API_KEY": "rdb_...",
        "RETAINDB_API_URL": "https://api.retaindb.com",
        "RETAINDB_PROJECT": "retaindb-quickstart"
      }
    }
  }
}

First verification flow

1. start or reload the MCP host
2. confirm the RetainDB tools are visible
3. run remember with a small fact
4. run search to confirm the fact is retrievable
5. run search_code or grep against a known workspace

That gives you better signal than only checking whether the process starts.

Which tool to use when

• need project-scoped retrieval: search
• need exact local text lookup: grep
• need concept-based code search in the current repo: search_code
• need to inspect the matching file: read
• need a durable preference or fact: remember
• need to index new content: learn
• need a citation-constrained answer: context.evidence_answer

Security notes

Keep the MCP server on trusted infrastructure, scope RETAINDB_PROJECT where possible, and use RETAINDB_MCP_MODE=remote unless you intentionally need local ingestion or local file search.

Next step

Continue with Claude Desktop setup or Claude Code setup. For the local-search side of the tool surface, read semantic search tools.