MCP Integration Guide

The smart-memory-mcp package is an MCP server that exposes SmartMemory operations to MCP-compatible clients (Claude Desktop, Cursor, Maya, custom agents). It is a separate package from smart-memory-core and ships its own tool catalogue.

For the full tool catalogue with signatures, see api/tools.md.

Install

pip install smartmemory-mcp

The console script is smartmemory-mcp (registered in pyproject.toml):

smartmemory-mcp                    # stdio transport (default)
smartmemory-mcp --http             # HTTP transport on 0.0.0.0:8011
smartmemory-mcp --http --port 9100 # custom HTTP port

You can also invoke the module directly: python -m smartmemory_mcp.

Backends

The server can route every tool call to one of two backends; the choice is independent of the tier model.

whoami() reports the active backend.

Tiers

Tools are registered into three tiers at server startup. Restarting the server is required after any tier-changing event (login, env var change).

FREE

login, whoami, switch_team, memory_ingest, memory_search, memory_recall (deprecated), get_working_context, memory_get, memory_export, memory_import, memory_migrate, memory_auto, memory_feedback.

PRO

PRO unlocks PRO-tier memory_* (CRUD: memory_add, memory_update, memory_delete, memory_clear, memory_list, memory_stats, memory_distill, memory_ingest_conversation, memory_search_advanced, memory_search_by_metadata) and the full decisions, code indexing, anchors, plans / failure recall, agent profiles, and structured ingestion suites.

PRO+

PRO+ adds reasoning, evolution, insights, dev workflow, and zettelkasten suites.

See api/tools.md for the complete per-tier list with signatures.

Authentication

Three sources are checked in order — the first non-empty value wins:

1. SMARTMEMORY_API_KEY environment variable.
2. The smartmemory_app desktop keyring (if installed).
3. The fallback file ~/.config/smartmemory/.api_key (written by the login tool).

Calling the login tool stores the key into the file fallback and validates it against the API. The server only re-reads credentials at startup, so:

restart the MCP server after login()

is mandatory.

switch_team(team_id) writes the new team ID into the smartmemory_app config and likewise requires a restart. Without the desktop app installed, set SMARTMEMORY_TEAM_ID instead.

Client configuration

Claude Desktop / Cursor

In the MCP client's config file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "smartmemory": {
      "command": "smartmemory-mcp",
      "env": {
        "SMARTMEMORY_API_KEY": "sm_live_...",
        "SMARTMEMORY_MCP_FULL_TOOLS": "true"
      }
    }
  }
}

HTTP transport

For multi-process deployments or browser clients, run in HTTP mode:

smartmemory-mcp --http --port 8011

Then point your MCP client at http://localhost:8011.

Calling a tool

Standard MCP tools/call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "query": "auth caching", "top_k": 5, "multi_hop": true }
  }
}

All tools return strings, except get_working_context which returns a structured surfacing-response dict.

Hosted MCP

For the managed SmartMemory Service there is also a hosted MCP server at https://mcp.smartmemory.ai/mcp. You run nothing yourself: each call is authenticated with OAuth through your SmartMemory account or with a SmartMemory API key, and runs as that caller. It exposes a fixed allowlist of tools rather than the full local tool catalogue. See Hosted MCP Server for setup.

Troubleshooting

• PRO tools missing after login — restart the MCP server. Tier is resolved once at startup.
• whoami reports Backend: remote (smartmemory package not installed) — install smartmemory for local backend, or this is expected if you intend remote-only.
• Tools time out: with the local backend, the first call can wait on loading the local models. Run sm warm once to preload them. With the remote backend, confirm the API URL is reachable.
• Permission warning on ~/.config/smartmemory/.api_key — the loader logs a warning if the file is group/other-readable. chmod 600 it.

See also

• MCP Tools API — every tool with its signature.
• SmartMemory API — Python API the tools wrap.