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

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.

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. Older builds may still show Rules in the UI.

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.

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.

{
  "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.

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.

{
  "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.

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