Ditto MCP Server

Ditto exposes a Model Context Protocol (MCP) server for tools that can use outside context. Connect it once, and Claude, Codex, Cursor, Antigravity, or another MCP client can search your Ditto memories and subjects from the place where you are already working.

Using OpenClaw or Hermes Agent? Those integrations use the Ditto CLI, not MCP. Start with Agent Integrations, OpenClaw, or Hermes Agent.

Endpoint

https://api.heyditto.ai/mcp

This is a Streamable HTTP endpoint that implements the full MCP specification. Clients no longer need to specify "transport": "sse" in their configuration.

Legacy fallback: The previous SSE endpoints (/mcp/sse and /mcp/message) still work for older clients that haven’t migrated yet.

Pick Your Tool

Start with the tool you use most. The setup values stay the same; the auth flow and config shape change by client.

[mcp_servers.ditto]
url = "https://api.heyditto.ai/mcp"
bearer_token_env_var = "DITTO_MCP_API_KEY"

export DITTO_MCP_API_KEY="YOUR_API_KEY"
codex mcp add --url https://api.heyditto.ai/mcp \
  --bearer-token-env-var DITTO_MCP_API_KEY ditto
codex mcp list

claude mcp add --transport http ditto https://api.heyditto.ai/mcp

claude mcp add --transport http ditto https://api.heyditto.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "ditto": {
      "url": "https://api.heyditto.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "ditto": {
      "url": "https://api.heyditto.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "ditto": {
      "url": "https://api.heyditto.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "ditto": {
      "serverUrl": "https://api.heyditto.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Authentication

Two methods are available:

OAuth

Use OAuth when your client supports remote MCP authentication. It is the cleanest option for Claude.ai, Claude Desktop, Claude Code, and some Cursor setups.

OAuth avoids storing a Ditto API key in a local config file. The client opens a browser sign-in flow, then stores and refreshes its token.

API Key

Use an API key when your client does not support OAuth yet, when you are using a local JSON/TOML config, or when you need a deterministic setup for a specific machine.

1. Open heyditto.ai → Settings → MCP API Keys
2. Click “Create Key” and give it a name
3. Copy the key immediately, it won’t be shown again

Use the key in an Authorization: Bearer <key> header.

Available Tools

Ditto’s MCP server exposes six tools:

search_memories

Search your memories using semantic similarity with composite retrieval (similarity, recency, and frequency signals).

fetch_memories

Fetch the full content of specific memories by their IDs. Use this after search_memories to get complete conversation text.

search_subjects

Search your knowledge graph subjects by semantic similarity.

search_memories_in_subjects

Get memory summaries linked to specific subjects in your knowledge graph.

get_memory_network

Get a memory and its network of related memories via shared subjects.

save_memory

Save an external memory to your knowledge graph. Useful for importing notes, documents, or context from other tools.

Resources

Three read-only resources provide context about your account:

API Key Best Practices

• Create separate keys per tool: easier to revoke if one is compromised
• Never commit keys to git: use environment variables or secrets managers
• Check “Last Used” timestamps: revoke unused keys in Settings → MCP API Keys
• Use OAuth when available: no credentials in config files, automatic token rotation

Troubleshooting

”Not Authenticated” Error

• Verify the key is correct with no extra spaces
• Check the header format: Authorization: Bearer YOUR_API_KEY
• Confirm the key hasn’t been revoked in Settings → MCP API Keys
• Restart the AI tool after adding configuration

Empty Search Results

• Make sure you have conversations in Ditto (the memories come from your chats)
• Try broader search terms
• Lower the minSimilarity threshold for wider results
• Check that the AI tool is actually invoking the MCP tools

OAuth Flow Fails

• Log into Ditto first in your browser
• Check that pop-ups aren’t blocked
• Try in an incognito window
• Clear browser cache and retry