StartUpdated 2026-05-30

Connect Agents

Give Claude, Cursor, Codex, backend jobs, and custom agents access to RetainDB.

Agents can read and update RetainDB through MCP or HTTP.

Use MCP when the agent host supports tools. Use HTTP when you are building a backend, job, worker, or custom runtime.

Choose A Connection

Agent type	Recommended path	Why
Claude Code, Cursor, Codex, Windsurf, Cline, OpenCode	MCP	tools appear directly inside the agent
backend support agent	HTTP	predictable server-side auth and logs
scheduled job or worker	HTTP	easier retries and idempotency
TypeScript app	SDK	typed helpers for memory and project operations
multi-agent workflow	SDK or Agent Memory API	task events, handoffs, and context bundles

Prerequisites

Create an API key in Dashboard -> Developers -> API Keys.

Use server-side environment variables:

bash

RETAINDB_API_KEY="rdb_..."
RETAINDB_API_URL="https://api.retaindb.com"
RETAINDB_PROJECT="production"

Normal dashboard users do not need API keys. API keys are for agents, SDKs, MCP, servers, jobs, and external automation.

MCP Setup

Add this to your MCP host config:

json

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

Restart the host, then verify:

txt

Call list_sources and tell me which RetainDB sources are ready.

Then:

txt

Ask RetainDB what the company brain knows about billing retries.

Useful MCP tools:

Tool	Use it for
`context`	ask the company brain
`list_sources`	inspect source sync status
`read_context_file`	read `/context/company.md` or other agent filesystem paths
`remember`	store durable facts, preferences, and corrections
`agent_event`	record decisions, failures, tool results, and task updates
`agent_handoff`	package context for another agent

HTTP Setup

Ask the company brain:

bash

curl -X POST "$RETAINDB_API_URL/v1/context" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "production",
    "query": "What should the agent know before answering billing questions?",
    "max_results": 8
  }'

List sources:

bash

curl "$RETAINDB_API_URL/v1/sources?project=production" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Read the agent filesystem:

bash

curl "$RETAINDB_API_URL/v1/context/files?project=production&path=/context/company.md" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

What To Put In Prompts

Use RetainDB output as evidence, not as a hidden global instruction.

txt

Use the following RetainDB company context when it is relevant.
If the context does not answer the user, say what is missing instead of guessing.

{retaindb_context}

Common Mistakes

Symptom	Likely cause	Fix
Agent cannot see tools	MCP host was not restarted	restart host and verify config path
`context` returns little or nothing	source is not indexed or wrong project	call `list_sources` and check `RETAINDB_PROJECT`
401 from API	missing or wrong key	use `Authorization: Bearer $RETAINDB_API_KEY`
Good answer in dashboard but not agent	project mismatch	use the same project in dashboard, MCP, and HTTP
Agent hallucinates over context	prompt does not require grounding	tell the agent to cite or admit missing context

Next: MCP Setup, Company Brain API, or Sources API.

Was this page useful?

Your feedback helps us make the product easier to ship with.