Where should I start: API, MCP, or Playground?

Start with Playground for quick testing, then use API docs for production integration. Use MCP if your agent framework supports tool-calling workflows.

How do I authenticate API requests?

Pass your MemBrain API key in the request headers as documented in the API reference. Keep keys server-side in production.

Which endpoint stores a memory and is it synchronous?

Use the Store a memory endpoint. Ingestion is asynchronous and returns a job id that you can poll for completion status.

How do I search and traverse graph relationships?

Use search endpoints for semantic recall and graph endpoints for neighborhood expansion, path finding, and traversal across linked memories.

Where can I test requests before coding integration?

Use the Interactive Playground under Docs to run request flows and inspect responses before wiring your app.

Why are MCP tools not appearing in Cursor?

Restart Cursor after editing mcp.json and verify that the MCP server is running on localhost:8100. Check the mcp.json configuration file to ensure the command and arguments are correctly set.

How do I fix 401 errors with MemBrain MCP?

Ensure your X-API-Key header is present in the mcp.json configuration and that the key starts with mb_live_. The API key must be valid and have proper permissions for the operations you're attempting.

What if the MCP server is not responding?

Run curl http://localhost:8100/health to check if the server is running. If that command fails, the server hasn't started yet. Verify the server process is running and listening on port 8100.

How do I debug silent failures in MCP?

Set LOG_LEVEL=DEBUG as an environment variable and restart the server to see full request/response logs. This will help identify where the failure is occurring in the request chain.

MEMBRAIN

MCP Server

mem-brain-mcp · Model Context Protocol

MCP Server

The Mem-Brain MCP server exposes your memory as callable tools over the Model Context Protocol — run it locally, or connect to the hosted endpoint without installing anything.

Any MCP-capable client — Cursor, Claude Code, Claude Desktop, ChatGPT, Agno — can call search_memories, add_memory, and the rest automatically.

Local or remote
Run the MCP server on your machine, or connect to the hosted endpoint with OAuth.
Any MCP client
Cursor, Claude Code, Claude Desktop, ChatGPT, Agno — configure once and go.
Full tool surface
search_memories, add_memory, traverse_graph, stats, deletes, and agent instructions.
Stateless bridge
Each tool call hits the API with your auth; the client polls ingest so agents get a predictable contract.

Install

Two options — pick whichever you prefer:

bash

uvx mem-brain-mcp

The server starts on http://localhost:8100 by default. You can verify it's running:

bash

curl http://localhost:8100/health

Connect your client

Add this to ~/.cursor/mcp.json. Replace mb_live_xxx with your real API key.

~/.cursor/mcp.json

json

{  "mcpServers": {    "mem-brain": {      "url": "http://localhost:8100/mcp",      "headers": {        "X-API-Key": "mb_live_xxx"      }    }  }}

The MCP server is stateless — it proxies every tool call to the Mem-Brain API with your API key. You can run one server and share it across clients by passing different keys per client.

Mem-Brain memory writes are async at the REST layer, but the MCP client polls the ingest job for you. From the MCP tool perspective, add_memory(...) still behaves like a normal blocking tool call.

Available tools

Tool	What it does
`add_memory(content, tags?, category?, ingestion_scope?)`	Store a new memory; optional ingest-time tag scope for merge/link candidates
`search_memories(query, k?, response_format?, scope?, rerank?, full_scope?, keyword_filter?, scope_regex?)`	Semantic search; optional scope (API list), rerank (nodes only), full_scope (list all in scope); legacy `keyword_filter` / `scope_regex` are single-source aliases—do not combine
`traverse_graph(start_memory_id, query, ...)`	Semantic graph traversal along edge descriptions
`get_memories(memory_ids)`	Fetch specific memories by ID
`delete_memories(memory_id? \| tags? \| category?)`	Delete by ID, tag, or category
`get_stats()`	Count and metadata about your memory store
`get_agent_instructions()`	Returns a prompt snippet the agent can use as context

Search response formats

The response_format parameter on search_memories controls what comes back:

Value	Returns
`raw`	Memory nodes and graph edges
`interpreted`	LLM plain-language summary — best for injecting directly into context
`both`	Summary plus raw evidence

Example — search with interpreted response

bash

search_memories(query="What does the user prefer for their editor?", response_format="interpreted")

Environment variables

Variable	Default	Description
`API_BASE_URL`	hosted Railway URL	URL of your Mem-Brain API
`MEMBRAIN_API_KEY`	—	Fallback key for single-user local runs. Overridden by the per-request header.
`MCP_SERVER_PORT`	8100	Port the MCP server listens on
`LOG_LEVEL`	`INFO`	Set to `DEBUG` to log every tool call

Troubleshooting

Tools not appearing in Cursor: restart Cursor after editing mcp.json and check that the server is running.

401 errors: make sure your X-API-Key header is present and the key starts with mb_live_.

Server not responding: run curl http://localhost:8100/health — if that fails the server isn't up yet.

Silent failures: set LOG_LEVEL=DEBUG and restart to see full request/response logs.

MCP Server

Install

Connect your client

Available tools

Search response formats

Environment variables

Troubleshooting

See also