Installing the MCP server

SurrealDB Agent Memory serves MCP (Streamable HTTP) at /mcp on the same host and port as the REST API. Point any MCP client at that endpoint:

• •

  SurrealDB Cloud - your context host from SurrealDB Studio API keys with /mcp appended, for example https://abc123.spectron.cloud/mcp.

• •

  Self-hosted - your server's base URL plus /mcp, for example http://localhost:9090/mcp.

Authentication uses Authorization: Bearer, the same as REST. Each key is bound to one Context, so context_id is optional on every tool call. The tools map to the unified substrate: remember, recall, context, reflect, forget, upload, inspect.

Quick install

install-mcp writes the correct config for most clients. Pass the /mcp URL as the first argument, your key with --header, and --oauth no to skip the OAuth prompt (SurrealDB Agent Memory uses a static Bearer key, not OAuth):

npx install-mcp https://<your-context-host>/mcp \
  --client cursor \
  --header "Authorization: Bearer <your-api-key>" \
  --oauth no

Use this for cursor, vscode, windsurf, zed, and opencode. Claude (Code, Cowork, Desktop) and Codex have a dedicated SurrealDB plugin - see the Claude and Codex guides. JetBrains and Antigravity use the manual configuration below.

Manual configuration

Any MCP client can be configured by hand:

{
  "mcpServers": {
    "spectron": {
      "url": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Some clients use a different key or shape - serverUrl in Windsurf and Antigravity, a servers object with a type field in VS Code. The per-client guides show each one.

Per-client guides

• •

  Claude Desktop and Claude Code

• •

  Cursor

• •

  VS Code

• •

  Windsurf

MCP vs SDK

Tool schemas: MCP tools reference.