aljaz/opencode
1
0
Fork 0
mirror of https://github.com/aljazceru/opencode.git synced 2025-12-19 08:44:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve MCP server configuration guidance with examples and caveats

Browse Source
This commit is contained in:
Jay V
2025-10-14 16:43:48 -04:00
parent d07e79e6ad
commit 7eddaa806d
2 changed files with 181 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.opencode/command/commit.md
View File

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

221
packages/web/src/content/docs/mcp-servers.mdx
View File

@@ -3,48 +3,52 @@ title: MCP servers
description: Add local and remote MCP tools. 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 - Local servers
- Remote servers - Remote servers
Once added, MCP tools are automatically available to the LLM alongside built-in tools. Once added, MCP tools are automatically available to the LLM alongside built-in tools.
--- :::note
OAuth support for MCP servers is coming soon.
## Configure :::
You can define MCP servers in your OpenCode config under `mcp`.
--- ---
### 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 :::tip
MCP servers add to your context, so you want to be careful with which MCP servers add to your context, so you want to be careful with which
ones you enable. 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.
```json title="opencode.json" {15} ---
## 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.
```jsonc title="opencode.jsonc" {6}
{ {
"$schema": "https://opencode.ai/config.json", "$schema": "https://opencode.ai/config.json",
"mcp": { "mcp": {
"my-local-mcp-server": { "name-of-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"],
"enabled": true "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",
"enabled": true,
"headers": {
"Authorization": "Bearer MY_API_KEY"
}
}
}
}
```
Local and remote servers can be used together within the same `mcp` config object.
```json title="opencode.json"
{ {
"$schema": "https://opencode.ai/config.json", "$schema": "https://opencode.ai/config.json",
"mcp": { "mcp": {
"my-local-mcp-server": { "my-local-mcp-server": {
"type": "local", "type": "local",
"command": ["bun", "x", "my-mcp-command"], // Or ["bun", "x", "my-mcp-command"]
"command": ["npx", "-y", "my-mcp-command"],
"enabled": true, "enabled": true,
"environment": { "environment": {
"MY_ENV_VAR": "my_env_var_value" "MY_ENV_VAR": "my_env_var_value"
} }
}, }
}
}
```
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.
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp_everything": {
"type": "local",
"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": { "my-remote-mcp": {
"type": "remote", "type": "remote",
"url": "https://my-mcp-server.com", "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 ## Manage
@@ -197,3 +243,90 @@ The glob pattern uses simple regex globbing patterns.
- `*` matches zero or more of any character - `*` matches zero or more of any character
- `?` matches exactly one character - `?` matches exactly one character
- All other characters match literally - 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.
```