Skip to content
AgentAtlas

Zed agent: instruction files, MCP servers, tool permissions, and ACP agents

Which rules files does the Zed agent read, and how do I add MCP servers and control tool access?

The Zed Agent loads personal instructions from ~/.config/zed/AGENTS.md plus the first project file it finds from a fixed list that starts with .rules and includes AGENTS.md and CLAUDE.md. MCP servers go under context_servers in your settings file, and agent.tool_permissions plus agent profiles decide which tools run and when you are asked. Other agents like Claude Agent or Codex run inside Zed through the Agent Client Protocol.

Compare: rules and instruction files in every AI coding agent →

Compare: add an MCP server in every AI coding agent →

Instruction files Zed reads

Personal instructions live in ~/.config/zed/AGENTS.md (on Windows, under %APPDATA%\Zed\AGENTS.md) and apply to every project. For project instructions, Zed uses the first matching file in this order:

  • .rules
  • .cursorrules
  • .windsurfrules
  • .clinerules
  • .github/copilot-instructions.md
  • AGENT.md
  • AGENTS.md
  • CLAUDE.md
  • GEMINI.md

Project instructions override the personal AGENTS.md when they conflict. External agents may read their own native files directly instead, so Zed's loader does not control them.

What happened to the Rules Library

Rules have been replaced by Skills and Instructions. Reusable, on-demand rules become Skills, default always-on rules become your personal AGENTS.md, and project .rules files remain supported as compatible instruction files.

A skill is a folder with a SKILL.md file. Install skills globally in ~/.agents/skills/ or per project in .agents/skills/, or create one with the built-in /create-skill skill. The agent picks skills up from their descriptions, and you can call one directly with a slash command.

Adding MCP servers

Install MCP servers as extensions, or add custom ones from Settings, AI, MCP Servers, then Add Server. Custom servers are saved under context_servers in your settings file. A remote server with no Authorization header triggers the standard MCP OAuth flow.

settings.json

{
  "context_servers": {
    "local-mcp-server": {
      "command": "some-command",
      "args": ["arg-1", "arg-2"],
      "env": {}
    },
    "remote-mcp-server": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

A green indicator dot next to the server in Settings, AI, MCP Servers means it is active. Zed supports the MCP Tools and Prompts features.

Tool permissions, profiles, and external agents

In Zed v0.224.0 and later, agent.tool_permissions.default sets approval behavior: confirm (default), allow, or deny. Per-tool rules add always_allow, always_deny, and always_confirm regex patterns. MCP tools use the key format mcp:SERVER:TOOL_NAME, such as mcp:github:create_issue.

settings.json

{
  "agent": {
    "tool_permissions": {
      "default": "confirm",
      "tools": {
        "terminal": {
          "default": "confirm",
          "always_allow": [{ "pattern": "^cargo\\s+(build|test|check)" }],
          "always_deny": [{ "pattern": "sudo\\s+rm" }]
        },
        "mcp:github:create_issue": { "default": "confirm" }
      }
    }
  }
}

Profiles under agent.profiles decide which built-in and MCP tools are available. The built-in profiles are Write, Ask, and Minimal. Manage them with the agent: manage profiles command. Tool permissions still decide whether an available tool needs approval.

External agents connect through the Agent Client Protocol (ACP). Install them from the ACP Registry (zed: acp registry), or add a custom agent under agent_servers. Zed may forward its MCP servers to them over ACP, but Zed profiles and Skills do not apply to them.

settings.json (custom ACP agent)

{
  "agent_servers": {
    "my-agent": {
      "type": "custom",
      "command": "node",
      "args": ["~/projects/agent/index.js", "--acp"],
      "env": {}
    }
  }
}

Sources

More Zed guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →