MCP Server

The official Model Context Protocol server for MemoryRelay. Connects Claude Desktop, OpenClaw, and other MCP-compatible clients directly to your MemoryRelay instance.

Package: @memoryrelay/mcp-server

No install needed

MemoryRelay also serves these tools remotely at https://api.memoryrelay.net/mcp (Streamable HTTP, same API key). See Connect an agent. The package adds the pull and status commands: Use a workspace as a folder.

Installation

# Global install
npm install -g @memoryrelay/mcp-server

# Or run directly with npx (no install needed)
npx @memoryrelay/mcp-server

Claude Desktop Configuration

Add the following to your Claude Desktop MCP configuration file:

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

{
  "mcpServers": {
    "memoryrelay": {
      "command": "npx",
      "args": ["-y", "@memoryrelay/mcp-server"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_your_api_key"
      }
    }
  }
}

tip

If you installed the package globally, you can use "command": "memoryrelay-mcp" instead of npx.

Self-Hosted Instances

Point the server at your own deployment by adding MEMORYRELAY_API_URL:

{
  "mcpServers": {
    "memoryrelay": {
      "command": "npx",
      "args": ["-y", "@memoryrelay/mcp-server"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_your_api_key",
        "MEMORYRELAY_API_URL": "https://memory.your-domain.com"
      }
    }
  }
}

Tool Groups

The MCP server exposes 60 tools (@memoryrelay/mcp-server 0.6.0 or later); 55 of them are organized into the groups below, and five more (memory_maintenance, memory_batch_update, memory_recall_debug, agent_stats, agent_activity) are exposed only when all groups are enabled. By default, all groups are enabled. Configure which groups are active using the MEMORYRELAY_TOOLS environment variable.

{
  "env": {
    "MEMORYRELAY_API_KEY": "mem_your_api_key",
    "MEMORYRELAY_TOOLS": "core,icm"
  }
}

info

Enable only the tool groups your workflow needs. Fewer tools means less context for the LLM to parse, which improves tool selection accuracy and reduces token usage. Set MEMORYRELAY_TOOLS=all (or omit it) to enable everything.

core (31 tools)

Core memory, entity, and agent operations.

Tool	Description
memory_store	Store a new memory with content and optional metadata
memory_search	Semantic search across stored memories
memory_list	List memories with pagination
memory_get	Retrieve a specific memory by ID
memory_update	Update memory content or metadata
memory_delete	Soft-delete a memory
memory_batch_store	Store multiple memories in a single call
memory_context	Build a formatted context string from relevant memories
memory_health	Check the health of the MemoryRelay service
memory_status	Get the processing status of a memory
memory_extraction_status	Get entity extraction status for a memory
memory_extract_entities	Trigger entity re-extraction for a memory
memory_feedback	Submit relevance feedback on a memory
memory_bulk_delete	Bulk delete memories by IDs
memory_consolidate	Find and merge near-duplicate memories
memory_restore_merge	Restore a previously merged memory
entity_create	Create a new entity (person, org, technology, concept)
entity_link	Link an entity to a memory with a relationship label
entity_list	List entities with optional type filtering
entity_update	Update entity name or metadata
entity_delete	Delete an entity
entity_graph	Explore the knowledge graph around an entity
entity_merge	Merge two entities
entity_create_relationship	Create a relationship between entities
entity_delete_relationship	Delete a relationship between entities
entity_list_relationships	List all entity relationships
agent_list	List all agents
agent_create	Create a new agent
agent_get	Get agent details
agent_update	Update agent name or description
agent_delete	Delete an agent and its data

context (2 tools)

Context building and memory promotion.

Tool	Description
memory_promote	Update a memory's importance and tier
context_build_v2	Build context using v2 API with advanced ranking

icm (22 tools)

ICM workspaces (/v2/icm): pinned, versioned context an agent walks like a folder. When a workspace is configured, prefer these tools over memory search. Against a server without ICM every tool returns an explicit icm_unsupported result. No tool approves, publishes or merges: submitting a stage and proposing a draft return where a person decides.

Tool	Description
icm_capabilities	Report whether the server supports ICM, the build targets it offers and who the key is
icm_workspace_list	List the ICM workspaces the key can read
icm_root	The key's repositories across workspaces, with the route bound to each step
icm_release_get	Get a published release and its files
icm_route_list	List a workspace's routes
icm_search	Find the sections of workspace files that answer a question, ranked, with the path and lines to read
icm_context_build	Build pinned context for a target (route, stage, repository) within a token budget
icm_context_for	Build the context a person bound to this repository and step
icm_resolve	Resolve a repository and step to its bound workspace and route
icm_receipt_get	Get the receipt recording exactly what a build supplied, with origins and hops
icm_pull	The command that writes a workspace's live version to a local folder
icm_source_scan	Scan a Git source for ICM files
icm_score	A workspace's scorecard
icm_maintenance	What needs attention in a workspace, including its repositories
icm_run_start	Start a run (icm:run)
icm_stage_context	Context for the current stage of a run
icm_stage_write	Write a stage's outputs
icm_stage_submit	Submit a stage for a person's review
icm_run_status	Get the status of a run
icm_report_reads	Report what was read (icm:observe)
icm_draft_get	Read a workspace's draft
icm_draft_write	Write files into the draft
icm_draft_propose	Propose the draft: a person publishes it or merges the pull request

Configuration Reference

Variable	Required	Default	Description
MEMORYRELAY_API_KEY	Yes	--	Your MemoryRelay API key
MEMORYRELAY_API_URL	No	https://api.memoryrelay.net	API base URL
MEMORYRELAY_TOOLS	No	all	Comma-separated list of tool groups to enable (core, context, icm)
MEMORYRELAY_AGENT_ID	No	auto-detected	Agent identifier
MEMORYRELAY_TIMEOUT	No	30000	Request timeout in milliseconds
MEMORYRELAY_LOG_LEVEL	No	info	Log level (debug, info, warn, error)

Security

The MCP server includes several security measures:

• API key masking -- Keys starting with mem_ are masked in all log output. Only the first 8 characters are shown.
• Input validation -- All tool inputs are validated against Zod schemas before being sent to the API. Malformed requests are rejected client-side.
• Sanitized errors -- Error messages returned to the LLM are sanitized to prevent leaking internal details like stack traces or database errors.
• Stdio safety -- All logging is directed to stderr. Only valid MCP protocol messages are written to stdout, preventing log contamination of the protocol stream.

warning

The API key is passed via environment variables in the MCP configuration. Ensure your configuration file has appropriate file permissions (readable only by your user account).

Troubleshooting

Tools not appearing in Claude Desktop

1. Verify the MCP configuration JSON is valid (no trailing commas).
2. Restart Claude Desktop after editing the configuration.
3. Check stderr output for initialization errors.

Authentication errors

1. Confirm your API key starts with mem_ and has not expired.
2. Verify the key has the required scopes (read, write) for the tools you are using.

Connection timeouts with self-hosted instances

1. Ensure MEMORYRELAY_API_URL does not include a trailing slash.
2. Verify the API is reachable: curl $MEMORYRELAY_API_URL/v1/health.