Skip to content

Commit 7eddaa8

Browse files
jayairjayair
committed
docs: improve MCP server configuration guidance with examples and caveats
1 parent d07e79e commit 7eddaa8

File tree

2 files changed

+175
-38
lines changed

2 files changed

+175
-38
lines changed

‎.opencode/command/commit.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
description: Git commit and push
3+
---
4+
15
commit and push
26

37
make sure it includes a prefix like

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

Lines changed: 171 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,48 +3,52 @@ 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. OpenCode supports both:
6+
You can add external tools to OpenCode using the _Model Context Protocol_, or MCP.
7+
8+
OpenCode supports both:
79

810
- Local servers
911
- Remote servers
1012

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

13-
---
14-
15-
## Configure
16-
17-
You can define MCP servers in your OpenCode config under `mcp`.
15+
:::note
16+
OAuth support for MCP servers is coming soon.
17+
:::
1818

1919
---
2020

21-
### Local
21+
## Caveats
2222

23-
Add local MCP servers using `"type": "local"` within the MCP object. Multiple MCP servers can be added.
23+
When you use an MCP server, it adds to the context. This can quickly add up if
24+
you have a lot of tools. So we recommend being careful with which MCP servers
25+
you use.
2426

2527
:::tip
2628
MCP servers add to your context, so you want to be careful with which
2729
ones you enable.
2830
:::
2931

30-
The key string for each server can be any arbitrary name.
32+
Certain MCP servers, like the GitHub MCP server tend to add a lot of tokens and
33+
can easily exceed the context limit.
34+
35+
---
36+
37+
## Configure
38+
39+
You can define MCP servers in your OpenCode config under `mcp`. Add each MCP
40+
with a unique name. You can refer to that MCP by name when prompting the LLM.
3141

32-
```json title="opencode.json" {15}
42+
```jsonc title="opencode.jsonc" {6}
3343
{
3444
"$schema": "https://opencode.ai/config.json",
3545
"mcp": {
36-
"my-local-mcp-server": {
37-
"type": "local",
38-
"command": ["bun", "x", "my-mcp-command"],
39-
"enabled": true,
40-
"environment": {
41-
"MY_ENV_VAR": "my_env_var_value"
42-
}
43-
},
44-
"my-different-local-mcp-server": {
45-
"type": "local",
46-
"command": ["bun", "x", "my-other-mcp-command"],
46+
"name-of-mcp-server": {
47+
// ...
4748
"enabled": true
49+
},
50+
"name-of-other-mcp-server": {
51+
// ...
4852
}
4953
}
5054
}
@@ -54,40 +58,71 @@ You can also disable a server by setting `enabled` to `false`. This is useful if
5458

5559
---
5660

57-
### Remote
61+
### Local
5862

59-
Add remote MCP servers under `mcp` with `"type": "remote"`.
63+
Add local MCP servers using `type` to `"local"` within the MCP object.
6064

61-
```json title="opencode.json"
65+
```jsonc title="opencode.jsonc" {15}
6266
{
6367
"$schema": "https://opencode.ai/config.json",
6468
"mcp": {
65-
"my-remote-mcp": {
66-
"type": "remote",
67-
"url": "https://my-mcp-server.com",
69+
"my-local-mcp-server": {
70+
"type": "local",
71+
// Or ["bun", "x", "my-mcp-command"]
72+
"command": ["npx", "-y", "my-mcp-command"],
6873
"enabled": true,
69-
"headers": {
70-
"Authorization": "Bearer MY_API_KEY"
74+
"environment": {
75+
"MY_ENV_VAR": "my_env_var_value"
7176
}
7277
}
7378
}
7479
}
7580
```
7681

77-
Local and remote servers can be used together within the same `mcp` config object.
82+
The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
7883

79-
```json title="opencode.json"
84+
For example, here's how I can add the test
85+
[`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
86+
87+
```jsonc title="opencode.jsonc"
8088
{
8189
"$schema": "https://opencode.ai/config.json",
8290
"mcp": {
83-
"my-local-mcp-server": {
91+
"mcp_everything": {
8492
"type": "local",
85-
"command": ["bun", "x", "my-mcp-command"],
86-
"enabled": true,
87-
"environment": {
88-
"MY_ENV_VAR": "my_env_var_value"
89-
}
90-
},
93+
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
94+
}
95+
}
96+
}
97+
```
98+
99+
And to use it I can add `use the mcp_everything tool` to my prompts.
100+
101+
```txt "mcp_everything"
102+
use the mcp_everything tool to add the number 3 and 4
103+
```
104+
105+
#### Options
106+
107+
Here are all the options for configuring a local MCP server.
108+
109+
| Option | Type | Required | Description |
110+
| ------------- | ------- | -------- | ----------------------------------------------------- |
111+
| `type` | String | Y | Type of MCP server connection, must be `"local"`. |
112+
| `command` | Array | Y | Command and arguments to run the MCP server. |
113+
| `environment` | Object | | Environment variables to set when running the server. |
114+
| `enabled` | Boolean | | Enable or disable the MCP server on startup. |
115+
116+
---
117+
118+
### Remote
119+
120+
Add remote MCP servers under by setting `type` to `"remote"`.
121+
122+
```json title="opencode.json"
123+
{
124+
"$schema": "https://opencode.ai/config.json",
125+
"mcp": {
91126
"my-remote-mcp": {
92127
"type": "remote",
93128
"url": "https://my-mcp-server.com",
@@ -100,6 +135,17 @@ Local and remote servers can be used together within the same `mcp` config objec
100135
}
101136
```
102137

138+
Here the `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
139+
140+
#### Options
141+
142+
| Option | Type | Required | Description |
143+
| --------- | ------- | -------- | -------------------------------------------------- |
144+
| `type` | String | Y | Type of MCP server connection, must be `"remote"`. |
145+
| `url` | String | Y | URL of the remote MCP server. |
146+
| `enabled` | Boolean | | Enable or disable the MCP server on startup. |
147+
| `headers` | Object | | Headers to send with the request. |
148+
103149
---
104150

105151
## Manage
@@ -197,3 +243,90 @@ The glob pattern uses simple regex globbing patterns.
197243
- `*` matches zero or more of any character
198244
- `?` matches exactly one character
199245
- All other characters match literally
246+
247+
---
248+
249+
## Examples
250+
251+
Below are examples of some common MCP servers. You can submit a PR if you want to document other servers.
252+
253+
---
254+
255+
### Context7
256+
257+
Add the [Context7 MCP server](https://github.com/context-labs/mcp-server-context7) to search through docs.
258+
259+
```json title="opencode.json" {4-7}
260+
{
261+
"$schema": "https://opencode.ai/config.json",
262+
"mcp": {
263+
"context7": {
264+
"type": "remote",
265+
"url": "https://mcp.context7.com/mcp"
266+
}
267+
}
268+
}
269+
```
270+
271+
If you have signed up for a free account, you can use your API key and get higher rate-limits.
272+
273+
```json title="opencode.json" {7-9}
274+
{
275+
"$schema": "https://opencode.ai/config.json",
276+
"mcp": {
277+
"context7": {
278+
"type": "remote",
279+
"url": "https://mcp.context7.com/mcp",
280+
"headers": {
281+
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
282+
}
283+
}
284+
}
285+
}
286+
```
287+
288+
Here we are assuming that you have the `CONTEXT7_API_KEY` environment variable set.
289+
290+
Add `use context7` to your prompts to use Context7 MCP server.
291+
292+
```txt "use context7"
293+
Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
294+
```
295+
296+
Alternatively, you can add something like this to your
297+
[AGENTS.md](/docs/rules/).
298+
299+
```md title="AGENTS.md"
300+
When you need to search docs, use `context7` tools.
301+
```
302+
303+
---
304+
305+
### Grep by Vercel
306+
307+
Add the [Grep by Vercel](https://github.com/vercel/grep-by-vercel) MCP server to search through code snippets on GitHub.
308+
309+
```json title="opencode.json" {4-7}
310+
{
311+
"$schema": "https://opencode.ai/config.json",
312+
"mcp": {
313+
"gh_grep": {
314+
"type": "remote",
315+
"url": "https://mcp.grep.app"
316+
}
317+
}
318+
}
319+
```
320+
321+
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.
322+
323+
```txt "use the gh_grep tool"
324+
What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
325+
```
326+
327+
Alternatively, you can add something like this to your
328+
[AGENTS.md](/docs/rules/).
329+
330+
```md title="AGENTS.md"
331+
If you are unsure how to do something, use `gh_grep` to search code examples from github.
332+
```

0 commit comments

Comments
 (0)