MCP Tools Reference

RelataDB exposes its full surface as Model Context Protocol  tools at the /mcp endpoint. The same surface is mirrored by the Python SDK’s McpClient and any MCP-compatible agent runtime (Claude Desktop, LangChain, OpenAI Agents SDK, …).

Endpoint: POST /mcp/tools/call · Discovery: GET /mcp/tools

The authoritative live list and JSON schemas are always available at GET /mcp/tools — this page mirrors what’s documented in docs/src/mcp-tools.md.

Access control (applies to every tool)

• Auth: every call authenticated (Bearer token).
• Parameter validation: ADR-057 enforced.
• Purpose check: every call requires a registered purpose.
• Egress filtering: classified types (SourceTrueIdentity, SigintIntercept, AccessScopedIntercept, LawfulInterceptRecord) are blocked at egress regardless of query success.
• Audit: every invocation recorded in the append-only audit log with principal, timestamp, purpose, cost units, and a tamper-evident hash chain.
• Quota: tools charge cost units (most query tools 1, multi-table tools 3–5). Default 10,000 units/principal; configurable via RELATA_QUERY_QUOTA. Quota exhaustion returns HTTP 429.

Query

Entity & Identity

Document Ingest & RAG

Knowledge Graph & Search

Entity Intelligence

Notes & Audit

Agent Memory (the cognitive verbs)

The 10 cognitive verbs ship as MCP tools and HTTP endpoints. Each requires a purpose token (recorded for audit).

Example lifecycle (MCP):

// 1. remember — store a governed memory item
{ "method": "tools/call", "params": { "name": "remember",
  "arguments": { "content": "Customer Alice plans to renew in Q3.",
                 "session_id": "agent-session-42", "confidence": 0.9,
                 "purpose": "account_management" } } }
 
// 2. recall — hybrid BM25+vector retrieval
{ "method": "tools/call", "params": { "name": "recall",
  "arguments": { "query": "What do we know about Alice's renewal?",
                 "session_id": "agent-session-42", "top_k": 5,
                 "as_of": "2026-06-01T00:00:00Z",
                 "purpose": "account_management" } } }
 
// 3. forget — schedule retention
{ "method": "tools/call", "params": { "name": "forget",
  "arguments": { "id": "<MemoryItem-uuid>", "retain_days": 90,
                 "purpose": "data_retention" } } }

The same verbs over HTTP:

curl -X POST http://localhost:9090/memory/remember \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"content":"Alice plans to renew in Q3.","purpose":"account_management"}'
 
curl -X POST http://localhost:9090/memory/recall \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"query":"Alice renewal","top_k":5,"purpose":"account_management"}'

Governance, Media & Ops (#949)

Purpose enforcement

Strict mode (default) — only registered purposes are allowed:

RELATA_PURPOSE_MODE=strict
RELATA_PURPOSES=analytics,audit,compliance,product_research

Open mode (dev/test only) — any non-empty purpose string is accepted:

RELATA_PURPOSE_MODE=open

Hierarchical scoping with : separator is supported (analytics:external).

Egress filtering

These classified types never appear in tool results even if queries touch them internally (ADR-057):

Error handling

MCP error envelope:

{
  "content": [{ "type": "text", "text": "error message" }],
  "isError": true
}

Deferred

watch / subscribe are not exposed over MCP — the SubscriptionManager + /watch/stream SSE surface is a long-lived event stream; the MCP tools/call request→response envelope cannot carry an open stream. Watch needs a streaming transport (MCP resources / notifications) rather than a synchronous dispatch arm.

SDK access (Python)

from relata import RelataClient, McpClient
 
with RelataClient(url, bearer_token=token, purpose="analytics") as client:
    mcp = McpClient.from_client(client)        # inherits auth + purpose
    profile = mcp.get_entity_profile("person-42", purpose="analytics")
    tools   = mcp.list_tools()                  # discovery
    custom  = mcp.call_tool("my_tool", {"arg": 1})  # generic dispatch

Vector search via MCP

{
  "name": "query",
  "arguments": {
    "sql": "PURPOSE 'product_research' SELECT id, title FROM Document WHERE SIMILAR(embedding, ARRAY[0.12, -0.34, 0.91, ...], threshold=0.75) LIMIT 10",
    "purpose": "product_research"
  }
}

Pass the embedding as a SQL ARRAY[...] literal, or bind via the Postgres wire protocol as a parameter (:query_embedding).