Skip to content

Commit eeed89f

Browse files
jayairjayair
committed
docs: make MCP server documentation more scannable and add Sentry example
1 parent 8ab533b commit eeed89f

File tree

2 files changed

+102
-61
lines changed

2 files changed

+102
-61
lines changed

‎.opencode/agent/docs.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ You are an expert technical documentation writer
66

77
You are not verbose
88

9+
Use a relaxed and friendly tone
10+
911
The title of the page should be a word or a 2-3 word phrase
1012

1113
The description should be one short line, should not start with "The", should

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

Lines changed: 100 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -3,37 +3,27 @@ title: MCP servers
33
description: Add local and remote MCP tools.
44
---
55

6-
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP.
7-
8-
OpenCode supports both:
9-
10-
- Local servers
11-
- Remote servers
6+
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP. OpenCode supports both local and remote servers.
127

138
Once added, MCP tools are automatically available to the LLM alongside built-in tools.
149

1510
---
1611

17-
## Caveats
12+
#### Caveats
1813

19-
When you use an MCP server, it adds to the context. This can quickly add up if
20-
you have a lot of tools. So we recommend being careful with which MCP servers
21-
you use.
14+
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.
2215

2316
:::tip
24-
MCP servers add to your context, so you want to be careful with which
25-
ones you enable.
17+
MCP servers add to your context, so you want to be careful with which ones you enable.
2618
:::
2719

28-
Certain MCP servers, like the GitHub MCP server tend to add a lot of tokens and
29-
can easily exceed the context limit.
20+
Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
3021

3122
---
3223

33-
## Configure
24+
## Enable
3425

35-
You can define MCP servers in your OpenCode config under `mcp`. Add each MCP
36-
with a unique name. You can refer to that MCP by name when prompting the LLM.
26+
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.
3727

3828
```jsonc title="opencode.jsonc" {6}
3929
{
@@ -54,7 +44,7 @@ You can also disable a server by setting `enabled` to `false`. This is useful if
5444

5545
---
5646

57-
### Local
47+
## Local
5848

5949
Add local MCP servers using `type` to `"local"` within the MCP object.
6050

@@ -77,8 +67,7 @@ Add local MCP servers using `type` to `"local"` within the MCP object.
7767

7868
The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
7969

80-
For example, here's how I can add the test
81-
[`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
70+
For example, here's how you can add the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
8271

8372
```jsonc title="opencode.jsonc"
8473
{
@@ -98,6 +87,8 @@ And to use it I can add `use the mcp_everything tool` to my prompts.
9887
use the mcp_everything tool to add the number 3 and 4
9988
```
10089

90+
---
91+
10192
#### Options
10293

10394
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.
112103

113104
---
114105

115-
### Remote
106+
## Remote
116107

117-
Add remote MCP servers under by setting `type` to `"remote"`.
108+
Add remote MCP servers by setting `type` to `"remote"`.
118109

119110
```json title="opencode.json"
120111
{
@@ -132,7 +123,9 @@ Add remote MCP servers under by setting `type` to `"remote"`.
132123
}
133124
```
134125

135-
Here the `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
126+
The `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
127+
128+
---
136129

137130
#### Options
138131

@@ -147,15 +140,17 @@ Here the `url` is the URL of the remote MCP server and with the `headers` option
147140

148141
---
149142

150-
### OAuth
143+
## OAuth
151144

152145
OpenCode automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, OpenCode will:
153146

154147
1. Detect the 401 response and initiate the OAuth flow
155148
2. Use **Dynamic Client Registration (RFC 7591)** if supported by the server
156149
3. Store tokens securely for future requests
157150

158-
#### Automatic OAuth
151+
---
152+
153+
### Automatic
159154

160155
For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server:
161156

@@ -173,11 +168,13 @@ For most OAuth-enabled MCP servers, no special configuration is needed. Just con
173168

174169
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>`.
175170

176-
#### Pre-registered Client
171+
---
172+
173+
### Pre-registered
177174

178175
If you have client credentials from the MCP server provider, you can configure them:
179176

180-
```json title="opencode.json"
177+
```json title="opencode.json" {7-11}
181178
{
182179
"$schema": "https://opencode.ai/config.json",
183180
"mcp": {
@@ -194,11 +191,39 @@ If you have client credentials from the MCP server provider, you can configure t
194191
}
195192
```
196193

194+
---
195+
196+
### Authenticating
197+
198+
You can manually trigger authentication or manage credentials.
199+
200+
Authenticate with a specific MCP server:
201+
202+
```bash
203+
opencode mcp auth my-oauth-server
204+
```
205+
206+
List all MCP servers and their auth status:
207+
208+
```bash
209+
opencode mcp list
210+
```
211+
212+
Remove stored credentials:
213+
214+
```bash
215+
opencode mcp logout my-oauth-server
216+
```
217+
218+
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`.
219+
220+
---
221+
197222
#### Disabling OAuth
198223

199224
If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set `oauth` to `false`:
200225

201-
```json title="opencode.json"
226+
```json title="opencode.json" {7}
202227
{
203228
"$schema": "https://opencode.ai/config.json",
204229
"mcp": {
@@ -214,31 +239,16 @@ If you want to disable automatic OAuth for a server (e.g., for servers that use
214239
}
215240
```
216241

217-
#### OAuth Options
218-
219-
| Option | Type | Required | Description |
220-
| -------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
221-
| `oauth` | Object \| false | | OAuth config object, or `false` to disable OAuth auto-detection. |
222-
| `clientId` | String | | OAuth client ID. If not provided, dynamic client registration will be attempted. |
223-
| `clientSecret` | String | | OAuth client secret, if required by the authorization server. |
224-
| `scope` | String | | OAuth scopes to request during authorization. |
225-
226-
#### Authenticating
227-
228-
You can manually trigger authentication or manage credentials:
229-
230-
```bash
231-
# Authenticate with a specific MCP server
232-
opencode mcp auth my-oauth-server
233-
234-
# List all MCP servers and their auth status
235-
opencode mcp list
242+
---
236243

237-
# Remove stored credentials
238-
opencode mcp logout my-oauth-server
239-
```
244+
#### OAuth Options
240245

241-
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`.
246+
| Option | Type | Description |
247+
| -------------- | --------------- | -------------------------------------------------------------------------------- |
248+
| `oauth` | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection. |
249+
| `clientId` | String | OAuth client ID. If not provided, dynamic client registration will be attempted. |
250+
| `clientSecret` | String | OAuth client secret, if required by the authorization server. |
251+
| `scope` | String | OAuth scopes to request during authorization. |
242252

243253
#### Debugging
244254

@@ -258,8 +268,7 @@ The `mcp debug` command shows the current auth status, tests HTTP connectivity,
258268

259269
## Manage
260270

261-
Your MCPs are available as tools in OpenCode, alongside built-in tools. So you
262-
can manage them through the OpenCode config like any other tool.
271+
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.
263272

264273
---
265274

@@ -313,11 +322,10 @@ Here we are using the glob pattern `my-mcp*` to disable all MCPs.
313322

314323
### Per agent
315324

316-
If you have a large number of MCP servers you may want to only enable them per
317-
agent and disable them globally. To do this:
325+
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:
318326

319327
1. Disable it as a tool globally.
320-
2. In your [agent config](/docs/agents#tools) enable the MCP server as a tool.
328+
2. In your [agent config](/docs/agents#tools), enable the MCP server as a tool.
321329

322330
```json title="opencode.json" {11, 14-18}
323331
{
@@ -360,6 +368,39 @@ Below are examples of some common MCP servers. You can submit a PR if you want t
360368

361369
---
362370

371+
### Sentry
372+
373+
Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues.
374+
375+
```json title="opencode.json" {4-8}
376+
{
377+
"$schema": "https://opencode.ai/config.json",
378+
"mcp": {
379+
"sentry": {
380+
"type": "remote",
381+
"url": "https://mcp.sentry.dev/mcp",
382+
"oauth": {}
383+
}
384+
}
385+
}
386+
```
387+
388+
After adding the configuration, authenticate with Sentry:
389+
390+
```bash
391+
opencode mcp auth sentry
392+
```
393+
394+
This will open a browser window to complete the OAuth flow and connect OpenCode to your Sentry account.
395+
396+
Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data.
397+
398+
```txt "use sentry"
399+
Show me the latest unresolved issues in my project. use sentry
400+
```
401+
402+
---
403+
363404
### Context7
364405

365406
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.
401442
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
402443
```
403444

404-
Alternatively, you can add something like this to your
405-
[AGENTS.md](/docs/rules/).
445+
Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
406446

407447
```md title="AGENTS.md"
408448
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
432472
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
433473
```
434474

435-
Alternatively, you can add something like this to your
436-
[AGENTS.md](/docs/rules/).
475+
Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
437476

438477
```md title="AGENTS.md"
439-
If you are unsure how to do something, use `gh_grep` to search code examples from github.
478+
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
440479
```

0 commit comments

Comments
 (0)