MCP Integration

Use Configure Memory as an MCP (Model Context Protocol) server with Claude Desktop, Cursor, and other MCP-compatible clients.

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external tools and data. Configure Memory exposes its capabilities as MCP tools, allowing any MCP-compatible AI to:

Read and write user memories
Search Gmail, Calendar, Drive, Notion
Access user context automatically

Quick Setup

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "memory": {
      "url": "https://api.configure.dev/mcp",
      "headers": {
        "X-App-Key": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop. You'll see Memory tools available in the tools menu.

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

json

{
  "mcpServers": {
    "memory": {
      "url": "https://api.configure.dev/mcp",
      "headers": {
        "X-App-Key": "your-api-key"
      }
    }
  }
}

MCP Handshake Flow

Configure Memory uses a handshake to learn about your agent:

Step 1: Initial Handshake

When your agent first connects, call memory_handshake:

json

{
  "name": "memory_handshake",
  "arguments": {}
}

Memory responds with questions:

json

{
  "status": "questions",
  "message": "Welcome. Please provide the requested information.",
  "questions": [
    { "id": "name", "question": "What's your name?" },
    { "id": "description", "question": "What do you help users with?" },
    { "id": "memory_focus", "question": "What user information is valuable for you?" },
    { "id": "memory_triggers", "question": "When should I save a memory?" }
  ]
}

Step 2: Complete Handshake

Answer the questions:

json

{
  "name": "memory_handshake_complete",
  "arguments": {
    "answers": {
      "name": "TravelBot",
      "description": "I help users plan trips, book flights, and manage travel",
      "memory_focus": "travel preferences, destinations, loyalty programs, budget",
      "memory_triggers": "user shares preferences, trip details, or likes/dislikes"
    }
  }
}

Memory now knows to:

Filter Gmail/Calendar data to travel-related items
Save memories about travel preferences
Ignore irrelevant data

Step 3: Process Messages

For each user message, call memory_process:

json

{
  "name": "memory_process",
  "arguments": {
    "user_id": "usr_abc123",
    "message": "I'm planning a trip to Tokyo",
    "conversation_history": [...]
  }
}

Response includes context to inject:

json

{
  "context": "User's name: Sarah\n\nFrom Gmail:\n• Flight to Barcelona Dec 15\n\nMemories:\n• preferred_airline: Delta",
  "context_injected": true,
  "tools_accessed": ["gmail"],
  "connected_tools": ["gmail", "calendar"]
}

Available MCP Tools

Context Tools

Tool	Description
`memory_handshake`	Start agent registration
`memory_handshake_complete`	Complete registration with answers
`memory_process`	Process user message, get context
`memory_get_context`	Directly fetch user profile
`memory_write_context`	Directly write to user profile
`memory_get_status`	Get connected tools status

Search Tools

Tool	Description
`memory_search_emails`	Search user's Gmail
`memory_get_calendar`	Get calendar events
`memory_search_files`	Search Google Drive
`memory_search_notes`	Search Notion

Action Tools

Tool	Description
`memory_create_calendar_event`	Create calendar event
`memory_send_email`	Send email via Gmail
`memory_sync_tool`	Refresh tool data

UI Tools

Tool	Description
`show_ui_component`	Display UI in supporting clients

Tool Schemas

memory_search_emails

json

{
  "name": "memory_search_emails",
  "arguments": {
    "user_id": "uuid",
    "query": "flight confirmation",
    "max_results": 10
  }
}

memory_get_calendar

json

{
  "name": "memory_get_calendar",
  "arguments": {
    "user_id": "uuid",
    "range": "week"
  }
}

Range options: "today" | "tomorrow" | "week" | "month"

memory_write_context

json

{
  "name": "memory_write_context",
  "arguments": {
    "user_id": "uuid",
    "data": {
      "seat_preference": "aisle",
      "home_airport": "SFO"
    }
  }
}

memory_create_calendar_event

json

{
  "name": "memory_create_calendar_event",
  "arguments": {
    "user_id": "uuid",
    "title": "Team Meeting",
    "start_time": "2025-01-20T14:00:00",
    "end_time": "2025-01-20T15:00:00",
    "description": "Weekly sync",
    "location": "Zoom"
  }
}

Integration Examples

Python with MCP Client

python

from anthropic import Anthropic
from mcp_client import MCPClient

client = Anthropic()
memory = MCPClient("memory")

# Step 1: Handshake (once per session)
handshake = memory.call("memory_handshake", {})
memory.call("memory_handshake_complete", {
    "answers": {
        "name": "Assistant",
        "description": "General purpose helper",
        "memory_focus": "preferences, schedules, projects",
        "memory_triggers": "user shares preferences or important info"
    }
})

# Step 2: Process messages
async def chat(user_id: str, message: str, history: list):
    # Get context from Memory
    mem = memory.call("memory_process", {
        "user_id": user_id,
        "message": message,
        "conversation_history": history
    })
    
    # Build prompt with context
    system = "You are a helpful assistant."
    if mem["context"]:
        system += f"\n\nUSER CONTEXT:\n{mem['context']}"
    
    # Generate response
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        system=system,
        messages=[*history, {"role": "user", "content": message}]
    )
    
    return response.content[0].text

TypeScript with MCP

typescript

import { MCPClient } from '@anthropic/mcp-client';

const memory = new MCPClient({
  serverUrl: 'https://api.configure.dev/mcp',
  headers: { 'X-App-Key': process.env.CONFIGURE_API_KEY }
});

// Handshake
await memory.call('memory_handshake', {});
await memory.call('memory_handshake_complete', {
  answers: {
    name: 'MyBot',
    description: 'Task management assistant',
    memory_focus: 'tasks, deadlines, preferences',
    memory_triggers: 'user creates tasks or shares preferences'
  }
});

// Process user message
async function chat(userId: string, message: string) {
  const mem = await memory.call('memory_process', {
    user_id: userId,
    message: message
  });
  
  // Use mem.context in your prompt
  console.log('Context:', mem.context);
  console.log('Tools accessed:', mem.tools_accessed);
  
  return mem;
}

Best Practices

1. Complete the Handshake

The handshake teaches Memory what data matters to your agent:

javascript

// Good: Specific description
"description": "I help users plan trips and book travel"

// Bad: Too generic
"description": "I'm an AI assistant"

2. Use memory_process for Everything

Let Memory decide when to inject context:

javascript

// Good: Use memory_process
const result = await memory.call("memory_process", { user_id, message });
// Memory decides if context is needed

// Bad: Always fetching everything
const profile = await memory.call("memory_get_context", { user_id });
// Wasteful for simple messages

3. Pass Assistant Responses Back

Enable automatic memory extraction:

javascript

// After generating response, let Memory detect memories
await memory.call("memory_process", {
  user_id: userId,
  message: userMessage,
  assistant_response: aiResponse // Memory extracts memories from this
});

4. Trust the Context Filter

Memory filters data based on your handshake. A TravelBot sees:

Flight bookings
Hotel confirmations
Travel preferences

A FinanceBot sees:

Bank statements
Receipts
Budget info

Troubleshooting

"No context returned"

Check if user has connected tools
Verify handshake was completed
Check if query is relevant to your agent's focus

"Tool not connected"

Guide user to connect the tool via your app
Use memory_get_status to check connection state
Show connection UI when needed

"Rate limited"

Memory limits requests per minute
Cache context when possible
Don't call for every keystroke

Security

MCP connections use HTTPS
Your API key authenticates your agent
User tokens authenticate specific users
Memories are namespaced per agent
Users can revoke access anytime

MCP Integration ​

What is MCP? ​

Quick Setup ​

Claude Desktop ​

Cursor ​

MCP Handshake Flow ​

Step 1: Initial Handshake ​

Step 2: Complete Handshake ​

Step 3: Process Messages ​

Available MCP Tools ​

Context Tools ​

Search Tools ​

Action Tools ​

UI Tools ​

Tool Schemas ​

memory_search_emails ​

memory_get_calendar ​

memory_write_context ​

memory_create_calendar_event ​

Integration Examples ​

Python with MCP Client ​

TypeScript with MCP ​

Best Practices ​

1. Complete the Handshake ​

2. Use memory_process for Everything ​

3. Pass Assistant Responses Back ​

4. Trust the Context Filter ​

Troubleshooting ​

"No context returned" ​

"Tool not connected" ​

"Rate limited" ​

Security ​

MCP Integration

What is MCP?

Quick Setup

Claude Desktop

Cursor

MCP Handshake Flow

Step 1: Initial Handshake

Step 2: Complete Handshake

Step 3: Process Messages

Available MCP Tools

Context Tools

Search Tools

Action Tools

UI Tools

Tool Schemas

memory_search_emails

memory_get_calendar

memory_write_context

memory_create_calendar_event

Integration Examples

Python with MCP Client

TypeScript with MCP

Best Practices

1. Complete the Handshake

2. Use memory_process for Everything

3. Pass Assistant Responses Back

4. Trust the Context Filter

Troubleshooting

"No context returned"

"Tool not connected"

"Rate limited"

Security