MCP Integration

XMDB includes a native MCP (Model Context Protocol) server that exposes memory tools to AI clients. This enables Claude, Cursor, ChatGPT, Gemini, and other MCP-compatible tools to read and write memory directly.

Overview

The MCP server supports two transport modes:

• stdio - Local mode for Claude Desktop, Cursor, and similar clients
• HTTP - Remote mode via https://mcp.xmdb.cloud/mcp

Available Tools

The MCP server exposes these tools:

| Tool | Description | |------|-------------| | write_memory | Store a memory item with provenance | | search_memory | Query memory with deterministic ordering | | get_memory_pack | Retrieve a context pack with attestation | | get_item_history | Fetch latest revision + history for an item | | xmdb.whoami | Return authenticated identity info | | xmdb.items_list | List items via /v1/items |

Aliases are also available: xmdb.capture, xmdb.search, xmdb.pack, xmdb.item_history.

Remote Mode (Recommended)

Connect to the hosted MCP endpoint without running a local server:

https://mcp.xmdb.cloud/mcp

All requests require an Authorization header with your MCP token.

Claude Desktop Configuration

Add XMDB to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "xmdb": {
      "command": "xmdb-mcp",
      "env": {
        "XMDB_BASE_URL": "https://api.xmdb.cloud",
        "XMDB_API_TOKEN": "your-token-here",
        "XMDB_WORKSPACE_ID": "your-workspace"
      }
    }
  }
}

For remote mode without a local binary, use the stdio-to-HTTP proxy from the examples.

Cursor Configuration

Configure XMDB in your Cursor MCP settings:

{
  "mcp": {
    "servers": {
      "xmdb": {
        "command": "xmdb-mcp",
        "env": {
          "XMDB_BASE_URL": "https://api.xmdb.cloud",
          "XMDB_API_TOKEN": "your-token-here",
          "XMDB_WORKSPACE_ID": "your-workspace"
        }
      }
    }
  }
}

ChatGPT & Gemini

Both ChatGPT and Gemini support MCP via their respective connectors. Configure the remote endpoint:

# Remote MCP endpoint
https://mcp.xmdb.cloud/mcp

# Headers
Authorization: Bearer your-mcp-token

Refer to each client's documentation for specific setup instructions.

Running Locally (stdio mode)

To run the MCP server locally:

# Set environment variables
export XMDB_BASE_URL="https://api.xmdb.cloud"
export XMDB_API_TOKEN="your-token"
export XMDB_WORKSPACE_ID="your-workspace"
export XMDB_SCOPE="your-scope"  # Optional if token has single scope

# Run the MCP server
xmdb-mcp

The server communicates via stdin/stdout using JSON-RPC.

Running Locally (HTTP mode)

Expose a local HTTP endpoint:

export XMDB_BASE_URL="https://api.xmdb.cloud"
export XMDB_API_TOKEN="your-token"
export MCP_AUTH_TOKEN="strong-local-token"

xmdb-mcp --transport=http --listen=127.0.0.1:7337 --endpoint=/mcp

• Requests require Authorization: Bearer strong-local-token
• Only POST requests are accepted at the endpoint
• CORS is controlled via MCP_ALLOWED_ORIGINS

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | XMDB_BASE_URL | Yes | API base URL | | XMDB_API_TOKEN | Yes | Authentication token | | XMDB_WORKSPACE_ID | No | Default workspace | | XMDB_SCOPE | No | Default scope (omit for single-scope tokens) | | MCP_AUTH_TOKEN | No | Token for HTTP mode authentication | | MCP_ALLOWED_ORIGINS | No | Comma-separated allowed CORS origins |

Next Steps

• CLI Reference - Full xmdbctl command reference
• Security - Token scopes and best practices