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 19 tools across memory management, conversations, topics, patterns, and graph-based retrieval.

Quick setup

1. Install

npm install -g @memnexus-ai/mcp-server

2. Configure your AI platform

Add MemNexus to your MCP configuration:

{
  "mcpServers": {
    "memnexus": {
      "command": "npx",
      "args": ["@memnexus-ai/mcp-server"],
      "env": {
        "MEMNEXUS_API_KEY": "cmk_live_xxx.yyy"
      }
    }
  }
}

Config file locations:

Platform	Config path
Claude Desktop (macOS)	~/.config/claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%/Claude/claude_desktop_config.json
Claude Code	.claude/settings.json or via MCP settings
Cursor	.cursor/mcp.json

3. Verify

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

"Search my memories for recent deployment notes"

Available tools

The MCP server exposes 19 tools organized into 5 categories:

Memory tools

Tool	Description
create_memory	Create a new memory with content, topics, and importance
search_memories	Semantic search across all memories
get_memory	Retrieve a specific memory by ID
list_memories	List memories with pagination
update_memory	Update an existing memory
delete_memory	Delete a memory

Conversation tools

Tool	Description
list_conversations	List all conversations
get_conversation_summary	Get summary of a conversation
get_conversation_timeline	Chronological timeline of memories in a conversation

Topic tools

Tool	Description
search_topics	Search for topics
discover_related_topics	Find topics related to a given topic
get_topic_summary	Get summary statistics for a topic

Pattern tools

Tool	Description
detect_patterns	Detect behavioral patterns from memories
compile_patterns	Compile detected patterns
get_patterns	List detected patterns
update_pattern	Update pattern metadata

Advanced tools

Tool	Description
graphrag_query	Graph-based retrieval augmented generation
detect_memory_communities	Detect communities in the memory graph
analyze_patterns	Advanced pattern analysis

Tool parameters

create_memory

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

Parameter	Type	Required	Description
content	string	Yes	The memory content
memoryType	string	Yes	episodic, semantic, or procedural
topics	string[]	No	Tags for categorization
importance	number	No	0-1 significance score
context	string	No	Additional context

search_memories

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

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
limit	number	No	Max results (default: 20)
threshold	number	No	Minimum similarity score (default: 0.7)

graphrag_query

{
  "query": "What technical decisions were made this quarter?",
  "depth": 2,
  "limit": 10,
  "includeRelationships": true
}

Parameter	Type	Required	Description
query	string	Yes	Natural language query
depth	number	No	Graph traversal depth
limit	number	No	Max results
includeRelationships	boolean	No	Include graph relationships

Architecture

The MCP server is a stateless translation layer:

AI Agent (Claude, Cursor)
    │
    ▼ MCP Protocol
┌────────────────┐
│  MCP Server    │
│  (Port 3001)   │
│  Translates    │
│  MCP → REST    │
└───────┬────────┘
        │ HTTP
        ▼
┌────────────────┐
│  API Gateway   │
│  Auth + Rate   │
│  Limiting      │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│  Core API      │
└────────────────┘

The MCP server has no direct database access. All requests flow through the API Gateway, which handles authentication and rate limiting.

Environment variables

Variable	Description	Default
MEMNEXUS_API_KEY	Your MemNexus API key	Required
API_GATEWAY_URL	API Gateway URL	https://api.memnexus.ai
MCP_PORT	Server port	3001
LOG_LEVEL	Logging level	info

Troubleshooting

Agent doesn't see MemNexus tools

1. Check that the config file path is correct for your platform
2. Restart the AI platform after changing config
3. Verify the API key is valid: mx auth status

Tools fail with authentication error

1. Check that MEMNEXUS_API_KEY is set correctly in the MCP config
2. Verify the key format: cmk_live_<id>.<secret>
3. Test the key directly: curl -H "Authorization: Bearer $MEMNEXUS_API_KEY" https://api.memnexus.ai/health

Connection timeout

1. Check your internet connection
2. Verify the API is reachable: mx system health
3. Check if a firewall is blocking outbound connections on 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