MCP Servers
Memory integrates with the Model Context Protocol in two ways:
- Built-in MCP server — Memory itself is an MCP server. Clients like Claude Desktop or Cursor connect directly to Memory to read/write the knowledge graph.
- MCP registry — Per-project registry of external MCP servers that agents can call as tools.
Built-in Memory MCP server
Section titled “Built-in Memory MCP server”Memory is a remote MCP server: there is no local stdio subcommand to run.
The current spec transport is Streamable HTTP at /api/mcp; the project-scoped
SSE endpoints remain available for clients that speak only SSE.
| Transport | Endpoint | Authentication |
|---|---|---|
| Streamable HTTP (spec 2025-11-25, recommended) | /api/mcp — POST for JSON-RPC, GET for the server-initiated stream, DELETE to end the session |
X-API-Key: <api_token> + X-Project-ID: <project_id>, or Authorization: Bearer <api_token> |
| SSE (legacy, project-scoped) | GET /api/mcp/sse/<projectId>, POST /api/mcp/sse/<projectId>/message |
X-API-Key, Authorization: Bearer, or ?token=<api_token> |
| JSON-RPC over HTTP (legacy) | POST /api/mcp/rpc |
same token, as X-API-Key or Authorization: Bearer |
Send the project id as the X-Project-ID header on /api/mcp; the SSE routes
carry it in the path instead.
Tip:
memory mcp-guideprints these snippets for your server URL, with the token redacted to${MEMORY_PROJECT_TOKEN}(pass--show-secretto inline the real value). It uses your first project, so check theX-Project-IDvalue before pasting if you belong to more than one.
Connecting Claude Desktop
Section titled “Connecting Claude Desktop”Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{ "mcpServers": { "memory": { "type": "http", "url": "https://api.example.com/api/mcp", "headers": { "X-Project-ID": "<project-id>", "X-API-Key": "<your-api-token>" } } }}Clients that only implement the older SSE transport use the project-scoped endpoint instead — the project id is part of the URL there:
{ "mcpServers": { "memory": { "type": "sse", "url": "https://api.example.com/api/mcp/sse/<project-id>", "headers": { "X-API-Key": "<your-api-token>" } } }}A client that can only speak Authorization: Bearer works too: the same token
is accepted in that header. Clients that only support stdio need their own
documented bridge to a remote server — Memory does not ship a stdio mode.
Connecting OpenCode
Section titled “Connecting OpenCode”Add to opencode.json in your project directory:
{ "mcp": { "memory": { "type": "remote", "url": "https://api.example.com/api/mcp", "headers": { "X-Project-ID": "<project-id>", "X-API-Key": "<your-api-token>" }, "enabled": true } }}Replace <project-id> with your project UUID (memory projects list) and
<your-api-token> with a project-scoped API token. Run opencode mcp list to
verify the connection.
Available MCP tools (built-in)
Section titled “Available MCP tools (built-in)”The built-in server exposes tools including:
- Knowledge graph — create, update, search objects and relationships
- Documents — upload, list, retrieve documents
- Search — unified vector + keyword search
- Chat — create sessions, send messages
- Agents — list agents, trigger runs
- MCP registry —
search_mcp_registryandmcp-registry-get. Installing a registry entry (mcp-registry-install) requires a platform-admin token, since it opens an outbound connection. A project’s own servers are administered over REST, not through client tools — see Managing external servers
See
apps/server/domain/mcp/README.mdfor the complete tools, resources, and prompts reference.
Sending feedback about Memory
Section titled “Sending feedback about Memory”The built-in server exposes feedback-submit, and the same submission is
available over REST as POST /api/feedback. Both accept the credential you
already use and file the report as a GitHub issue, with your account, project and
basic environment details attached automatically — you never need to paste a
token or your email.
There is no strict template. Write what you were trying to do, what happened, and what you expected. If you can, add the steps that reproduce it and the exact error text; one or two sentences is fine when that is all you have.
{ "message": "The entity search tool returns stale results for a few minutes after an update.", "category": "bug", "severity": "medium", "include_context": true}category (bug, feature, usability, docs, other) and severity
(low, medium, high) are optional. include_context defaults to true;
set it to false to send only your message and account identity. A caller is
limited to a handful of submissions per hour, and an immediate retry of the same
text returns the issue created by the first call instead of filing a duplicate.
A deployment that has no feedback tracker configured answers 503 and sends
nothing anywhere — the endpoint is present, the destination is not.
Sharing a scoped key with someone else
Section titled “Sharing a scoped key with someone else”To hand an outside client — a teammate’s agent, a partner, a demo — access to one project without giving it your own token, create a share: a named key bound to the exact tools you choose.
In the web UI: Settings → MCP Servers → Sharing → New share. Name the share, tick the tools it may call, and optionally enter one or more email addresses under Email the key. Each recipient receives the endpoint, the key, and ready-to-paste client configs; the sender is named in the email.
Presets. The create form offers a preset row that ticks a curated tool set in one click — it replaces the current selection, and you can adjust the ticks afterwards:
| Preset | What it grants |
|---|---|
| Read-only (default) | Search, graph reads, document and journal reads, schema reads, skill reads, and agent/run reads. No MCP tool in this set writes. |
| Knowledge writer | Read-only plus creating, editing, and deleting objects, relationships, documents, and journal notes. |
| Schema & blueprints | Graph reads, then schema read/write, schema migrations, and blueprints. |
| Agent observer | Agent, run, question, and session reads, plus search and graph reads. |
| Documents | Upload, list, retrieve, and delete documents, plus document classification, keyword search, and semantic search. |
| Full access | Every tool a share key can carry. |
A share key is also an ordinary project API token, so the scopes behind the selected tools are honoured by the REST API as well as the MCP tools. Presets keep that set as narrow as the tools allow — the Documents preset, for example, grants document read/write and search but no knowledge or chat writes.
Presets never exceed what a share may grant: platform administration, project settings, credential minting, and agent execution/management are not shareable, so Full access is the ceiling rather than “admin”. Each preset’s tool count is resolved against your project’s catalog when the page loads, so it always matches the tools the backend currently offers.
The same data is available to API clients: GET /api/projects/{projectId}/mcp/tools
returns tools plus a templates array (id, label, description, tools,
toolCount, and default on the preselected one). Creating a share still sends
an explicit tools list — a template is a UI convenience, not a new request
field. The list is required: a request with no tools (or an empty array) is
rejected with HTTP 422. Shares created before the allowlist existed, and the
legacy POST /api/projects/{projectId}/mcp/share endpoint, keep an unrestricted
allowlist and remain read-only through their token scopes.
Copy an existing share. To start a new share from one that already works,
open its ⋯ menu → Duplicate share. The create form opens pre-filled with
that share’s description and tool selection, under a free name (<name> (copy),
or (copy 2) and so on when that name is taken); adjust anything and save. The
copy is an ordinary new share with its own key — the source share, its key, and
its invite recipients are untouched. Legacy shares can be copied this way too,
which is how you move off one, even though they cannot be edited.
The key is shown to you exactly once, on the creation screen. If you also entered recipients, they have their own copy; otherwise copy it before closing the dialog.
To send the key to someone after the share exists, open the share’s ⋯ menu → Invite by email. That emails the current key and the same ready-to-paste client configs, so anyone already using the share keeps working. Issue a new key in the same menu is the destructive alternative: the old key stops working immediately and its dialog offers the same optional email field. A share whose key was stored before the deployment enabled key encryption cannot be re-sent — the invite dialog says so and offers Issue a new key instead.
Who has the key, and what it did. A share records the addresses its key was emailed to: the Sharing list shows them (hover the chip for the full list) and marks a share read & write when its tools can modify the graph. The invite email says the same thing, so a recipient is never told a writable key is read-only. Choose View writes on a share to open the object browser filtered to the objects that share’s key created or last updated. The filter follows the share’s current key, so after Issue a new key it starts from that rotation instead of covering the retired key.
From the CLI: memory projects share-mcp --project my-project --email alice@example.com does the same through the legacy share endpoint and
mints one key per recipient.
Sharing only ever narrows access: a share token carries just the scopes its selected tools require, so it cannot reach project administration or other projects.
Brave Search integration
Section titled “Brave Search integration”The built-in server includes a brave_web_search tool backed by the Brave Search API. The API key can be set globally (via environment variable) or overridden per-org or per-project — see Built-in tool configuration below.
Built-in tool configuration
Section titled “Built-in tool configuration”Built-in tools can be enabled/disabled and configured at three levels. The most specific level wins:
project setting → org default → global env varIf a project has no explicit setting, it inherits from the org default. If neither is set, the global environment variable is used.
Available built-in tools
Section titled “Available built-in tools”| Tool | Env var (global fallback) | Config field |
|---|---|---|
brave_web_search |
BRAVE_SEARCH_API_KEY |
api_key |
Project-level configuration
Section titled “Project-level configuration”List the builtin server and its tools for your project:
# 1. Find the builtin server ID (auto-created on first list)curl "https://api.example.com/api/admin/mcp-servers?projectId=<projectId>" \ -H "Authorization: Bearer <token>"# → find the entry with "type": "builtin"
# 2. List its tools (includes inheritedFrom field)curl https://api.example.com/api/admin/mcp-servers/<builtinServerId>/tools \ -H "Authorization: Bearer <token>"Each tool in the response includes an inheritedFrom field: "project", "org", or "global", indicating where the current effective setting comes from.
Enable/disable a built-in tool at project level:
curl -X PATCH "https://api.example.com/api/admin/mcp-servers/<builtinServerId>/tools/<toolId>" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Set a per-project API key for brave_web_search:
curl -X PATCH "https://api.example.com/api/admin/mcp-servers/<builtinServerId>/tools/<toolId>" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "config": { "api_key": "BSA..." } }'Once set, this project’s agent runs use this API key instead of the global BRAVE_SEARCH_API_KEY.
Org-level defaults
Section titled “Org-level defaults”Org defaults apply to all projects in the org that have no project-level override.
List current org defaults:
curl https://api.example.com/api/admin/orgs/<orgId>/tool-settings \ -H "Authorization: Bearer <token>"Set an org default (enable + API key):
curl -X PUT "https://api.example.com/api/admin/orgs/<orgId>/tool-settings/brave_web_search" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "config": { "api_key": "BSA..." } }'Disable brave_web_search for all projects in the org by default:
curl -X PUT "https://api.example.com/api/admin/orgs/<orgId>/tool-settings/brave_web_search" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Remove an org default (projects fall back to the global env var):
curl -X DELETE "https://api.example.com/api/admin/orgs/<orgId>/tool-settings/brave_web_search" \ -H "Authorization: Bearer <token>"Inheritance example
Section titled “Inheritance example”Suppose you want brave_web_search enabled for most projects but one project should use a different API key:
Global env: BRAVE_SEARCH_API_KEY=BSA-global-key
Org default: enabled=true, api_key=BSA-org-key ← applies to all projects by default Project A: (no override) → uses org key (inheritedFrom: "org") Project B: api_key=BSA-project-b-key → uses project B key (inheritedFrom: "project") Project C: enabled=false → tool disabled for this projectThe MCP Integration settings page (Project Settings → Integrations → MCP Integration) has a Built-in Tools section where you can toggle tools and set config fields for the current project.
The Tool Defaults page (Project Settings → Organization → Tool Defaults) lets org admins set org-wide defaults for all built-in tools.
External MCP server registry
Section titled “External MCP server registry”Each project can register external MCP servers. These servers are proxied on demand and their tool catalogs are mirrored locally so agents can discover tools without connecting to every server on each request.
Server types
Section titled “Server types”| Type | type value |
Connection |
|---|---|---|
| Built-in (Memory) | builtin |
Internal; not configurable |
| Subprocess (local) | stdio |
Launches a command with arguments |
| Server-Sent Events | sse |
Long-lived HTTP SSE connection |
| Plain HTTP | http |
Per-request HTTP |
Managing external servers
Section titled “Managing external servers”List registered servers
Section titled “List registered servers”curl https://api.example.com/api/admin/mcp-servers \ -H "Authorization: Bearer <token>"Register a stdio server
Section titled “Register a stdio server”curl -X POST https://api.example.com/api/admin/mcp-servers \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "filesystem", "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"], "env": {}, "enabled": true }'Register an SSE server
Section titled “Register an SSE server”curl -X POST https://api.example.com/api/admin/mcp-servers \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "my-sse-server", "type": "sse", "url": "https://my-mcp-server.example.com/sse", "headers": { "Authorization": "Bearer <server-token>" }, "enabled": true }'Register an HTTP server
Section titled “Register an HTTP server”curl -X POST https://api.example.com/api/admin/mcp-servers \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "my-http-server", "type": "http", "url": "https://my-mcp-server.example.com/mcp", "headers": {}, "enabled": true }'Import a Claude MCP config
Section titled “Import a Claude MCP config”Memory can import the mcpServers format used by Claude Desktop
(claude_desktop_config.json), Claude Code (.mcp.json / ~/.claude.json), and
claude mcp add-json. Each valid entry is created; malformed entries and name
conflicts are reported without aborting the rest.
# From a filememory agents mcp-servers import --from-claude ~/.claude.json --device laptop-connector
# From stdincat claude_desktop_config.json | memory agents mcp-servers import --from-claude -
# Preview the plan without writingmemory agents mcp-servers import --from-claude ./.mcp.json --device laptop-connector --dry-runDelivery is chosen per entry by default (--target auto):
| Entry | Lands as |
|---|---|
http / sse (remote) |
a server-target registry row, connected outbound by the Memory host |
stdio (local command) |
a device-target registry row, pushed to the connector named by --device |
--target server forces every entry onto the Memory host; --target device
forces every entry onto the connector. A stdio entry without a device is a
broadcast, which only project admins may create. Existing names are skipped
unless --overwrite is passed. ${VAR} placeholders in env/headers values are
stored literally — Memory does not expand them.
The same import is available in the web UI (Settings → MCP Servers → Add server → Import from Claude) and over the REST API:
curl -X POST https://api.example.com/api/admin/mcp-servers/import \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "config": {"mcpServers": {"github": {"command": "npx", "args": ["-y", "pkg"]}}}, "target": "auto", "targetInstanceId": "laptop-connector", "overwrite": false, "dryRun": false }'The response lists created, updated, skipped, and failed entries.
Local stdio entries are better imported by the connector itself, which runs them on the machine that owns the command. In the macOS connector app open Hosted MCP Servers → Import from Claude…, or on a Linux connector run:
memory-connector mcp import --from-claude ~/.claude.json --dry-runmemory-connector mcp import --from-claude ~/.claude.json --overwriteThe connector import refuses while the connector is running (it would race the
config file); use the app or its loopback management API for a live connector.
An overwrite keeps the existing server’s enabled state and disabled_tools.
Inspect a server (preview tools without saving)
Section titled “Inspect a server (preview tools without saving)”curl -X POST https://api.example.com/api/admin/mcp-servers/<serverId>/inspect \ -H "Authorization: Bearer <token>"Returns the tool list from the live server without persisting anything.
Sync tool catalog
Section titled “Sync tool catalog”curl -X POST https://api.example.com/api/admin/mcp-servers/<serverId>/sync \ -H "Authorization: Bearer <token>"Connects to the server, calls tools/list, and upserts results into the local tool catalog. Safe to call repeatedly (idempotent).
List synced tools
Section titled “List synced tools”curl https://api.example.com/api/admin/mcp-servers/<serverId>/tools \ -H "Authorization: Bearer <token>"Enable / disable a tool
Section titled “Enable / disable a tool”curl -X PATCH https://api.example.com/api/admin/mcp-servers/<serverId>/tools/<toolId> \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Disabled tools are filtered from the agent context.
Update a server
Section titled “Update a server”curl -X PATCH https://api.example.com/api/admin/mcp-servers/<serverId> \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Delete a server
Section titled “Delete a server”curl -X DELETE https://api.example.com/api/admin/mcp-servers/<serverId> \ -H "Authorization: Bearer <token>"Official MCP registry
Section titled “Official MCP registry”Browse and install servers from the official MCP registry at registry.modelcontextprotocol.io.
Search the registry
Section titled “Search the registry”curl "https://api.example.com/api/admin/mcp-registry/search?q=github" \ -H "Authorization: Bearer <token>"Get details for a registry server
Section titled “Get details for a registry server”curl https://api.example.com/api/admin/mcp-registry/servers/github \ -H "Authorization: Bearer <token>"Install from the registry
Section titled “Install from the registry”curl -X POST https://api.example.com/api/admin/mcp-registry/install \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "serverName": "github", "config": { "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." } } }'This creates a new MCPServer record for your project and immediately runs a sync to populate the tool catalog.
Server entity reference
Section titled “Server entity reference”MCPServer — table kb.mcp_servers
| Field | Type | Description |
|---|---|---|
id |
UUID | Primary key |
projectId |
UUID | Owning project |
name |
string | Display name |
enabled |
bool | Disabled servers are not proxied |
type |
string | stdio | sse | http | builtin |
command |
string | Executable path (stdio only) |
args |
string[] | Arguments (stdio only) |
env |
object | Environment variables (stdio only) |
url |
string | Server URL (sse/http only) |
headers |
object | HTTP headers (sse/http only) |
createdAt |
timestamp | |
updatedAt |
timestamp |
MCPServerTool — table kb.mcp_server_tools
| Field | Type | Description |
|---|---|---|
id |
UUID | Primary key |
serverId |
UUID | FK → mcp_servers |
toolName |
string | As reported by the server |
description |
string | Tool description |
inputSchema |
object | JSON Schema for tool inputs |
enabled |
bool | Disabled tools are hidden from agents |
createdAt |
timestamp |
Hosted MCP servers (workspace)
Section titled “Hosted MCP servers (workspace)”For persistent, containerized MCP servers managed by the workspace system, contact your platform administrator.