# Warp’s agent lives in the terminal. Give it a map of the repo.

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

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).

Warp’s agent runs commands and reads what they print. Maguyva indexes the whole repo and serves it over MCP, so the agent asks where code lives instead of running grep and cat until something matches.

> One mcpServers entry in ~/.warp/.mcp.json: a URL and an Authorization header.

## What Warp needs to know

Four facts specific to Warp.

### ~/.warp/.mcp.json

Warp starts servers in this global file on its own. You can also paste the same JSON into Settings → Agents → MCP servers → + Add.

### Remote, by URL

A `url` entry connects over Streamable HTTP or SSE. Nothing runs locally and Node.js is not needed.

### A literal header

The key goes straight into the `Authorization` header. Keep it in the global file, not in a project’s `.warp/.mcp.json` that you commit.

### Never auto-started

Warp detects `.warp/.mcp.json` in a cloned repo but waits for you to start each server. It can also read servers from Claude Code and Codex configs once you turn that on.

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

```text
# AGENTS.md
- Run make test before you call a change done.
- Use the scripts in bin/, not ad hoc commands.
```

Warp reads project rules from `AGENTS.md` (or `WARP.md`, which wins if both exist) and applies Global Rules everywhere. Use them for:

- Build, test, and deploy commands.
- Conventions the agent keeps getting wrong.
- Commands the agent should never run.

Rules tell the agent how to work. They cannot tell it which service still reads the environment variable you are about to remove.

## Where grep in the terminal runs out

Three things a shell session cannot learn cheaply.

### // output scrolls past

Every grep and cat the agent runs lands in the conversation. A search that prints two hundred lines spends context before the real work starts.

### // a match isn’t a caller

grep cannot tell a real call from a comment, a fixture, or a method with the same name on another class.

### // the shell starts cold

A new session knows nothing about the repo. Maguyva’s index is already built, so the first question gets a ranked answer.

## Maguyva as a Warp MCP server

One mcpServers entry gives Warp’s 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, short enough to read in a terminal pane.
- **Tools that only read**: Maguyva’s tools query the index. None of them edit files or run commands.

> Warp gives the agent *a terminal*.
> Maguyva gives the agent *a map of the code*.

## Two workflows

Ask the map first, then run commands.

### 01. Trace a failing script to its source

```text
warp agent> deploy.sh fails: BUILD_ID is unset. where is it set?

text_pattern_search("BUILD_ID=")
  ci/env.sh:9   export BUILD_ID=...
  docs/deploy.md:31   ← prose

→ The agent sources ci/env.sh and reruns the deploy.
[exit 0]
```

One indexed search replaces a recursive grep across the repo and its output.

### 02. Check callers before changing a boot step

```text
warp agent> can we stop running migrations at startup?

dependency_search("runMigrations", dependents)
  3 callers: server.ts, worker.ts, scripts/seed.ts

→ The agent moves all three to the release step.
[exit 0]
```

The callers arrive before the change, so the worker does not boot against an old schema.

## Setup in Warp

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 ~/.warp/.mcp.json

`~/.warp/.mcp.json`

```json
{
  "mcpServers": {
    "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. Check that the server is running under Settings → Agents → MCP servers, then ask one question whose answer you already know.

Warp’s [MCP docs](https://docs.warp.dev/agents/capabilities/mcp/) cover file-based servers, sharing, and authentication.

## Index one repo you already know.

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