MCP server

Zekra's MCP server gives any Model Context Protocol client memory tools: recall, retain, graph queries, brains, secrets and data sources.

The server speaks MCP over stdio. It is a thin adapter over the REST API. Each tool call becomes one HTTPS request to your Zekra instance, carrying your token. All access checks and validation happen on the server.

MCP client --stdio--> zekra mcp --HTTPS + X-Zekra-Token--> Zekra API (app.zekra.dev)

Two binaries

Binary	Where it comes from	Tools
zekra mcp (recommended)	The zekra CLI. Install with curl, npm or go install.	Memory, brains, access control, chat, secrets and data sources: 24 listed tools. Adds brain_create.
zekra-mcp	Built from cmd/zekra-mcp in the Zekra server repository	The full set of 31 tools, including the graph_* tools, memory_share, memory_dedup and memory_recall_archive

Both read the same environment variables and call the same API. Use zekra mcp unless you need the graph tools. To build zekra-mcp, clone the server repository and run:

Configuration

Variable	Meaning
ZEKRA_API_URL	Base URL of the Zekra app. Default: https://app.zekra.dev
ZEKRA_TOKEN	Your access token (cbt_…), sent as X-Zekra-Token. It decides which brains you can read and write.
ZEKRA_AGENT_ID	Optional agent label, sent as X-Agent-Id. With a token, the token's identity is used instead.
ZEKRA_DEFAULT_NAMESPACE	Optional. Binds the session to one brain: any tool call without a namespace argument uses this brain.

zekra mcp also falls back to the values saved by zekra auth login in ~/.zekra/config.json. Legacy CABRAIN_* variable names are still accepted; a ZEKRA_* value always wins.

Client setup

The fastest path is the CLI, which writes the right file for each client:

Use zekra mcp:print <client> to see the snippet without writing anything. To configure a client by hand, use the snippets below. If you use zekra-mcp, set "command": "zekra-mcp" and remove args.

Claude Code

Project scope, in .mcp.json at the repository root (--user makes the CLI write ~/.claude.json instead):

Or from the Claude Code CLI:

For Claude Code there is also a plugin that bundles the MCP server, slash commands, agents and hooks.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Desktop may not find binaries on your shell PATH. If the server fails to start, use the absolute path to zekra. zekra mcp:install writes the absolute path for you.

Cursor

~/.cursor/mcp.json:

Codex

~/.codex/config.toml:

Gemini CLI

~/.gemini/settings.json:

Any other MCP client

Any client that can launch a stdio server works. Run zekra mcp (or zekra-mcp) with the environment variables above. The server implements initialize, ping, tools/list and tools/call, and reports protocol version 2024-11-05.

Remote MCP (OAuth)

Zekra also runs a hosted MCP server at https://mcp.zekra.dev (Streamable HTTP). Clients that support remote MCP connect with just the URL and sign in with OAuth 2.1; no binary, no token to paste. On the consent screen you pick which brains the client may use, read or read + write. Manage or revoke access later under Account → Connected apps in the console.

Client	How to connect
Claude.ai / Claude Desktop	Settings → Connectors → Add custom connector → paste https://mcp.zekra.dev (leave client id/secret empty) → Connect
ChatGPT	Settings → Apps & Connectors → Advanced → Developer mode → Create connector → URL https://mcp.zekra.dev, authentication OAuth
Claude Code	claude mcp add --transport http zekra https://mcp.zekra.dev, then /mcp to sign in
Cursor	{"mcpServers":{"zekra":{"url":"https://mcp.zekra.dev"}}} in ~/.cursor/mcp.json, or zekra mcp:install cursor --remote
Gemini CLI	{"mcpServers":{"zekra":{"httpUrl":"https://mcp.zekra.dev"}}} in ~/.gemini/settings.json

The remote server exposes the same tools as the stdio server, from one shared registry (GET https://app.zekra.dev/api/mcp/tools lists them). OAuth apps never see the token, delete, vault-reveal or connector tools, and every call is re-checked against your grant and your current access to the brain. Discovery documents: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on mcp.zekra.dev.

Clients without remote MCP support (for example Codex) keep using the stdio server above.

Tool results and errors

Every tool returns one text content block that holds the JSON response of the matching REST endpoint. When the API answers with an error, the result has isError: true and the body carries the structured error:

Error codes are listed in the REST API reference. An unknown tool name returns JSON-RPC error -32602.

Tool reference

Argument names are exactly as the tools declare them. Some tools use snake_case and some use camelCase. Access is what the calling token needs on the brain: read, write or admin. Tools marked zekra-mcp are only in the zekra-mcp binary. brain_create is only in zekra mcp.

Memory

memory_recall

Hybrid recall inside one brain: vector search and BM25 fused with RRF, a salience signal, reranking and optional one-hop entity expansion. Access: read.

Argument	Type	Required	Notes
namespace	string	yes	Brain to read
query	string	yes	Short, keyword-forward queries rank best
limit	integer		Results after reranking (default 8)
expand_entities	boolean		One-hop entity expansion (default true)
min_importance	number		Drop memories below this importance
types	string[]		zekra-mcp. Only memories whose metadata.type is in this list
exclude_source_kinds	string[]		zekra-mcp. Drop memories from these sourceKind values

Returns { "results": [ { id, content, score, network, memoryType, sourceKind, sourceRef, importance, validAt, viaEntity? } ] }. An empty result is recorded as a knowledge gap.

memory_retain

Store a memory. The server runs the write decision (add, update, invalidate or noop), embeds and indexes the text, and vaults any secrets it detects. Access: write.

Argument	Type	Required	Notes
namespace	string	yes
content	string	yes	Raw or distilled text, in any language
source_kind	string	yes in zekra-mcp	Where it came from. zekra-mcp accepts claude_code, coder_run, whatsapp, slack, chat, manual.
source_ref	string		Session, thread or run id
importance_hint	number		0 to 1. A nudge that is blended in, not a final value
visibility	string		private (default), team or global

Returns { "id", "decision", "importance", "supersededId"? }.

memory_get

Fetch one memory by id with full provenance. Access: read.

Argument	Type	Required
namespace	string	yes
id	string (UUID)	yes

memory_edit

Change a memory's content (which re-embeds it), importance or metadata. Access: write.

Argument	Type	Required	Notes
namespace	string	yes
id	string	yes
content	string		New content
importance	number		0 to 1
metadata	object		Replaces the existing metadata

memory_forget

Soft-delete a memory. It sets invalidAt and never removes the row. Access: write.

Argument	Type	Required	Notes
namespace	string	yes
id	string	yes
reason	string		Recorded with the memory

memory_share

Grant another agent identity access to a brain. The caller needs write access on the brain. Listed by zekra-mcp. zekra mcp accepts the call but does not list it.

Argument	Type	Required	Default
namespace	string	yes
grantee_agent_id	string	yes
can_read	boolean		true
can_write	boolean		false

memory_dedup (zekra-mcp)

Soft-invalidate duplicates in a brain: memories with the same sourceRef are collapsed to the newest one. Access: write.

Argument	Type	Required	Notes
namespace	string	yes
sourceKind	string		Limit to one source kind

Returns { "namespace", "sourceKind", "invalidated": <count> }.

memory_recall_archive (zekra-mcp)

Reserved for deep recall over the cold storage tier. It is not implemented yet and always returns an unavailable error.

memory_gaps

List knowledge gaps: queries whose recall came back empty, deduplicated and counted.

Argument	Type	Notes
namespace	string	Optional filter
status	string	open, indexed, dismissed or all. Default: open and indexed
limit	integer	Default 100

memory_resolve_gap

Close a gap after you retain the missing knowledge (indexed), or drop it (dismissed).

Argument	Type	Required
id	integer	yes
status	string: indexed, dismissed or open	yes
resolution	string

Brains

brain_list

List brains with their memory counts. No arguments.

brain_details

One brain in detail: memory count, counts by type and source, open gaps, recall count and first and last dates. Argument: namespace (required).

brain_create (zekra mcp only)

Create a brain by storing a first marker memory in it. Arguments: name (required) and description. Access: write on the new namespace.

brain_delete

Delete a brain and all of its memories. This cannot be undone. Access: write.

Argument	Type	Required	Notes
namespace	string	yes
confirm	string	yes	Must equal namespace. zekra mcp also accepts true.

brain_chat

Ask a brain a question. An agent recalls and searches the brain, answers only from what it finds, and returns citations. Access: read.

Argument	Type	Required	Notes
namespace	string	yes
message	string	yes
topK	integer		Memories to ground on (default 8)

Returns { "answer", "citations": [...], "footprint": { recalled, model, provider, mode, grounded, iterations, steps } }.

Access control (admin)

These tools need an admin token.

Tool	Arguments	What it does
brain_create_token	agentId (required), label, isAdmin (default false)	Mint a token for an agent identity. Returns the token once.
brain_tokens	includeRevoked (default false)	List tokens with their grants
brain_grant	agentId, namespace (both required), canRead (default true), canWrite (default false)	Create or update a grant
brain_revoke_grant	agentId, namespace (both required)	Remove a grant

Secrets vault

Tool	Arguments	Access	What it does
secret_list	namespace	read	Secret names and masked hints. Never values.
secret_store	namespace, name, value (required), kind	write	Store or replace a secret. kind is one of api_key, password, env, token, private_key, connection_string, generic.
secret_reveal	namespace, name	write	Decrypt and return the value
secret_delete	namespace, name	write	Delete a secret

Data sources

Tool	Arguments	Access	What it does
datasource_list	namespace	read	Connectors with status, document count and last sync
datasource_create	namespace, kind, name (required), config	write	Add a connector. kind is one of text, markdown, crawler, github, sql, webhook.
datasource_sync	id	write	Run a connector now. Returns { ingested, status }.
datasource_delete	id	write	Remove a connector. Memories it already ingested stay.

Connector config keys are listed in Data sources.

Graph (zekra-mcp)

Tool	Arguments	What it does
graph_ontology	namespace	The brain's entity types and relation types with live counts. Call this first to learn valid names.
graph_traverse	namespace, entity (required), depth (default 2, max 6), relations[], types[], direction (out, in or both), asOf (RFC 3339), limit	Multi-hop walk from a named entity. Returns each reachable entity with its depth and path.
graph_neighbors	namespace, entity (required), asOf	Direct typed relations of one entity, with direction and a readable fact
graph_path	namespace, from, to (required), maxDepth (default 4, max 6)	Shortest relation path between two entities
graph_spine	namespace, entity (required), depth (default 2, max 4), hubs[], roles[], perGroup (default 10, max 200), window (such as 24h, 7d, 2w, 3m), since, until, timeRoles[]	Everything connected to one entity in one call, grouped by role. Each group gives the true total next to a capped sample.

All graph tools need read access on the brain.