OAuth MCP connector / tools-only

Connect customer memory to AI clients.

ContextDB exposes six scoped memory tools at https://api.contextdb.ai/mcp. Marketplace clients use OAuth 2.1 with PKCE and refresh-token rotation. ContextDB binds each grant to one account, project, and private memory partition.

POST /mcp · application/json · tools/* only · stateless

Protocol boundary

One authenticated request, one JSON response.

OAuth grants derive the organization, project, and private user partition on the server. Trusted backend integrations may still use a project key and explicit user_id.

Transport POST /mcp · JSON-RPC 2.0

Single request objects in, application/json responses out.

Capability tools/list · tools/call

tools/* is the only advertised capability.

Scope OAuth grant → project + bound partition

Marketplace tools cannot name another organization, project, or user partition.

Not included SSE · sessions · resumability · server messages

No full-protocol support is claimed.

CURRENT STATUS The endpoint is part of the hosted alpha and is not production-ready. It covers the bounded tools contract described here, not every MCP capability or client transport.

Tool directory

Six scoped memory operations.

Service-key arguments mirror the hosted HTTP routes. OAuth schemas omit user_id because the server binds it. Writes require provenance, ordinary recall does not authorize an action, and action recall returns an explicit policy outcome.

remember user_id · content · source

Store one sourced memory in the caller's user partition.

recall user_id · query · top_k

Retrieve context for grounding a response, not for action authorization.

recall_for_action user_id · query · top_k

Return trusted action evidence plus act, ask, or abstain.

pending_confirmations user_id

List memories awaiting scoped confirmation.

confirm user_id · memory_id

Record authenticated project-credential context against one scoped memory.

forget user_id · memory_id | entity + attribute

Delete one memory or clear one slot. Whole-partition erasure stays on HTTP and the console.

Client setup

Point an OAuth-capable client at one endpoint.

Add the URL without a project key. The client discovers OAuth metadata, opens the ContextDB consent screen, and receives a revocable token.

{
  "mcpServers": {
    "contextdb": {
      "url": "https://api.contextdb.ai/mcp"
    }
  }
}

Add to Cursor → Install from Cursor Directory → View the open-source plugin → Review connected clients →

OAuth tools derive the memory partition from the grant and do not accept caller-supplied user_id. Tools: remember, recall, recall_for_action, pending_confirmations, confirm, and scoped forget. Whole-partition erasure requires the idempotent HTTP or console path.

Client compatibility

One OAuth endpoint for marketplace clients.

The connector advertises Streamable HTTP, OAuth discovery, dynamic client registration, PKCE, refresh tokens, revocation, and explicit tool safety annotations.

ChatGPT Plugins / OpenAI review

Submitted for OpenAI plugin review on September 30, 2026. Vendor review is in progress, so ContextDB is not yet in the ChatGPT plugin directory.

Claude Custom connector / Directory

Use the remote Streamable HTTP URL. Directory publication still requires Anthropic organization access and review.

Cursor mcp.json / Cursor Directory

Add the URL directly or install the ContextDB listing on Cursor Directory. OAuth starts on first connection.

Grok Custom connector / Grok Build

Add the same remote URL. OAuth grants remain revocable in ContextDB settings.

Lovable Custom MCP / registry

Connect the URL as a chat connector or discover io.github.atomsai/contextdb-memory through an MCP registry.

OFFICIAL MCP REGISTRY io.github.atomsai/contextdb-memory@0.1.0 is published and points to the production OAuth endpoint. Vendor-specific directories still require their own review.

Host enforcement

A tool result advises the host. It does not run the action.

ContextDB returns and records the decision. The customer host must pause on ask, stop on abstain, and apply its own business authorization before continuing on act.

Act outcome == "act"

The host may continue only after its own authorization checks.

Ask outcome == "ask"

The host pauses the action and asks for an attestation.

Abstain outcome == "abstain"

The host does not run the action without another authorized path.

Confirm confirm · recall_for_action

After the host retains any end-user attestation, confirm and evaluate the action again.

An API-key MCP confirmation records authenticated project-credential context against one scoped memory. An OAuth MCP confirmation records the authorizing ContextDB user and server-bound partition. The customer host authenticates any separate application end user and retains any end-user attestation. A Console confirmation records operator context. No confirmation proves objective truth. ContextDB advises. The customer host enforces. An act result is not permission to bypass host authorization.

Static call trace

Resolve an ask, then evaluate again.

The host authenticates the end user and retains any attestation before the confirmation call records project-credential context. The second action recall applies policy to the updated evidence state.

tools/call recall_for_action {"user_id": "caller-1", "query": "book Friday"}
-> {"outcome": "ask", "memories": [], "pending_confirmation_ids": ["…"]}

# the host authenticates the end user and retains the attestation

tools/call confirm {"user_id": "caller-1", "memory_id": "…"}
-> {"memory": {"confirmed": true, "…": "…"}}

tools/call recall_for_action {"user_id": "caller-1", "query": "book Friday"}
-> {"outcome": "act", "memories": ["…"]}

# the host still authorizes and executes the booking itself

Inspect the bounded MCP tools contract.

Start with the quickstart, then connect a compatible client to the hosted-alpha endpoint.

Configure the MCP client How the gate works