OpenCode | Spectron

Installing Spectron in OpenCode gives the agent persistent memory across sessions, so it can recall previous decisions and project context without you repeating them.

For integration rules your agent should follow (auth, scope, endpoints, common mistakes), see Agent guide (AGENTS.md). OpenCode reads a project AGENTS.md automatically.

Configure

OpenCode reads configuration from opencode.json in your workspace root (or ~/.config/opencode/opencode.json for a global entry). Add Spectron as a remote MCP server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spectron": {
      "type": "remote",
      "url": "https://<your-context-host>/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:SPECTRON_API_KEY}",
        "X-Spectron-Context": "acme-prod"
      }
    }
  }
}

The {env:SPECTRON_API_KEY} syntax reads the key from the environment, keeping the secret out of the file:

export SPECTRON_API_KEY="<your-api-key>"

On SurrealDB Cloud, use your context host from Surrealist API keys (not a generic shared domain). Self-hosted: replace the URL with your Spectron server's base URL + /mcp.

Note

X-Spectron-Context is a client-side convenience for templating. Each API key is bound to one Context, so context_id is optional on every tool call; omit it to use the key's Context. An explicit value that does not match the key still returns 401.

Verify the installation

Start OpenCode and ask "What MCP tools do you have available?" It should report the Spectron tools. If they do not appear, check that opencode.json is valid JSON and that the URL and SPECTRON_API_KEY are correct.

Usage examples

Remember a decision as you code:

"Remember that we use conventional commits and squash-merge every pull request."

OpenCode calls memory_store with a suitable scope.

Recall context before a task:

"What's our commit and merge convention?"

OpenCode calls memory_recall before answering.

Scope per tool call

Narrow reads and writes with the per-tool scope argument (slash paths, for example ["org/acme/project/cli"]). Register paths with spectron scopes create before first use. For project isolation, use separate contexts or distinct scope paths.

Removing Spectron

Delete the "spectron" entry from the mcp object in opencode.json, or set "enabled": false to disable it without removing the configuration.