MemOS MCP Integration Guide

This guide helps you configure MemOS MCP service in platforms like Coze Space, enabling seamless integration between your agent and the memory system.

Choose an MCP Deployment Method

MemOS provides two MCP deployment options. Choose based on your needs:

Use MemOS Cloud Service (Recommended)

If you want to connect quickly without deploying your own server, MemOS official cloud service is recommended.

Advantages:

• ✅ Out of the box, no deployment required
• ✅ High availability guarantees
• ✅ Automatic scaling and maintenance
• ✅ Supports multiple clients (Claude, Cursor, Cline, etc.)

How to configure:

Visit MemOS Cloud MCP Configuration Guide for detailed instructions.

Main steps:

1. Register and get an API Key in MemOS API Console
2. Configure @memtensor/memos-api-mcp service in your MCP client
3. Set environment variables (MEMOS_API_KEY, MEMOS_USER_ID, MEMOS_CHANNEL)

Deploy MCP Service Yourself

If you need a private deployment or custom requirements, you can deploy MCP service on your own server.

Advantages:

• ✅ Fully private data
• ✅ Configurable and customizable
• ✅ Full control of the service
• ✅ Suitable for internal enterprise use

Prerequisites:

• Python 3.9+
• Neo4j database (or another supported graph database)
• HTTPS domain (required by platforms like Coze)

Continue reading for detailed deployment steps.

Self-Hosted MCP Service Configuration

The content below applies to users who deploy MCP service themselves.

Architecture

Self-hosted MCP service uses the following architecture:

Client (Coze/Claude, etc.)
    ↓ [HTTPS]
MCP Server (port 8002)
    ↓ [HTTP calls]
Server API (port 8001)
    ↓
MemOS Core Service

Component overview:

• Server API: provides REST APIs (/product/*) to handle memory CRUD
• MCP Server: exposes the MCP protocol over HTTP and calls Server API to complete operations
• HTTPS reverse proxy: platforms like Coze require HTTPS secure connections

cd /path/to/MemOS
python src/memos/api/server_api.py --port 8001

curl http://localhost:8001/docs

cd /path/to/MemOS
python examples/mem_mcp/simple_fastmcp_serve.py --transport http --port 8002

╭──────────────────────────────────────────────────╮
│       MemOS MCP via Server API                   │
│       Transport:   HTTP                          │
│       Server URL:  http://localhost:8002/mcp     │
╰──────────────────────────────────────────────────╯

export MEMOS_API_BASE_URL="http://localhost:8001/product"

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /mcp {
        proxy_pass http://localhost:8002/mcp;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE support
        proxy_buffering off;
        proxy_cache off;
    }
}

cd /path/to/MemOS
python examples/mem_mcp/simple_fastmcp_client.py

Working FastMCP Client
========================================
Connected to MCP server

  1. Adding memory...
    Result: Memory added successfully
  
  2. Searching memories...
    Result: [search result]
  
  3. Chatting...
    Result: [AI response]

✓ All tests completed!

Configure MCP in Coze Space

After the service is deployed, configure the MCP connection in Coze Space.

https://your-domain.com/mcp

Use REST API Directly (Advanced)

For scenarios that require more flexible integration, you can call Server API’s REST endpoints directly.

cd /path/to/MemOS
python src/memos/api/server_api.py --port 8001

import json
import requests
from runtime import Args
from typings.add_memory.add_memory import Input, Output

def handler(args: Args[Input])->Output:
    memory_content = args.input.memory_content
    user_id = args.input.user_id
    cube_id = args.input.cube_id
    
    # Call Server API add endpoint
    url = "https://your-domain.com:8001/product/add"
    payload = json.dumps({
        "user_id": user_id,
        "messages": memory_content,  # Supports string or message array
        "writable_cube_ids": [cube_id] if cube_id else None
    })
    headers = {
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, headers=headers, data=payload, timeout=30)
    response.raise_for_status()
    
    return response.json()

# Search tool
def search_handler(args: Args[Input]) -> Output:
    url = "https://your-domain.com:8001/product/search"
    payload = json.dumps{
        "user_id": args.input.user_id,
        "query": args.input.query,
    })
    headers = {
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, headers=headers, data=payload, timeout=30)
    response.raise_for_status()
    
    return response.json()

# Chat tool
def chat_handler(args: Args[Input]) -> Output:
    url = "https://your-domain.com:8001/product/chat/complete"
    payload = json.dumps({
        "user_id": args.input.user_id,
        "query": args.input.query
    })
    response = requests.post(url, json=payload, timeout=30)
    return response.json()

FAQ

Q1: MCP service cannot connect to Server API

Solution:

• Check whether Server API is running: curl http://localhost:8001/docs
• Check whether environment variable MEMOS_API_BASE_URL is configured correctly
• Check MCP service logs and confirm the call address

Q2: Coze cannot connect to MCP service

Solution:

• Make sure you use HTTPS
• Check whether the SSL certificate is valid
• Test reverse proxy configuration: curl https://your-domain.com/mcp
• Check firewall and security group settings

Q3: Neo4j connection failed

Solution:

• Ensure Neo4j service is running
• Check connection info in the configuration file (uri, user, password)
• Refer to examples/data/config/tree_config_shared_database.json as an example configuration

Q4: How to see complete API examples?

Reference files:

• MCP server: examples/mem_mcp/simple_fastmcp_serve.py
• MCP client: examples/mem_mcp/simple_fastmcp_client.py
• API tests: examples/api/server_router_api.py

Summary

With this guide, you can:

• ✅ Choose a suitable MCP deployment option (cloud or self-hosted)
• ✅ Complete the full MCP service deployment process
• ✅ Integrate MemOS memory features into platforms like Coze
• ✅ Integrate directly via REST API

No matter which option you choose, MemOS can provide your agent with powerful memory managementders=headers, data=payload) return json.loads(response.text)

Publish and Use the Plugin

After publishing, you can view the plugin under "My Resources" and integrate it into the agent workflow as a plugin:

Build an Agent and Test

After building the simplest agent, you can test memory operations:

1. Create a new agent
2. Add the published memory plugin
3. Configure the workflow
4. Test memory write and retrieval functions

With the above configuration, you can successfully integrate MemOS memory features in Coze Space and provide powerful memory capabilities for your agent.