MCP Integration

The MemNexus MCP server gives AI agents direct access to memory tools. Agents can create, search, and manage memories without any custom code — the MCP protocol handles everything.

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. Instead of building custom integrations, you configure an MCP server and the agent gets native tool access.

MemNexus provides an MCP server that exposes 12 tools across memory management, conversations, the knowledge graph, behavioral patterns, and account operations.

Quick setup

1. Install the CLI and log in

The MemNexus CLI (mx) configures the MCP integration and runs the bridge that connects your agent to the hosted MCP server.

npm install -g @memnexus-ai/cli
mx auth login

mx auth login stores your API key in ~/.memnexus/config.json, so no secrets end up in your agent config files.

2. Configure your AI agent

Run mx setup and pick your agent, or target one directly:

mx setup                # interactive — detects installed agents
mx setup claude-code    # or configure a specific agent

Supported agent IDs: claude-code, claude-desktop, copilot, cursor, codex, opencode, chatgpt.

mx setup writes an MCP server entry that launches the bridge with mx mcp serve. For a JSON-config agent, the entry looks like this:

{
  "mcpServers": {
    "memnexus": {
      "type": "stdio",
      "command": "mx",
      "args": ["mcp", "serve"]
    }
  }
}

mx mcp serve is a stdio-to-HTTP bridge: your agent talks to it over stdio, and it forwards requests to the hosted MCP server at https://mcp.memnexus.ai/mcp using the API key from mx auth login.

3. Verify

Restart your AI platform. You should see MemNexus tools available. Try asking your agent:

"Search my memories for recent deployment notes"

You can also run mx setup verify to health-check every configured agent.

Available tools

The MCP server exposes 12 tools:

Memory tools

Tool	Description
create_memory	Save a new memory. Content is required; topics and entities are extracted automatically.
search_memories	Search memories by meaning, or list recent memories chronologically.
get_memory	Retrieve a memory by ID or name, with optional similar/related/conversation discovery.
manage_memory	Update or delete an existing memory.
recall	Get an AI-synthesized summary of a topic across your memory history.

Context and session tools

Tool	Description
build_context	Build a context briefing before starting work on a topic.
initialize_session	Return a refreshed working-memory brief (recent work, active decisions, gotchas).
conversations	List conversations, search them, or view one as a summary or timeline.

Knowledge and pattern tools

Tool	Description
knowledge_graph	Explore extracted facts, topics, and entities in the knowledge graph.
patterns	Work with behavioral patterns (list, detect, analyze, compile).

Account tools

Tool	Description
get_user_profile	Check account details: plan, quota, usage, and memory limits.
submit_feedback	Send a bug report, feature request, or question to the MemNexus team.

Tool parameters

create_memory

{
  "content": "Deployed v1.26.2 with OpenAPI validation fixes.",
  "topics": ["deployment", "core-api"]
}

Parameter	Type	Required	Description
content	string	Yes	The memory content. Topics and entities are extracted automatically.
topics	string[]	No	Extra tags for categorization
conversationId	string	No	Group related memories, or omit for auto-assignment
name	string	No	Key for a named memory (upserts a new version if it already exists)
memoryType	string	No	episodic, semantic, or procedural

search_memories

{
  "query": "deployment issues last week",
  "limit": 10
}

Parameter	Type	Required	Description
query	string	No	Natural language search query. Omit to list recent memories.
limit	number	No	Max results (default: 10)
recent	string	No	Time filter, e.g. 24h, 7d, 2w
topics	string[]	No	Restrict results to these topics

knowledge_graph

{
  "type": "facts",
  "query": "technical decisions this quarter"
}

Parameter	Type	Required	Description
type	string	Yes	facts, topics, related_topics, entities, entity_memories, or health
query	string	Depends	Search string (required for facts; optional for topics/entities)

Architecture

The bridge is a stateless translation layer between your agent and the hosted MemNexus MCP server:

AI Agent (Claude, Cursor, ...)
    │
    ▼ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────┐
│  mx mcp serve        │
│  (local bridge)      │
│  stdio → HTTP        │
└──────────┬───────────┘
           │ HTTPS
           ▼
┌──────────────────────┐
│  MemNexus MCP server │
│  mcp.memnexus.ai     │
│  Auth + Rate Limit   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Core API            │
└──────────────────────┘

The bridge runs locally and holds no state. It reads your API key from ~/.memnexus/config.json and attaches it to each request, so credentials never appear in agent config files.

Environment variables

These are read by mx mcp serve. All are optional — mx auth login and mx setup handle the defaults.

Variable	Description	Default
MX_API_KEY	API key override (normally read from ~/.memnexus/config.json)	From mx auth login
MX_MCP_URL	Hosted MCP server URL	https://mcp.memnexus.ai/mcp

Troubleshooting

Agent doesn't see MemNexus tools

1. Confirm the agent was configured: run mx setup verify
2. Restart the AI platform after running mx setup
3. Verify you are logged in: mx auth status

Tools fail with authentication error

1. Re-run mx auth login to refresh the stored key
2. Verify the key format: cmk_live_<id>.<secret>
3. Check the bridge logs: mx mcp logs

Connection timeout

1. Check your internet connection
2. Run mx mcp doctor for a full bridge and config health check
3. Check if a firewall is blocking outbound HTTPS (port 443)

Next steps

• Claude Desktop Setup — Detailed Claude Desktop integration guide
• Claude Code Setup — Claude Code integration guide
• Cursor Setup — Cursor integration guide
• Prompt Library — System prompts for memory-aware agents