## MCP Server

Connect Claude Desktop, Claude Code, Cursor, Continue, Zed, or any MCP-compatible agent to SwarmRecall over stdio. The server exposes 52 tools and 4 resources covering every SwarmRecall module.

## Overview

The Model Context Protocol is an open standard that lets agents call tools and read resources over a JSON-RPC stream. SwarmRecall ships its MCP server in two transports so you can pick whichever fits your setup:

Local stdio — run swarmrecall mcp from the CLI. Best for Claude Desktop, Claude Code, Cursor, and any client that spawns MCP servers as subprocesses.
Remote HTTP — connect to https://swarmrecall-api.onrender.com/mcp over Streamable HTTP. Nothing to install; auth via your API key. Best for hosted clients, serverless agents, and teams that do not want to run a local process.

## 1. Install

The MCP server ships inside the SwarmRecall CLI:

npm install -g @swarmrecall/cli

Verify the install:

swarmrecall --version

Alternatively, if you use ClawHub, the skill will install the CLI for you:

clawhub install swarmrecall

## 2. Authenticate

swarmrecall register --save

Or, if you already have an API key, set it via environment variable:

export SWARMRECALL_API_KEY=sr_live_...

The MCP server reads SWARMRECALL_API_KEY first, then falls back to the saved config file. Override the API URL with SWARMRECALL_API_URL or swarmrecall config set-url when pointing at a staging deployment.

## 3. Configure your MCP client

### Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "swarmrecall": {
      "command": "swarmrecall",
      "args": ["mcp"],
      "env": {
        "SWARMRECALL_API_KEY": "sr_live_..."
      }
    }
  }
}

Restart Claude Desktop. SwarmRecall appears in the MCP menu.

### Claude Code

From any project directory:

claude mcp add swarmrecall -- swarmrecall mcp

Or add it manually to ~/.claude.json under mcpServers with the same shape as the Claude Desktop example.

### Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "swarmrecall": {
      "command": "swarmrecall",
      "args": ["mcp"],
      "env": { "SWARMRECALL_API_KEY": "sr_live_..." }
    }
  }
}

### Remote HTTP (no install required)

If your client supports remote MCP servers, point it at SwarmRecall directly — nothing to install locally:

{
  "mcpServers": {
    "swarmrecall": {
      "url": "https://swarmrecall-api.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer sr_live_..."
      }
    }
  }
}

The endpoint speaks the MCP Streamable HTTP transport. Authentication is the same SwarmRecall API key you use with the SDK or CLI — pass it as Authorization: Bearer sr_live_....

### MCP Inspector (for debugging)

# local stdio
npx @modelcontextprotocol/inspector swarmrecall mcp

# remote HTTP
npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url https://swarmrecall-api.onrender.com/mcp \
  --header "Authorization: Bearer sr_live_..."

## 4. Tools

### Memory (10)

memory_store	Store a memory (fact, preference, decision, context, session summary).
memory_search	Semantic search across memories.
memory_get	Fetch a memory by ID.
memory_list	List memories with optional filtering.
memory_update	Update importance, tags, metadata, or archived flag.
memory_delete	Permanently delete a memory.
memory_sessions_start	Start a new memory session.
memory_sessions_current	Get the currently active session.
memory_sessions_update	Update session state, summary, or mark ended.
memory_sessions_list	List sessions.

### Knowledge (11)

knowledge_entity_create	Create an entity (person, project, tool, concept).
knowledge_entity_get	Fetch an entity with its outgoing relations.
knowledge_entity_list	List entities with optional filtering.
knowledge_entity_update	Update an entity.
knowledge_entity_delete	Delete an entity and its relations.
knowledge_relation_create	Create a directed relation between two entities.
knowledge_relation_list	List relations.
knowledge_relation_delete	Delete a relation.
knowledge_traverse	Traverse the graph from a starting entity.
knowledge_search	Semantic search across entities.
knowledge_validate	Validate the graph against defined constraints.

### Learnings (9)

learning_log	Log an error, correction, discovery, optimization, or preference.
learning_search	Semantic search across learnings.
learning_get	Fetch a learning by ID.
learning_list	List learnings with filtering.
learning_update	Update status, priority, resolution, area, or tags.
learning_patterns	List recurring patterns detected across learnings.
learning_promotions	List patterns ready to be promoted into rules.
learning_resolve	Mark a learning as resolved.
learning_link	Link related learnings for pattern detection.

### Skills (6)

skill_register	Register a skill the agent has acquired.
skill_list	List registered skills.
skill_get	Fetch a skill by ID.
skill_update	Update a skill's version, config, or status.
skill_remove	Unregister a skill.
skill_suggest	Suggest skills relevant to a task context.

### Pools (2)

pool_list	List shared pools this agent belongs to.
pool_get	Get details for a specific pool and its members.

### Dream (14)

dream_start	Start a dream cycle for memory consolidation.
dream_get	Get details of a specific dream cycle.
dream_list	List dream cycles.
dream_update	Update a cycle status or attach results.
dream_complete	Mark a cycle as completed.
dream_fail	Mark a cycle as failed.
dream_get_config	Get the current dream configuration.
dream_update_config	Update dream configuration.
dream_get_duplicates	Fetch memory clusters above similarity threshold.
dream_get_unsummarized_sessions	Fetch completed sessions missing summaries.
dream_get_duplicate_entities	Fetch entity pairs that may be duplicates.
dream_get_stale	Fetch memories past the decay age.
dream_get_contradictions	Fetch memory pairs with divergent content.
dream_get_unprocessed	Fetch memories not yet processed for entity extraction.
dream_execute	Run Tier 1 server-side operations (decay, prune, cleanup).

## 5. Resources

Read-only resources for clients that surface resources as inline context. Each returns JSON.

swarmrecall://pools	Shared pools this agent belongs to with access levels.
swarmrecall://skills	Skills this agent has registered.
swarmrecall://sessions/current	The currently active memory session, if any.
swarmrecall://dream/config	The dream configuration (schedule, thresholds).

## 6. Troubleshooting

### "No SwarmRecall API key configured"

The server could not find SWARMRECALL_API_KEY in the environment or ~/.config/swarmrecall/config.json. Run swarmrecall register --save or set the env var in your MCP client config.

### 401 Unauthorized responses

Your key is invalid or revoked. Run swarmrecall config show to verify the active key, then swarmrecall register --save to mint a new one.

### Tools not appearing in Claude Desktop

Confirm which swarmrecall returns a valid path on your PATH. If npm i -g installed to a location your GUI Claude Desktop does not see, use the absolute path in the command field of your MCP config.

## What's next?

API Reference — every endpoint the MCP tools wrap.
SDK Guide — use @swarmrecall/sdk directly.
@swarmrecall/mcp on npm — embed the server in your own agent.