# Zed is fast. The agent still has to find the code.

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

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 Zed agent works from the files you open and the instructions you give it. Maguyva indexes the whole repo and serves it back over MCP, so the agent asks where a symbol lives instead of guessing.

> One context_servers entry: a URL and an Authorization header.

## What Zed needs to know

Four facts specific to Zed. None of them are hard.

### settings.json

Remote servers live under `context_servers`. Open the file with `zed: open settings file`, or add a server from Settings → AI → MCP Servers.

### Remote, by URL

Zed connects to Maguyva’s remote endpoint over HTTP. No local process, no Node.js.

### A literal header

This guide puts the key straight into the `Authorization` header, because environment-variable expansion in Zed headers is not verified here. Keep it in your user settings, not in a file you commit.

### Tool permissions

Zed asks before each tool call by default. Allow Maguyva’s tools one at a time under `agent.tool_permissions.tools`, with keys like `mcp:maguyva:find_symbol`.

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

```text
# .rules
- Run the repo test command before you call a change done.
- Keep edits inside the package you were asked to change.
```

Zed loads one project instruction file: the first match from a fixed list that starts with `.rules` and includes `AGENTS.md` and `CLAUDE.md`. Personal instructions go in `~/.config/zed/AGENTS.md`. Use them for:

- Build, test, and lint commands.
- Conventions the agent keeps getting wrong.
- Directories the agent should not touch.

An instruction file tells the agent how to work. It cannot tell the agent which of four thousand files call the function it is about to change.

## Where the open buffer runs out

Three things the Zed agent cannot learn from the files in front of it.

### // the open file isn’t the repo

The agent sees what you opened and what it greps. A helper with the same name in another package looks identical until the wrong one ships.

### // callers aren’t on screen

“What breaks if I change this signature?” is a graph question. Without an index, the agent reads files one at a time until it runs out of turns or context.

### // context has a budget

Every file the agent opens to orient itself costs tokens it cannot spend on the change. One ranked answer with file:line costs less than ten exploratory reads.

## Maguyva as a Zed context server

One context_servers entry gives the Zed 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.
- **A tool list that stays current**: Zed reloads a server’s tools when the server announces a change, without a restart.

> Zed gives the agent *a fast editor*.
> Maguyva gives the agent *a map of the code*.

## Two workflows

Ask the map first, then edit.

### 01. Find the implementation before the agent opens a tab

```text
zed agent> where is the retry policy for outbound webhooks?

find_symbol("retryPolicy")
  src/webhooks/dispatch.ts:41   retryPolicy()   ← implementation
  src/webhooks/__mocks__/dispatch.ts:9   ← mock

→ The agent opens dispatch.ts:41, not the mock.
[exit 0]
```

One ranked lookup replaces a round of grep. The answer comes back as a path and a line the agent can open directly.

### 02. Check dependents before a signature change

```text
zed agent> add a timeout argument to fetchInvoice

dependency_search("fetchInvoice", dependents)
  7 callers across 4 packages

→ The agent updates all seven call sites in one pass.
[exit 0]
```

The blast radius arrives before the first edit, not after the build fails.

## Setup in Zed

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 context_servers in your Zed settings

`~/.config/zed/settings.json`

```json
{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
```

### 03. Replace the placeholder and ask one question

Swap `mgv_xxxx` for your API key and save. Ask the agent one question whose answer you already know, then open the cited file.

Zed’s own [MCP docs](https://zed.dev/docs/ai/mcp) cover context servers, agent profiles, and tool permissions.

## Index one repo you already know.

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