# Copilot sees your workspace. Maguyva maps the repo.

Canonical source: https://maguyva.ai/for-vscode

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

The agent in VS Code reads the files you attach and the ones it searches for. Maguyva indexes the whole repo and serves it over MCP, so the agent asks where a symbol lives and who calls it before it edits.

> One servers entry in .vscode/mcp.json: a URL and an Authorization header.

## What VS Code needs to know

Four facts specific to VS Code.

### .vscode/mcp.json

Servers go under `servers`, not `mcpServers`. For every workspace, run `MCP: Open User Configuration` and add the same entry to your profile’s `mcp.json`.

### type: http

VS Code connects to Maguyva’s endpoint over Streamable HTTP and falls back to SSE only when a server lacks it. Nothing runs locally.

### An env reference

The header reads `Bearer ${env:MAGUYVA_API_KEY}`, which VS Code resolves from the environment it was started in, so the key stays out of the file you commit. Prefer a prompt? An input variable asks once and stores the key.

### Workspace Trust

Servers in `.vscode/mcp.json` start without a separate prompt once you trust the workspace, and never start in Restricted Mode. Configure Tools in the chat input turns single tools on or off.

## Custom instructions are a working agreement. Use them.

```text
# .github/copilot-instructions.md
- Run npm test before you call a change done.
- Never edit generated files under src/gen/.
```

VS Code reads project-wide instructions from `.github/copilot-instructions.md` or `AGENTS.md`, and targeted ones from `.github/instructions/*.instructions.md` files with an `applyTo` pattern. Use them for:

- Build, test, and lint commands.
- Conventions the agent keeps getting wrong.
- Folders the agent should leave alone.

Instructions tell the agent how to work. They cannot tell it which of four thousand files import the type it is about to rename.

## Where the workspace view runs out

Three things the agent cannot learn from the files it has open.

### // attached isn’t everything

The agent works from what you attach and what its searches return. The caller in another package that breaks after the change was never in either list.

### // a text match isn’t a reference

Workspace search finds the string. It cannot tell a real call from a comment, a mock, or a method with the same name on another class.

### // every read costs context

Each file the agent opens to orient itself spends context it needs for the change. One ranked answer with file:line costs less than ten exploratory reads.

## Maguyva as an MCP server in VS Code

One servers entry gives the agent:

- **11 tools over your indexed repo**: semantic, structural (AST), graph, and text search, plus symbol lookup, dependents, and file retrieval.
- **Answers with file paths and line numbers**: across 285+ languages, so the agent opens the right file first.
- **Tools that only read**: Maguyva’s tools query the index. None of them edit your files, so each approval is about reading, not writing.

> VS Code gives the agent *your workspace*.
> Maguyva gives the agent *a map of the repo*.

## Two workflows

Ask the map first, then edit.

### 01. Find the tests before changing a parser

```text
vscode agent> which tests exercise parseConfig?

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ The agent runs both files after the edit, not the whole suite.
[exit 0]
```

The answer names the two test files that reach the parser, so the agent checks the change where it can break.

### 02. Size a rename before the first edit

```text
vscode agent> rename OrderStatus.PENDING to OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  23 references across 9 files

→ The agent plans one pass over nine files.
[exit 0]
```

The reference count arrives before the edit, not after the type checker fails.

## Setup in VS Code

Three steps. Free tier: 3 repos, 50K indexed lines, no card.

### 01. Index a repo at maguyva.ai

Pick one you already know, so you can grade the answers.

### 02. Add Maguyva to .vscode/mcp.json

`.vscode/mcp.json`

```json
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Set your key and start the server

Set `MAGUYVA_API_KEY` in the environment you start VS Code from, then start the server from the code lens above its entry. Ask the agent one question whose answer you already know.

VS Code’s [MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers) cover input variables, the portable .mcp.json format, and server trust.

## Index one repo you already know.

Connect VS Code over MCP, then ask one question you can check.