Connecting AI Assistants

AI assistants reach CortexDB over the Model Context Protocol (MCP). There are three ways to connect one, depending on where the assistant runs and who signs in:

The local MCP package

cortexdb-mcp (PyPI) is a small process the assistant starts on the same computer. It speaks MCP over stdio and calls your CortexDB server's REST API with the credential in its environment. It has the widest tool set: memory, access checks, conflicts, rollups, notices, the directory and the four code tools. Version 0.9.0 is the release for CortexDB 0.14.0: it takes a person's or an agent's token as its credential, and its --tool-profile chooses all (the default), read, write (adds publish and forget_by_key) or code. Install and per-client setup: MCP Server.

Use it when the assistant runs on someone's computer and can start a command. A connector app that runs in a vendor's cloud, such as ChatGPT, cannot start a local process; it needs a remote server.

Remote MCP on your server

Since 0.14.0 the CortexDB server can serve MCP itself at /mcp: streamable HTTP, stateless, one JSON-RPC message per POST, JSON answers. It is an OAuth 2.1 resource server: every call carries a principal's own signed token, and each tool call runs as the REST request that token would make, with the same checks. The operator key is not an MCP credential. It is off by default.

Turn it on

A setting that does not parse refuses the start (exit 78, MCP_CONFIG_INVALID). Clients reach the server through HTTPS: put /mcp behind your reverse proxy and set CORTEX_MCP_RESOURCE to the URL they use. GET /v1/admin/version lists mcp_http_v1 while the server serves /mcp.

The tools

A tool that names no scope uses the first allowlist entry; a scope outside the allowlist is refused inside the result (isError: true, SCOPE_NOT_ALLOWLISTED). Each tool carries MCP annotations (readOnlyHint, destructiveHint), so a client can ask before a destructive call.

Try it

On a server set up for tenant acme as in Org Trees, with Alice's region registered, and started with CORTEX_MCP=on, CORTEX_MCP_PROFILE=write and CORTEX_MCP_RESOURCE=https://memory.acme.example/mcp, mint a person's token (here with the server's own minter; in production your identity provider issues it):

ALICE_TOKEN=$(curl -sS -X POST "$CORTEX_URL/v1/auth/tokens" \
  -H "Authorization: Bearer $CORTEX_API_KEY" -H "Content-Type: application/json" \
  -d '{"subject": "user:alice", "scope": "org:acme", "ttl_seconds": 3600}' | jq -r .token)

Initialize, list the tools, then call them:

mcp() { curl -sS -X POST "$CORTEX_URL/mcp" \
  -H "Authorization: Bearer $ALICE_TOKEN" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -d "$1"; }

mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# {"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{"listChanged":false}},"instructions":"CortexDB long-term memory. …",
#  "protocolVersion":"2025-06-18","serverInfo":{"name":"cortexdb","version":"0.14.0"}}}

mcp '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# recall, decision_history, explain, remember, forget (the write profile)

mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"remember","arguments":{"text":"We decided to move the payments service to Postgres 17 in Q1."}}}'
# {"id":3,"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"Remembered at org:acme/user:alice: evt_01a186b11cec73f09f0a03ca1b944dd0"}],
#  "isError":false,"structuredContent":{"event_id":"evt_01a186b11cec73f09f0a03ca1b944dd0","status":"captured",…},"cacheScope":"private"}}

mcp '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"recall","arguments":{"query":"what did we decide about the payments database?"}}}'
# {"id":4,"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"[2026-10-29 08:05 UTC] We decided to move the payments service to Postgres 17 in Q1."}],"isError":false,…}}

The default allowlist, org:{tenant}/{principal}/*, is the caller's own region (org:acme/user:alice for Alice in tenant acme), so remember wrote there. A server-side client such as this one sends notifications/initialized after initialize (answered 202); no session id is issued or needed.

Sign-in with OAuth

Without a token, /mcp answers 401 with a pointer to its protected-resource metadata (RFC 9728), which names the authorization servers a client signs the person in with:

curl -sS -i -X POST "$CORTEX_URL/mcp" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
# HTTP/1.1 401 Unauthorized
# www-authenticate: Bearer resource_metadata="https://memory.acme.example/.well-known/oauth-protected-resource/mcp"

curl -sS "$CORTEX_URL/.well-known/oauth-protected-resource/mcp"
# {"authorization_servers":["https://login.acme.example"],"bearer_methods_supported":["header"],
#  "resource":"https://memory.acme.example/mcp","resource_name":"CortexDB"}

The authorization server is your identity provider, trusted through an issuers-file entry. For an access token that names the MCP resource as its audience, give the entry an alias from that audience to the tenant, and map people with directory mode so each token resolves to the person's principal:

[[issuer]]
id = "acme-idp"
iss = "https://login.acme.example"
format = "jwt"
algorithms = ["RS256"]
keys = ["keys/idp.pem"]            # the provider's public key; or jwks_url = "<its JWKS URL>"
max_lifetime_s = 3600

[issuer.subject]
mode = "directory"
kinds = ["user"]

[issuer.tenants]
allowed = ["acme"]
aliases = [{ aud = "https://memory.acme.example/mcp", tenant = "acme" }]

With that entry, an access token from https://login.acme.example whose aud is the MCP resource and whose subject is listed on Dana's directory entry calls /mcp as user:dana in tenant acme, and the default allowlist is org:acme/user:dana/*. A token with another audience is 401 WRONG_TENANT; the 401 carries error="invalid_token" when a credential was presented.

Connector apps: ChatGPT, Claude and others

A connector app that runs in its vendor's cloud connects to a remote MCP server by URL and signs the person in with OAuth. What it needs from you:

1. /mcp reachable at a public HTTPS URL, with CORTEX_MCP_RESOURCE set to that URL;
2. an identity provider that signs the person in for that app and issues an access token CortexDB accepts (the issuers-file entry above, its alias naming the resource);
3. each person in the tenant's directory, with the sign-in account their tokens carry.

ChatGPT's connectors and Claude's custom connectors use remote MCP over HTTPS with OAuth, the shape /mcp serves. CortexDB has not yet been run end to end with ChatGPT against /mcp, so treat a direct ChatGPT connection to your own server as untested; Team-CortexDB connects ChatGPT and Claude today. A browser-based MCP client is not supported yet (/mcp allows no MCP header in CORS).

Limits

• /mcp runs on a plain node: a cluster ingress answers 501 CLUSTER_ROUTE_UNSUPPORTED, and a cluster data node refuses CORTEX_MCP=on.
• It is stateless and answers JSON only: GET and DELETE /mcp answer 405, and no event stream is opened.
• Check a server before you point an app at it: it serves /mcp only while GET /v1/admin/version lists mcp_http_v1. CortexDB Cloud's API does not list it today; use the local package there.

Team-CortexDB on the customer portal

Team-CortexDB is a company's team brain, set up from the customer portal (customer.cortexdb.ai, Team-CortexDB › Setup): CortexDB on your own server with a door in front of it that connects your team's AI tools, holds the company's rules and syncs your sources. The setup page connects each kind of app its own way:

• Coding agents (Claude Code, Cursor, Codex and others): one setup run, from a message for the agent or a terminal command the page gives you, connects the apps you tick on that computer (and, with "Find more on my computer", the others it finds).
• ChatGPT and Claude (Claude on desktop, web and mobile) are connector apps that sign in through the portal: in the app's own connector settings you add the address the page shows (https://<your door>/h/<app>/mcp), the app opens the portal's sign-in, and the person allows it. No key is copied. The page shows the steps for each app.
• Any other app that can use a remote MCP server over HTTP: the same address, signing in with OAuth where the app supports it, else a connection key sent as a header.

Each connection is listed under Your computers on the setup page and can be revoked there.

The portal also serves an MCP endpoint of its own, https://customer.cortexdb.ai/mcp, for your coding agents to read releases and docs, ask CortexHelper and run Scope Studio. It takes an agent key from the portal's Agent keys page (Authorization: Bearer <agent key>); it holds none of your memories.

See also

• MCP Server · CortexDB for AI Coding Agents
• Identity and Tokens · Shared Memory