# VS Code

Installing SurrealDB Agent Memory as an MCP server in VS Code.

VS Code supports MCP servers through the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension (version 1.99 or later with agent mode enabled) and through compatible AI extensions that implement the MCP client protocol.

## Prerequisites

- VS Code 1.99 or later
- GitHub Copilot extension with agent mode enabled, **or** another MCP-compatible VS Code extension

To enable Copilot agent mode: open VS Code settings, search for `github.copilot.chat.agent.enabled`, and set it to `true`.

## Install

The MCP server lives at `/mcp` on your SurrealDB Agent Memory instance. On **SurrealDB Cloud** the base is your context host from SurrealDB Studio **API keys**; self-hosted, it is your server's base URL. Point VS Code at it with [`install-mcp`](https://github.com/supermemoryai/install-mcp):

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

The URL is the first argument; auth is passed with `--header`, and `--oauth no` skips the OAuth prompt (SurrealDB Agent Memory uses a static Bearer key). The installer writes the configuration to `.vscode/mcp.json` in your current working directory, which makes the MCP server available to everyone who opens the workspace - suitable for shared team projects.

To make the server available in every workspace instead, add the same entry to your global VS Code config by hand (see the paths below).

### Config file locations

| Scope | Path |
|---|---|
| Workspace | `.vscode/mcp.json` (relative to your project root) |
| Global (macOS) | `~/Library/Application Support/Code/User/mcp.json` |
| Global (Windows) | `%APPDATA%\Code\User\mcp.json` |
| Global (Linux) | `~/.config/Code/User/mcp.json` |

### What gets written

**`.vscode/mcp.json` (workspace):**

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

VS Code uses the `servers` key (rather than `mcpServers`) and requires a `type` field. The `install-mcp` command handles this difference automatically.

### Committing the config

The `.vscode/mcp.json` file can be committed to your repository so the team shares the same MCP server configuration. The API key should **not** be committed directly. Instead, use a VS Code input variable to prompt for the key at runtime:

```json
{
  "inputs": [
    {
      "id": "spectronApiKey",
      "type": "promptString",
      "description": "Spectron API key",
      "password": true
    }
  ],
  "servers": {
    "spectron": {
      "type": "http",
      "url": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:spectronApiKey}",
        "X-Spectron-Context": "acme-prod"
      }
    }
  }
}
```

VS Code will prompt each developer for their API key the first time they use the MCP server in the workspace.

## Verify the installation

1. Open VS Code and the workspace
2. Open the Copilot chat panel (`Ctrl+Shift+I` or `Cmd+Shift+I`)
3. Switch to **Agent** mode using the mode selector in the chat panel
4. Type `@spectron` or ask: "What MCP servers are available?"
5. Copilot should acknowledge the SurrealDB Agent Memory tools

Alternatively, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **MCP: List Servers** to see the status of all configured MCP servers including SurrealDB Agent Memory.

## Usage examples

### Remembering project decisions in agent mode

In Copilot agent mode:

> "Remember that we use Prisma for all database access in this project and that direct SQL queries are not permitted outside of migration scripts."

Copilot calls `remember`. The decision persists across VS Code sessions and is recalled the next time you ask a database-related question.

### Recalling context before refactoring

Before asking Copilot to refactor a module:

> "What do you know about the design decisions behind the authentication module?"

Copilot calls `recall`, retrieves the relevant context, and incorporates it into its refactoring suggestions.

### Searching project documentation

If your team's documentation is synced into SurrealDB Agent Memory's knowledge base:

> "What does our architecture decision record say about the API gateway pattern?"

Copilot calls `recall` and returns the relevant ADR content.

## Scope per workspace

Keep memory isolated per repository by passing a **`scope`** argument on each tool call (for example `["org/acme/project/platform-v3"]`), or by using separate SurrealDB Agent Memory contexts. The install helper does not set default scope headers.

## Removing SurrealDB Agent Memory

Delete the `"spectron"` entry from `.vscode/mcp.json` (workspace) or from the global `mcp.json` file. VS Code will stop offering the SurrealDB Agent Memory tools in subsequent sessions.