docs: Add instructions about how to use MCP servers (#34656)

Release Notes:

- N/A

docs/src/ai/agent-panel.md

@@ -121,6 +121,12 @@ Zed will store this profile in your settings using the same profile name as the
 
 All custom profiles can be edited via the UI or by hand under the `assistant.profiles` key in your `settings.json` file.
 
+### Tool Approval
+
+Zed's Agent Panel surfaces the `agent.always_allow_tool_actions` setting that, if turned to `false`, will require you to give permission to any editing attempt as well as tool calls coming from MCP servers.
+
+You can change that by setting this key to `true` in either your `settings.json` or via the Agent Panel's settings view.
+
 ### Model Support {#model-support}
 
 Tool calling needs to be individually supported by each model and model provider.

docs/src/ai/mcp.md

@@ -4,35 +4,35 @@ Zed uses the [Model Context Protocol](https://modelcontextprotocol.io/) to inter
 
 > The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
 
-Check out the [Anthropic news post](https://www.anthropic.com/news/model-context-protocol) and the [Zed blog post](https://zed.dev/blog/mcp) for an introduction to MCP.
+Check out the [Anthropic news post](https://www.anthropic.com/news/model-context-protocol) and the [Zed blog post](https://zed.dev/blog/mcp) for a general intro to MCP.
 
-## MCP Servers as Extensions
+## Installing MCP Servers
+
+### As Extensions
 
 One of the ways you can use MCP servers in Zed is by exposing them as an extension.
-To learn how to do that, check out the [MCP Server Extensions](../extensions/mcp-extensions.md) page for more details.
+To learn how to create your own, check out the [MCP Server Extensions](../extensions/mcp-extensions.md) page for more details.
 
-### Available extensions
+Thanks to our awesome community, many MCP servers have already been added as extensions.
-
+You can check which ones are available via any of these routes:
-Many MCP servers have been exposed as extensions already, thanks to Zed's awesome community.
-Check which ones are already available in Zed's extension store via any of these routes:
 
 1. [the Zed website](https://zed.dev/extensions?filter=context-servers)
-2. in the app, run the `zed: extensions` action
+2. in the app, open the Command Palette and run the `zed: extensions` action
 3. in the app, go to the Agent Panel's top-right menu and look for the "View Server Extensions" menu item
 
 In any case, here are some of the ones available:
 
-- [Postgres](https://github.com/zed-extensions/postgres-context-server)
+- [Context7](https://zed.dev/extensions/context7-mcp-server)
-- [GitHub](https://github.com/LoamStudios/zed-mcp-server-github)
+- [GitHub](https://zed.dev/extensions/github-mcp-server)
-- [Puppeteer](https://github.com/zed-extensions/mcp-server-puppeteer)
+- [Puppeteer](https://zed.dev/extensions/puppeteer-mcp-server)
-- [BrowserTools](https://github.com/mirageN1349/browser-tools-context-server)
+- [Gem](https://zed.dev/extensions/gem)
-- [Brave Search](https://github.com/zed-extensions/mcp-server-brave-search)
+- [Brave Search](https://zed.dev/extensions/brave-search-mcp-server)
 - [Prisma](https://github.com/aqrln/prisma-mcp-zed)
-- [Framelink Figma](https://github.com/LoamStudios/zed-mcp-server-figma)
+- [Framelink Figma](https://zed.dev/extensions/framelink-figma-mcp-server)
-- [Linear](https://github.com/LoamStudios/zed-mcp-server-linear)
+- [Linear](https://zed.dev/extensions/linear-mcp-server)
-- [Resend](https://github.com/danilo-leal/zed-resend-mcp-server)
+- [Resend](https://zed.dev/extensions/resend-mcp-server)
 
-## Add your own MCP server
+### As Custom Servers
 
 Creating an extension is not the only way to use MCP servers in Zed.
 You can connect them by adding their commands directly to your `settings.json`, like so:
@@ -51,4 +51,77 @@ You can connect them by adding their commands directly to your `settings.json`,
 ```
 
 Alternatively, you can also add a custom server by accessing the Agent Panel's Settings view (also accessible via the `agent: open configuration` action).
-From there, you can add it through the modal that appears when clicking the "Add Custom Server" button.
+From there, you can add it through the modal that appears when you click the "Add Custom Server" button.
+
+## Using MCP Servers
+
+### Installation Check
+
+Regardless of whether you're using MCP servers as an extension or adding them directly, most servers out there need some sort of configuration as part of the set up process.
+
+In the case of extensions, Zed will show a modal displaying what is required for you to properly set up a given server.
+For 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).
+
+In 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.
+
+To check whether your MCP server is properly installed, go to the Agent Panel's settings view and watch the indicator dot next to its name.
+If they're running correctly, the indicator will be green and its tooltip will say "Server is active".
+If not, other colors and tooltip messages will indicate what is happening.
+
+### Using in the Agent Panel
+
+Once installation is complete, you can return to the Agent Panel and start prompting.
+Mentioning your MCP server by name helps the agent pick it up.
+
+If you want to ensure a given server will be used, you can create [a custom profile](./agent-panel.md#custom-profiles) by turning off the built-in tools (either all of them or the ones that would cause conflicts) and turning on only the tools coming from the MCP server.
+
+As an example, [the Dagger team suggests](https://container-use.com/agent-integrations#add-container-use-agent-profile-optional) doing that with their [Container Use MCP server](https://zed.dev/extensions/container-use-mcp-server):
+
+```json
+"agent": {
+  "profiles": {
+    "container-use": {
+      "name": "Container Use",
+      "tools": {
+        "fetch": true,
+        "thinking": true,
+        "copy_path": false,
+        "find_path": false,
+        "delete_path": false,
+        "create_directory": false,
+        "list_directory": false,
+        "diagnostics": false,
+        "read_file": false,
+        "open": false,
+        "move_path": false,
+        "grep": false,
+        "edit_file": false,
+        "terminal": false
+      },
+      "enable_all_context_servers": false,
+      "context_servers": {
+        "container-use": {
+          "tools": {
+            "environment_create": true,
+            "environment_add_service": true,
+            "environment_update": true,
+            "environment_run_cmd": true,
+            "environment_open": true,
+            "environment_file_write": true,
+            "environment_file_read": true,
+            "environment_file_list": true,
+            "environment_file_delete": true,
+            "environment_checkpoint": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Tool Approval
+
+Zed's Agent Panel includes the `agent.always_allow_tool_actions` setting that, if set to `false`, will require you to give permission for any editing attempt as well as tool calls coming from MCP servers.
+
+You can change this by setting this key to `true` in either your `settings.json` or through the Agent Panel's settings view.