Security and Scope Controls

Secure RetainDB MCP as if it were a production integration point, not a convenience script. It can read local files, search code, ingest sources, and write durable memory, so the surrounding scope model matters.

Key management

Use separate rdb_* keys per environment:

# Development
RETAINDB_API_KEY=rdb_dev_...

# Production
RETAINDB_API_KEY=rdb_prod_...

Example split config:

{
  "mcpServers": {
    "RetainDB-dev": {
      "command": "npx",
      "args": ["-y", "@retaindb/mcp-server@latest"],
      "env": {
        "RETAINDB_API_KEY": "rdb_dev_...",
        "RETAINDB_PROJECT": "project-dev"
      }
    },
    "RetainDB-prod": {
      "command": "npx",
      "args": ["-y", "@retaindb/mcp-server@latest"],
      "env": {
        "RETAINDB_API_KEY": "rdb_prod_...",
        "RETAINDB_PROJECT": "project-prod"
      }
    }
  }
}

Scope controls that matter most

Default project scope

Set RETAINDB_PROJECT whenever the server should stay anchored to one project by default.

Runtime mode

• remote is the safe default
• local enables local ingest behavior
• auto mixes remote and local behavior when available

Local filesystem allowlist

If you enable local ingest or want controlled local scans, restrict roots explicitly:

RETAINDB_MCP_MODE=auto
RetainDB_LOCAL_ALLOWLIST=/workspace/app,/workspace/docs

Generated scoped configs

Use the built-in scope generator when you want per-client or per-source configs:

retaindb-context-mcp scope --project my-project --client claude
retaindb-context-mcp scope --project my-project --source github --client vscode

Tool-level operational guidance

• prefer search, search_code, grep, and read for day-to-day coding workflows
• reserve write-capable verbs like remember, record, and learn for trusted workflows
• use namespaced tools like context.add_source or memory.add only when you need the explicit advanced contract

Monitoring and traceability

Track:

• which project a server instance defaults to
• which host/client is allowed to invoke it
• whether local mode is enabled
• trace IDs or tool result metadata returned by the MCP workflow

When something looks wrong, first verify whether the server instance is over-scoped before assuming a product bug.

Key rotation

Operationally:

1. create a replacement rdb_* key
2. update the MCP host config
3. restart the MCP host
4. revoke the old key once the new config is confirmed

Do not rotate keys by editing live configs without a restart plan, or you will create hard-to-debug partial failures.

Best practices

• never commit .env, local MCP settings, or copied secrets
• keep separate keys per environment and per trust boundary
• keep production servers in remote mode unless local access is intentionally required
• use RetainDB_LOCAL_ALLOWLIST instead of broad filesystem access
• validate that a scoped config still surfaces only the tools and content you expect

Next step

• Auth Model
• Operations Troubleshooting
• MCP Setup