ekkOS_docs
Integration Guide

MCP Integration

Connect ekkOS to Claude Code, Cursor, and other MCP-compatible AI tools. Get persistent memory across all your development workflows.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. Think of it as a plugin system for AI.

ekkOS provides an MCP server that gives your AI tools access to persistent memory. When you connect Claude Code or Cursor to ekkOS via MCP, they gain the ability to:

  • Remember context across sessions
  • Learn from successful problem-solving
  • Apply proven patterns automatically
  • Validate suggestions against your history

Claude Code Setup

Step 1: Locate your settings file

Claude Code stores its configuration in ~/.claude/settings.json

# macOS/Linux ~/.claude/settings.json # Windows %USERPROFILE%\.claude\settings.json

Step 2: Add ekkOS MCP server

Add the following to your settings.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "ekkos-memory": {
      "command": "npx",
      "args": ["-y", "@ekkos/mcp-server"],
      "env": {
        "EKKOS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Step 3: Restart Claude Code

Close your terminal and reopen it. Claude Code will automatically load the MCP server on next launch.

Verify Installation

Ask Claude: "Search my memory for recent patterns"— if it uses the ekko tool, you're connected!

Cursor Setup

Step 1: Create MCP configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ekkos-memory": {
      "command": "npx",
      "args": ["-y", "@ekkos/mcp-server"],
      "env": {
        "EKKOS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Step 2: Enable MCP in Cursor Settings

  1. 1Open Cursor Settings (Cmd/Ctrl + ,)
  2. 2Search for "MCP"
  3. 3Enable "Use MCP Servers"

Step 3: Reload Window

Press Cmd/Ctrl + Shift + P and run "Reload Window"

Alternative: Global Installation

For faster startup, you can install the MCP server globally:

npm install -g @ekkos/mcp-server

Then update your config to use the global command:

{
  "mcpServers": {
    "ekkos-memory": {
      "command": "ekkos-mcp",
      "env": {
        "EKKOS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available MCP Tools

Once connected, your AI has access to these memory tools:

ekko

Search your memory substrate for patterns, solutions, and context

Signature
ekko(query: string, limit?: number)
Example prompt

"Search for authentication patterns"

Returns

Array of matching memories with relevance scores

crystallize

Save important decisions and patterns permanently

Signature
crystallize(title: string, problem: string, solution: string, tags?: string[])
Example prompt

"Remember: Always use Supabase for auth"

Returns

Confirmation with pattern ID

reflex

Validate AI suggestions against your established patterns (Hallucination Firewall)

Signature
reflex(request: string, proposed_answer: string)
Example prompt

"Check if this approach aligns with our history"

Returns

GROUNDED, SPECULATIVE, or CONFLICT with explanation

forge_insight

Create new patterns from learnings with success metrics

Signature
forge_insight(title: string, problem: string, solution: string, works_when?: string[])
Example prompt

"Create pattern: RLS requires service role for admin ops"

Returns

Pattern ID and confirmation

trace

Explain why a suggestion was made - show provenance

Signature
trace(retrieval_id: string, memory_ids?: string[])
Example prompt

"Show me which memories influenced this suggestion"

Returns

Detailed provenance with relevance scores

get_directives

Get current MUST/NEVER/PREFER/AVOID behavioral rules

Signature
get_directives(userId?: string, windowHours?: number)
Example prompt

"What are the current rules I should follow?"

Returns

Active directives with priorities

Best Practices

Do

  • • Ask AI to "search memory" for relevant context
  • • Crystallize important decisions and patterns
  • • Use reflex to validate unfamiliar suggestions
  • • Let the AI forge insights from successful solutions
  • • Keep API keys in environment variables

Don't

  • • Store API keys in plain text configs
  • • Expect memory without asking for it
  • • Ignore the reflex tool for risky changes
  • • Forget to restart after config changes
  • • Run multiple MCP servers on same port

Troubleshooting

MCP server not starting?

1. Verify Node.js 18+ is installed: node --version

2. Check npx is available: npx --version

3. Try running manually: EKKOS_API_KEY=xxx npx @ekkos/mcp-server

4. Check for error messages in the terminal output

AI not using memory tools?

1. Explicitly ask: "Search my memory for..." or "Use ekkOS to..."

2. Verify the MCP server is listed in your tool's connected servers

3. Check your API key is valid at platform.ekkos.dev

4. Restart your AI tool completely (not just reload)

Getting rate limited?

Free tier includes 100 requests/day. Upgrade at platform.ekkos.dev/pricing

Pro tier: 10,000 requests/day

Team tier: Unlimited requests

Next Steps

MCP Tools Reference

Complete documentation for all MCP tools

View reference

The Golden Loop

Learn how memory improves over time

Learn more