# JetBrains Air

Installing SurrealDB Agent Memory as an MCP server in JetBrains Air.

[JetBrains Air](https://www.jetbrains.com/air/) is a standalone agentic development environment that runs Claude Agent, OpenAI Codex, Gemini CLI, Junie, or any ACP-compatible agent installed on your machine. Installing SurrealDB Agent Memory gives the agent you select 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)](/docs/agent-memory/reference/agents.md)**. Air picks up instruction files that already exist in your project, including `CLAUDE.md` and the `.claude` folder for Claude Agent, and passes them to the selected agent.

> [!NOTE]
> This page covers JetBrains Air. For AI Assistant inside IntelliJ IDEA, PyCharm, WebStorm and the other IDEs, see the [JetBrains](/docs/agent-memory/integrations/mcp-server/coding-assistants/jetbrains.md) guide.

## Configure

The `install-mcp` helper does not cover JetBrains Air, so configure the server by hand.

1. Open **Settings** and go to **AI | MCP Servers**
2. Turn on **Enable MCP support**
3. Click **Add Global MCP Server**, or use the drop-down to choose **Add Local MCP Server** or **Add Workspace MCP Server**
4. Paste the configuration below and save it

```json
{
  "mcpServers": {
    "spectron": {
      "url": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>",
        "X-Spectron-Context": "acme-prod"
      }
    }
  }
}
```

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

Air connects on save, because SurrealDB Agent Memory authenticates with a static Bearer key rather than OAuth.

### Choosing a scope

The three **Add** options write the same JSON to different places:

| Scope | Where it lives | Use it for |
| --- | --- | --- |
| Global | Air's own settings on your machine | A personal key you want in every project |
| Local | `.air/mcp.json` in the project root | Project-specific configuration, stored with Air's other project settings |
| Workspace | `.mcp.json` in the project root | A repository that already carries MCP configuration |

Workspace servers start only when **Launch workspace MCP servers** is also enabled on the same settings page.

> [!WARNING]
> Air reads the bearer token from the configuration file itself, and tokens passed through environment variables are not supported. Both `.air/mcp.json` and `.mcp.json` sit in the project root, so add the file to `.gitignore` before you paste a key, or use the **Global** scope to keep the key out of the repository.

> [!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

1. Reopen **Settings → AI | MCP Servers** and confirm **spectron** is in the **Added** list with a green status indicator and a tool count
2. Start a task and ask "What MCP tools do you have available?" The agent should report the SurrealDB Agent Memory tools

If the indicator is not green, check that the URL (your context host + `/mcp`) and API key are correct.

## Usage examples

**Store a project decision:**

> "Remember that this service uses hexagonal architecture and all adapters live under `internal/adapters`."

The agent calls `remember` with a suitable `scope`.

**Recall context before a change:**

> "What did we decide about where adapters live in this project?"

The agent calls `recall` before answering.

Air's permission mode, cycled with `Shift+Tab`, applies to the task as a whole rather than to individual tool calls. In **Ask** mode the agent requests approval before it changes files or runs commands.

## Scope per tool call

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

## Removing SurrealDB Agent Memory

Open **Settings → AI | MCP Servers**, select the **spectron** entry, and remove it. For the Local and Workspace scopes you can instead delete the `"spectron"` key from `.air/mcp.json` or `.mcp.json`.