Claude

The official SurrealDB plugin marketplace for Claude ships a spectron plugin that connects Claude to your Spectron instance's /mcp endpoint and installs a usage skill. It supports Claude Code, Cowork, and Claude Desktop. There is no default URL — point it at your own instance (SurrealDB Cloud: your context host from Surrealist API keys; self-hosted: your server's base URL).

Claude Code and Cowork

Install the plugin

Add the marketplace, then install the spectron plugin:

/plugin marketplace add surrealdb/ai-claude-plugin
/plugin install spectron@surrealdb

Claude Code reads the plugin directly — the MCP server and the usage skill load automatically.

Configure

The Spectron MCP has no default URL. Set your instance endpoint and a bearer token before launching Claude Code, then restart:

export SPECTRON_MCP_URL="https://<your-spectron-instance>/mcp"
export SPECTRON_MCP_TOKEN="<your-api-key>"

If SPECTRON_MCP_URL is unset, the server will not connect. The plugin's MCP entry expands these variables:

{
  "mcpServers": {
    "spectron": {
      "type": "http",
      "url": "${SPECTRON_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${SPECTRON_MCP_TOKEN}"
      }
    }
  }
}

The bearer token is your Spectron context API key. Each key is bound to one Context, so context_id is optional on every tool call.

Verify the installation

claude mcp list

You should see spectron connected. In a session, ask "What MCP tools do you have access to?" and Claude should list the Spectron tools: remember, recall, context, reflect, forget, upload, inspect.

Usage examples

Remember architectural decisions as you code:

claude "Remember that we have decided to use event sourcing for the orders service and that the aggregate root is OrderAggregate."

Claude Code calls remember. The next time you start a session in this project, recall surfaces this decision before Claude answers questions about the orders service.

Recall context before a coding task:

claude "What do you remember about our database schema decisions?"

Claude Desktop

Claude Desktop has no plugin/marketplace format, so set it up manually. Both options use your instance's /mcp URL and a bearer token; there is no default.

Option A — Connectors UI (recommended)

Open Settings → Connectors → Add custom connector and add:

Option B — Manual config

Merge the following into claude_desktop_config.json, then restart Claude Desktop:

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

You can validate the file with cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool.

Skill (optional)

Claude Desktop cannot load plugins, but you can add the Spectron usage skill by hand: open Settings → Skills → Upload skill and upload the plugins/spectron/skills/mcp/ folder from the plugin repo.

Verify the installation

1. 1.

   Restart Claude Desktop completely (quit and reopen)

2. 2.

   Start a new conversation

3. 3.

   Click the tools icon (the hammer symbol) in the composer — the seven Spectron tools should appear

4. 4.

   Ask "What MCP tools do you have?" and Claude should describe the Spectron tools

Scope on tool calls

Narrow reads and writes with the per-tool scope argument (slash paths, for example ["org/acme/user/alice"] or ["org/acme/project/orders-service"]). Register paths with spectron scopes create before first use. Use separate contexts or distinct scope paths to keep memory isolated per repository.

Removing Spectron

Claude Code / Cowork: remove the spectron plugin from the /plugin menu, or run claude mcp remove spectron.

Claude Desktop: remove the spectron connector, or delete the "spectron" key from claude_desktop_config.json, then restart Claude Desktop.