docs: make MCP server documentation more scannable and add Sentry example

.opencode/agent/docs.md

@@ -6,6 +6,8 @@ You are an expert technical documentation writer
 
 You are not verbose
 
+Use a relaxed and friendly tone
+
 The title of the page should be a word or a 2-3 word phrase
 
 The description should be one short line, should not start with "The", should

packages/web/src/content/docs/mcp-servers.mdx

@@ -3,37 +3,27 @@ title: MCP servers
 description: Add local and remote MCP tools.
 ---
 
-You can add external tools to OpenCode using the _Model Context Protocol_, or MCP.
-
-OpenCode supports both:
-
-- Local servers
-- Remote servers
+You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both local and remote servers.
 
 Once added, MCP tools are automatically available to the LLM alongside built-in tools.
 
 ---
 
-## Caveats
+#### Caveats
 
-When you use an MCP server, it adds to the context. This can quickly add up if
-you have a lot of tools. So we recommend being careful with which MCP servers
-you use.
+When you use an MCP server, it adds to the context. This can quickly add up if you have a lot of tools. So we recommend being careful with which MCP servers you use.
 
 :::tip
-MCP servers add to your context, so you want to be careful with which
-ones you enable.
+MCP servers add to your context, so you want to be careful with which ones you enable.
 :::
 
-Certain MCP servers, like the GitHub MCP server tend to add a lot of tokens and
-can easily exceed the context limit.
+Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
 
 ---
 
-## Configure
+## Enable
 
-You can define MCP servers in your OpenCode config under `mcp`. Add each MCP
-with a unique name. You can refer to that MCP by name when prompting the LLM.
+You can define MCP servers in your OpenCode config under `mcp`. Add each MCP with a unique name. You can refer to that MCP by name when prompting the LLM.
 
 ```jsonc title="opencode.jsonc" {6}
 {
@@ -54,7 +44,7 @@ You can also disable a server by setting `enabled` to `false`. This is useful if
 
 ---
 
-### Local
+## Local
 
 Add local MCP servers using `type` to `"local"` within the MCP object.
 
@@ -77,8 +67,7 @@ Add local MCP servers using `type` to `"local"` within the MCP object.
 
 The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
 
-For example, here's how I can add the test
-[`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
+For example, here's how you can add the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
 
 ```jsonc title="opencode.jsonc"
 {
@@ -98,6 +87,8 @@ And to use it I can add `use the mcp_everything tool` to my prompts.
 use the mcp_everything tool to add the number 3 and 4
 ```
 
+---
+
 #### Options
 
 Here are all the options for configuring a local MCP server.
@@ -112,9 +103,9 @@ Here are all the options for configuring a local MCP server.
 
 ---
 
-### Remote
+## Remote
 
-Add remote MCP servers under by setting `type` to `"remote"`.
+Add remote MCP servers by setting `type` to `"remote"`.
 
 ```json title="opencode.json"
 {
@@ -132,7 +123,9 @@ Add remote MCP servers under by setting `type` to `"remote"`.
 }
 ```
 
-Here the `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
+The `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
+
+---
 
 #### Options
 
@@ -147,7 +140,7 @@ Here the `url` is the URL of the remote MCP server and with the `headers` option
 
 ---
 
-### OAuth
+## OAuth
 
 OpenCode automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, OpenCode will:
 
@@ -155,7 +148,9 @@ OpenCode automatically handles OAuth authentication for remote MCP servers. When
 2. Use **Dynamic Client Registration (RFC 7591)** if supported by the server
 3. Store tokens securely for future requests
 
-#### Automatic OAuth
+---
+
+### Automatic
 
 For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server:
 
@@ -173,11 +168,13 @@ For most OAuth-enabled MCP servers, no special configuration is needed. Just con
 
 If the server requires authentication, OpenCode will prompt you to authenticate when you first try to use it. If not, you can [manually trigger the flow](#authenticating) with `opencode mcp auth <server-name>`.
 
-#### Pre-registered Client
+---
+
+### Pre-registered
 
 If you have client credentials from the MCP server provider, you can configure them:
 
-```json title="opencode.json"
+```json title="opencode.json" {7-11}
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
@@ -194,11 +191,39 @@ If you have client credentials from the MCP server provider, you can configure t
 }
 ```
 
+---
+
+### Authenticating
+
+You can manually trigger authentication or manage credentials.
+
+Authenticate with a specific MCP server:
+
+```bash
+opencode mcp auth my-oauth-server
+```
+
+List all MCP servers and their auth status:
+
+```bash
+opencode mcp list
+```
+
+Remove stored credentials:
+
+```bash
+opencode mcp logout my-oauth-server
+```
+
+The `mcp auth` command will open your browser for authorization. After you authorize, OpenCode will store the tokens securely in `~/.local/share/opencode/mcp-auth.json`.
+
+---
+
 #### Disabling OAuth
 
 If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set `oauth` to `false`:
 
-```json title="opencode.json"
+```json title="opencode.json" {7}
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
@@ -214,31 +239,16 @@ If you want to disable automatic OAuth for a server (e.g., for servers that use
 }
 ```
 
-#### OAuth Options
-
-| Option         | Type            | Required | Description                                                                      |
-| -------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
-| `oauth`        | Object \| false |          | OAuth config object, or `false` to disable OAuth auto-detection.                 |
-| `clientId`     | String          |          | OAuth client ID. If not provided, dynamic client registration will be attempted. |
-| `clientSecret` | String          |          | OAuth client secret, if required by the authorization server.                    |
-| `scope`        | String          |          | OAuth scopes to request during authorization.                                    |
-
-#### Authenticating
-
-You can manually trigger authentication or manage credentials:
-
-```bash
-# Authenticate with a specific MCP server
-opencode mcp auth my-oauth-server
-
-# List all MCP servers and their auth status
-opencode mcp list
+---
 
-# Remove stored credentials
-opencode mcp logout my-oauth-server
-```
+#### OAuth Options
 
-The `mcp auth` command will open your browser for authorization. After you authorize, OpenCode will store the tokens securely in `~/.local/share/opencode/mcp-auth.json`.
+| Option         | Type            | Description                                                                      |
+| -------------- | --------------- | -------------------------------------------------------------------------------- |
+| `oauth`        | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection.                 |
+| `clientId`     | String          | OAuth client ID. If not provided, dynamic client registration will be attempted. |
+| `clientSecret` | String          | OAuth client secret, if required by the authorization server.                    |
+| `scope`        | String          | OAuth scopes to request during authorization.                                    |
 
 #### Debugging
 
@@ -258,8 +268,7 @@ The `mcp debug` command shows the current auth status, tests HTTP connectivity,
 
 ## Manage
 
-Your MCPs are available as tools in OpenCode, alongside built-in tools. So you
-can manage them through the OpenCode config like any other tool.
+Your MCPs are available as tools in OpenCode, alongside built-in tools. So you can manage them through the OpenCode config like any other tool.
 
 ---
 
@@ -313,11 +322,10 @@ Here we are using the glob pattern `my-mcp*` to disable all MCPs.
 
 ### Per agent
 
-If you have a large number of MCP servers you may want to only enable them per
-agent and disable them globally. To do this:
+If you have a large number of MCP servers you may want to only enable them per agent and disable them globally. To do this:
 
 1. Disable it as a tool globally.
-2. In your [agent config](/docs/agents#tools) enable the MCP server as a tool.
+2. In your [agent config](/docs/agents#tools), enable the MCP server as a tool.
 
 ```json title="opencode.json" {11, 14-18}
 {
@@ -360,6 +368,39 @@ Below are examples of some common MCP servers. You can submit a PR if you want t
 
 ---
 
+### Sentry
+
+Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues.
+
+```json title="opencode.json" {4-8}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sentry": {
+      "type": "remote",
+      "url": "https://mcp.sentry.dev/mcp",
+      "oauth": {}
+    }
+  }
+}
+```
+
+After adding the configuration, authenticate with Sentry:
+
+```bash
+opencode mcp auth sentry
+```
+
+This will open a browser window to complete the OAuth flow and connect OpenCode to your Sentry account.
+
+Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data.
+
+```txt "use sentry"
+Show me the latest unresolved issues in my project. use sentry
+```
+
+---
+
 ### Context7
 
 Add the [Context7 MCP server](https://github.com/upstash/context7) to search through docs.
@@ -401,8 +442,7 @@ Add `use context7` to your prompts to use Context7 MCP server.
 Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
 ```
 
-Alternatively, you can add something like this to your
-[AGENTS.md](/docs/rules/).
+Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
 
 ```md title="AGENTS.md"
 When you need to search docs, use `context7` tools.
@@ -432,9 +472,8 @@ Since we named our MCP server `gh_grep`, you can add `use the gh_grep tool` to y
 What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
 ```
 
-Alternatively, you can add something like this to your
-[AGENTS.md](/docs/rules/).
+Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
 
 ```md title="AGENTS.md"
-If you are unsure how to do something, use `gh_grep` to search code examples from github.
+If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
 ```