MCP & agents

Memora exposes the vault to agents through the Model Context Protocol. The server speaks JSON-RPC 2.0 over the Streamable HTTP transport at /mcp, on the same port as the HTTP API and the web UI. There is one MCP endpoint and one tool catalog.

initialize answers with the protocol version the client asks for when it is one of the three above, and with 2025-06-18 otherwise.

Transport#

• Requests are JSON-RPC 2.0 objects sent with POST /mcp. Batches (JSON arrays) are not supported.
• Responses are plain JSON (application/json). The server does not open SSE streams and does not issue an Mcp-Session-Id.
• GET and DELETE on /mcp return 405 Method Not Allowed with Allow: POST.
• A notification (a notifications/* method without an id) gets 202 Accepted and no body.
• /mcp needs a configured vault. Until one is chosen it returns 409 {"error":"vault not configured","needs_vault":true}.
• A browser session (cookie) may also call /mcp. It then needs a same-origin request, like the rest of the JSON API.

The server speaks Streamable HTTP only. A client that can only launch local stdio servers can use a bridge such as mcp-remote (see below).

Connecting an agent#

With an API key#

Create a key in the web UI (Keys page), with memora-cli (/keys), or with POST /api/keys. The raw key (memora_live_...) is shown once. By default a key gets the scopes mcp, read and write and may call every tool. See Tool switches and per-key permissions to narrow it.

Use http://localhost:8400/mcp for a local install, or your public URL such as https://memory.example.com/mcp behind a reverse proxy. When the server sets MEMORA_DOMAIN or MEMORA_BASE_URL, requests for any other host get 404, so use that domain.

Claude Code:

claude mcp add --transport http memora https://memory.example.com/mcp \
  --header "Authorization: Bearer memora_live_REPLACE_WITH_YOUR_KEY"

Cursor, Windsurf and other clients with an mcpServers JSON config (VS Code uses the key servers in .vscode/mcp.json):

{
  "mcpServers": {
    "memora": {
      "type": "http",
      "url": "http://localhost:8400/mcp",
      "headers": {
        "Authorization": "Bearer memora_live_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Codex (~/.codex/config.toml), with the key in the MEMORA_API_KEY environment variable:

[mcp_servers.memora]
url = "https://memory.example.com/mcp"
bearer_token_env_var = "MEMORA_API_KEY"

Clients that only run local stdio servers, such as the Claude Desktop config file, can bridge with mcp-remote (needs Node.js):

{
  "mcpServers": {
    "memora": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://memory.example.com/mcp",
        "--header", "Authorization: Bearer memora_live_REPLACE_WITH_YOUR_KEY"
      ]
    }
  }
}

Some clients send the key as X-API-Key: <key> instead. Both headers are accepted.

With OAuth#

Clients that support MCP authorization (for example Claude and ChatGPT custom connectors, or Claude Code without a --header) can connect with only the URL:

claude mcp add --transport http memora https://memory.example.com/mcp

The flow:

1. The client calls /mcp without credentials and gets 401 with WWW-Authenticate: Bearer resource_metadata="https://memory.example.com/.well-known/oauth-protected-resource".
2. It reads the protected resource metadata (RFC 9728) and the authorization server metadata at /.well-known/oauth-authorization-server (RFC 8414; also served at /.well-known/openid-configuration and under a /mcp suffix).
3. It registers itself with dynamic client registration at POST /oauth/register (RFC 7591), or uses an HTTPS client metadata document URL as its client_id. The owner can also register clients in the web UI. Redirect URIs must be HTTPS, or plain HTTP on localhost, 127.0.0.1 or [::1].
4. It opens /oauth/authorize (authorization code with PKCE S256 only). The browser lands on the Memora sign-in page, and the signed-in owner approves or denies the connection on a consent card. Codes are valid for 10 minutes.
5. It exchanges the code at POST /oauth/token and receives an access token and a refresh token. The only OAuth scope is mcp.

The access token is a regular Memora API key named after the client. It starts with the default scopes (mcp, read, write) and every tool, and it shows up on the Keys page like any other key, so you can restrict, disable or delete it there. The access token has no expiry. A refresh_token grant replaces it with a fresh one (the old token stops working at once) and rotates the refresh token. Disabling or deleting the key ends the connection.

Set MEMORA_BASE_URL (for example https://memory.example.com) when the server runs behind a proxy, so the issuer and endpoint URLs in the metadata are the public ones. Without it the server derives them from the request headers.

Test from a shell#

curl -s -X POST http://localhost:8400/mcp \
  -H "Authorization: Bearer memora_live_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Discovery card#

GET /.well-known/mcp.json needs no auth and returns:

The card is the same for every caller. To see what a given key may call, use tools/list with that key.

Methods#

There are no prompts, no pagination cursors and no change notifications.

Resources#

resources/read returns {contents: [{uri, mimeType, text}]}.

Results and errors#

A successful tool call returns the tool's JSON result as text:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{...}" }],
    "isError": false
  }
}

A tool that fails (bad arguments, note not found, unknown tool name) returns the same envelope with isError: true and the error message as the text. The HTTP status stays 200.

JSON-RPC errors:

HTTP errors before JSON-RPC runs:

What each key sees#

tools/list is filtered per caller:

• A tool switched off on the server is hidden for everyone.
• A key whose tool list is not "*" only sees the tools in its list.
• A key without the write scope only sees read-only tools.
• Admin tools are added for keys with the admin scope (and for browser sessions).

tools/call on a tool that tools/list would hide returns -32003. Details are in Tool switches and per-key permissions.

Privacy rules#

The owner can hide notes and folders from specific agents (web UI, /api/privacy, or the privacy_* admin tools). For an API key covered by a rule, every tool works as if the hidden paths did not exist: they are left out of listings, search, the graph, tags, events, logs, locks and folder metadata; a hidden path named in an argument is answered as not found, for reads and writes alike; and folder operations that would carry hidden items along are refused. If the rules cannot be read, the key sees nothing (fail closed). Browser sessions are never filtered.

Tools#

R = read-only (needs only the mcp scope). W = changes the vault or server state (also needs the write scope). Unless marked required, arguments are optional. Paths are vault-relative, for example Projects/Plan.md.

Notes (note)#

Search (search)#

Query (query)#

Tags (tag)#

Folders (folder, ops)#

Graph (graph)#

Versioning (version)#

Bulk writes (write)#

Collaboration (collab)#

Activity and health (ops)#

Identity (identity)#

Import and export (interop)#

The exchange folder is memora-exchange in the server's temporary directory. Tools never read or write anywhere else on the server's disk.

Checks, to-dos and pins (ux)#

Pins are shared by every browser of the owner (/api/pins). They follow their note or folder through renames and moves done by Memora (over MCP or HTTP, including notes inside a moved folder) and are removed when the item is deleted or moved to the trash; deleting a folder removes every pin under it. A key whose privacy rules hide a path neither lists nor changes its pin, and position counts only the pins the key can see.

Admin tools (admin)#

Listed and callable only for keys with the admin scope (and for browser sessions). They are not part of the switchable catalog: global tool switches and a key's tool list do not apply to them, and they do not need write.

When kind is omitted it is taken from the path on disk: a folder if a folder exists there, otherwise a note.

Identity and tracking#

Every tool call is published to the web UI's realtime activity stream as an ai_activity start and end pair, named after the API key (or the signed-in user), with the note paths involved. Calls are also counted per key: the Keys page and GET /api/keys show each key's uses, last_ip, and the tools it has called recently. initialize registers the connection under the key's name (GET /api/aliases). set_my_name changes the alias shown in the activity feed and log, and set_my_color changes the key's color in the UI. See API.md for the HTTP endpoints.