1---
2title: Model Context Protocol (MCP) in Zed
3description: Install and configure MCP servers in Zed to extend your AI agent with external tools, data sources, and integrations.
4---
5
6# Model Context Protocol
7
8Zed uses the [Model Context Protocol](https://modelcontextprotocol.io/) to interact with context servers.
9
10> The Model Context Protocol (MCP) is an open protocol for connecting LLM applications to external tools and data sources through a standard interface.
11
12## Supported Features
13
14Zed currently supports MCP's [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) and [Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts) features.
15We welcome contributions that help advance Zed's MCP feature coverage (Discovery, Sampling, Elicitation, etc).
16
17Zed also handles the `notifications/tools/list_changed` notification from MCP servers. When a server adds, removes, or modifies its available tools at runtime, Zed automatically reloads the tool list without requiring a server restart.
18
19## Installing MCP Servers
20
21### As Extensions
22
23One of the ways you can use MCP servers in Zed is by exposing them as an extension.
24Check out the [MCP Server Extensions](../extensions/mcp-extensions.md) page to learn how to create your own.
25
26Many MCP servers are available as extensions. Find them via:
27
281. [the Zed website](https://zed.dev/extensions?filter=context-servers)
292. in the app, open the Command Palette and run the `zed: extensions` action
303. in the app, go to the Agent Panel's top-right menu and look for the "View Server Extensions" menu item
31
32Popular servers available as an extension include:
33
34- [Context7](https://zed.dev/extensions/context7-mcp-server)
35- [GitHub](https://zed.dev/extensions/github-mcp-server)
36- [Puppeteer](https://zed.dev/extensions/puppeteer-mcp-server)
37- [Gem](https://zed.dev/extensions/gem)
38- [Brave Search](https://zed.dev/extensions/brave-search-mcp-server)
39- [Prisma](https://github.com/aqrln/prisma-mcp-zed)
40- [Framelink Figma](https://zed.dev/extensions/framelink-figma-mcp-server)
41- [Resend](https://zed.dev/extensions/resend-mcp-server)
42
43### As Custom Servers
44
45Creating an extension is not the only way to use MCP servers in Zed.
46You can connect them by adding their commands directly to your settings file ([how to edit](../configuring-zed.md#settings-files)), like so:
47
48```json [settings]
49{
50 "context_servers": {
51 "local-mcp-server": {
52 "command": "some-command",
53 "args": ["arg-1", "arg-2"],
54 "env": {}
55 },
56 "remote-mcp-server": {
57 "url": "custom",
58 "headers": { "Authorization": "Bearer <token>" }
59 },
60 "remote-mcp-server-with-oauth": {
61 "url": "https://mcp.example.com/mcp"
62 }
63 }
64}
65```
66
67Alternatively, you can also add a custom server by accessing the Agent Panel's Settings view (also accessible via the `agent: open settings` action).
68From there, you can add it through the modal that appears when you click the "Add Custom Server" button.
69
70> Note: When a remote MCP server has no configured `"Authorization"` header, Zed will prompt you to authenticate yourself against the MCP server using the standard MCP OAuth flow.
71
72## Using MCP Servers
73
74### Configuration Check
75
76Most MCP servers require configuration after installation.
77
78In the case of extensions, after installing it, Zed will pop up a modal displaying what is required for you to properly set it up.
79For example, the GitHub MCP extension requires you to add a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
80
81In the case of custom servers, make sure you check the provider documentation to determine what type of command, arguments, and environment variables need to be added to the JSON.
82
83To check if your MCP server is properly configured, go to the Agent Panel's settings view and watch the indicator dot next to its name.
84If they're running correctly, the indicator will be green and its tooltip will say "Server is active".
85If not, other colors and tooltip messages will indicate what is happening.
86
87### Agent Panel Usage
88
89Once installation is complete, you can return to the Agent Panel and start prompting.
90
91How reliably MCP tools get called can vary from model to model.
92Mentioning the MCP server by name can help the model pick tools from that server.
93
94However, if you want to _ensure_ a given MCP server will be used, you can create [a custom profile](./agent-panel.md#custom-profiles) where all built-in tools (or the ones that could cause conflicts with the server's tools) are turned off and only the tools coming from the MCP server are turned on.
95
96As an example, [the Dagger team suggests](https://container-use.com/agent-integrations#zed) doing that with their [Container Use MCP server](https://zed.dev/extensions/mcp-server-container-use):
97
98```json [settings]
99"agent": {
100 "profiles": {
101 "container-use": {
102 "name": "Container Use",
103 "tools": {
104 "fetch": true,
105 "thinking": true,
106 "copy_path": false,
107 "find_path": false,
108 "delete_path": false,
109 "create_directory": false,
110 "list_directory": false,
111 "diagnostics": false,
112 "read_file": false,
113 "open": false,
114 "move_path": false,
115 "grep": false,
116 "edit_file": false,
117 "terminal": false
118 },
119 "enable_all_context_servers": false,
120 "context_servers": {
121 "container-use": {
122 "tools": {
123 "environment_create": true,
124 "environment_add_service": true,
125 "environment_update": true,
126 "environment_run_cmd": true,
127 "environment_open": true,
128 "environment_file_write": true,
129 "environment_file_read": true,
130 "environment_file_list": true,
131 "environment_file_delete": true,
132 "environment_checkpoint": true
133 }
134 }
135 }
136 }
137 }
138}
139```
140
141### Tool Permissions
142
143> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
144> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
145
146Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior for the native Zed agent:
147
148- `"confirm"` (default) — Prompts for approval before running any tool action, including MCP tool calls
149- `"allow"` — Auto-approves tool actions without prompting
150- `"deny"` — Blocks all tool actions
151
152For granular control over specific MCP tools, you can configure per-tool permission rules.
153MCP tools use the key format `mcp:<server>:<tool_name>` — for example, `mcp:github:create_issue`.
154The `default` key on a per-tool entry is the primary mechanism for MCP tools, since pattern-based rules match against an empty string for MCP tools and most patterns won't match.
155
156Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
157
158### External Agents
159
160Note that for [external agents](./external-agents.md) connected through the [Agent Client Protocol](https://agentclientprotocol.com/), access to MCP servers installed from Zed may vary depending on the ACP agent implementation.
161
162Regarding the built-in ones, Claude Agent and Codex both support it, and Gemini CLI does not yet.
163In the meantime, learn how to add MCP server support to Gemini CLI through [their documentation](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#using-mcp-servers).
164
165### Error Handling
166
167When a MCP server encounters an error while processing a tool call, the agent receives the error message directly and the operation fails.
168Common error scenarios include:
169
170- Invalid parameters passed to the tool
171- Server-side failures (database connection issues, rate limits)
172- Unsupported operations or missing resources
173
174The error message from the context server will be shown in the agent's response, allowing you to diagnose and correct the issue.
175Check the context server's logs or documentation for details about specific error codes.