docs: improve MCP server configuration guidance with examples and caveats

.opencode/command/commit.md

@@ -1,3 +1,7 @@
+---
+description: Git commit and push
+---
+
 commit and push
 
 make sure it includes a prefix like

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

@@ -3,48 +3,52 @@ 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:
+You can add external tools to OpenCode using the _Model Context Protocol_, or MCP.
+
+OpenCode supports both:
 
 - Local servers
 - Remote servers
 
 Once added, MCP tools are automatically available to the LLM alongside built-in tools.
 
----
-
-## Configure
-
-You can define MCP servers in your OpenCode config under `mcp`.
+:::note
+OAuth support for MCP servers is coming soon.
+:::
 
 ---
 
-### Local
+## Caveats
 
-Add local MCP servers using `"type": "local"` within the MCP object. Multiple MCP servers can be added.
+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.
 :::
 
-The key string for each server can be any arbitrary name.
+Certain MCP servers, like the GitHub MCP server tend to add a lot of tokens and
+can easily exceed the context limit.
+
+---
+
+## Configure
+
+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.
 
-```json title="opencode.json" {15}
+```jsonc title="opencode.jsonc" {6}
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
-    "my-local-mcp-server": {
-      "type": "local",
-      "command": ["bun", "x", "my-mcp-command"],
-      "enabled": true,
-      "environment": {
-        "MY_ENV_VAR": "my_env_var_value"
-      }
-    },
-    "my-different-local-mcp-server": {
-      "type": "local",
-      "command": ["bun", "x", "my-other-mcp-command"],
+    "name-of-mcp-server": {
+      // ...
       "enabled": true
+    },
+    "name-of-other-mcp-server": {
+      // ...
     }
   }
 }
@@ -54,40 +58,71 @@ You can also disable a server by setting `enabled` to `false`. This is useful if
 
 ---
 
-### Remote
+### Local
 
-Add remote MCP servers under `mcp` with `"type": "remote"`.
+Add local MCP servers using `type` to `"local"` within the MCP object.
 
-```json title="opencode.json"
+```jsonc title="opencode.jsonc" {15}
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
-    "my-remote-mcp": {
-      "type": "remote",
-      "url": "https://my-mcp-server.com",
+    "my-local-mcp-server": {
+      "type": "local",
+      // Or ["bun", "x", "my-mcp-command"]
+      "command": ["npx", "-y", "my-mcp-command"],
       "enabled": true,
-      "headers": {
-        "Authorization": "Bearer MY_API_KEY"
+      "environment": {
+        "MY_ENV_VAR": "my_env_var_value"
       }
     }
   }
 }
 ```
 
-Local and remote servers can be used together within the same `mcp` config object.
+The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
 
-```json title="opencode.json"
+For example, here's how I can add the test
+[`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
+
+```jsonc title="opencode.jsonc"
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
-    "my-local-mcp-server": {
+    "mcp_everything": {
       "type": "local",
-      "command": ["bun", "x", "my-mcp-command"],
-      "enabled": true,
-      "environment": {
-        "MY_ENV_VAR": "my_env_var_value"
-      }
-    },
+      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
+    }
+  }
+}
+```
+
+And to use it I can add `use the mcp_everything tool` to my prompts.
+
+```txt "mcp_everything"
+use the mcp_everything tool to add the number 3 and 4
+```
+
+#### Options
+
+Here are all the options for configuring a local MCP server.
+
+| Option        | Type    | Required | Description                                           |
+| ------------- | ------- | -------- | ----------------------------------------------------- |
+| `type`        | String  | Y        | Type of MCP server connection, must be `"local"`.     |
+| `command`     | Array   | Y        | Command and arguments to run the MCP server.          |
+| `environment` | Object  |          | Environment variables to set when running the server. |
+| `enabled`     | Boolean |          | Enable or disable the MCP server on startup.          |
+
+---
+
+### Remote
+
+Add remote MCP servers under by setting `type` to `"remote"`.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "my-remote-mcp": {
       "type": "remote",
       "url": "https://my-mcp-server.com",
@@ -100,6 +135,17 @@ Local and remote servers can be used together within the same `mcp` config objec
 }
 ```
 
+Here the `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
+
+#### Options
+
+| Option    | Type    | Required | Description                                        |
+| --------- | ------- | -------- | -------------------------------------------------- |
+| `type`    | String  | Y        | Type of MCP server connection, must be `"remote"`. |
+| `url`     | String  | Y        | URL of the remote MCP server.                      |
+| `enabled` | Boolean |          | Enable or disable the MCP server on startup.       |
+| `headers` | Object  |          | Headers to send with the request.                  |
+
 ---
 
 ## Manage
@@ -197,3 +243,90 @@ The glob pattern uses simple regex globbing patterns.
 - `*` matches zero or more of any character
 - `?` matches exactly one character
 - All other characters match literally
+
+---
+
+## Examples
+
+Below are examples of some common MCP servers. You can submit a PR if you want to document other servers.
+
+---
+
+### Context7
+
+Add the [Context7 MCP server](https://github.com/context-labs/mcp-server-context7) to search through docs.
+
+```json title="opencode.json" {4-7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+```
+
+If you have signed up for a free account, you can use your API key and get higher rate-limits.
+
+```json title="opencode.json" {7-9}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Here we are assuming that you have the `CONTEXT7_API_KEY` environment variable set.
+
+Add `use context7` to your prompts to use Context7 MCP server.
+
+```txt "use context7"
+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/).
+
+```md title="AGENTS.md"
+When you need to search docs, use `context7` tools.
+```
+
+---
+
+### Grep by Vercel
+
+Add the [Grep by Vercel](https://github.com/vercel/grep-by-vercel) MCP server to search through code snippets on GitHub.
+
+```json title="opencode.json" {4-7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "gh_grep": {
+      "type": "remote",
+      "url": "https://mcp.grep.app"
+    }
+  }
+}
+```
+
+Since we named our MCP server `gh_grep`, you can add `use the gh_grep tool` to your prompts to get the agent to use it.
+
+```txt "use the gh_grep tool"
+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/).
+
+```md title="AGENTS.md"
+If you are unsure how to do something, use `gh_grep` to search code examples from github.
+```