mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-19 08:44:22 +01:00
docs: improve MCP server configuration guidance with examples and caveats
This commit is contained in:
Jay V
@@ -1,3 +1,7 @@
|
||||
---
|
||||
description: Git commit and push
|
||||
---
|
||||
|
||||
commit and push
|
||||
|
||||
make sure it includes a prefix like
|
||||
|
||||
@@ -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.
|
||||
|
||||
```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",
|
||||
"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"
|
||||
{
|
||||
"$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"
|
||||
```jsonc title="opencode.jsonc" {15}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"my-local-mcp-server": {
|
||||
"type": "local",
|
||||
"command": ["bun", "x", "my-mcp-command"],
|
||||
// Or ["bun", "x", "my-mcp-command"]
|
||||
"command": ["npx", "-y", "my-mcp-command"],
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"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": {
|
||||
"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.
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user