mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-26 12:14:20 +01:00
3ae75d7031
Co-authored-by: Matt Gillard <matt-github@gillard.biz> Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>
335 lines
8.5 KiB
Plaintext
335 lines
8.5 KiB
Plaintext
---
|
|
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:
|
|
|
|
- Local servers
|
|
- Remote servers
|
|
|
|
Once added, MCP tools are automatically available to the LLM alongside built-in tools.
|
|
|
|
:::note
|
|
OAuth support for MCP servers is coming soon.
|
|
:::
|
|
|
|
---
|
|
|
|
## Caveats
|
|
|
|
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.
|
|
:::
|
|
|
|
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.
|
|
|
|
```jsonc title="opencode.jsonc" {6}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"name-of-mcp-server": {
|
|
// ...
|
|
"enabled": true,
|
|
},
|
|
"name-of-other-mcp-server": {
|
|
// ...
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
You can also disable a server by setting `enabled` to `false`. This is useful if you want to temporarily disable a server without removing it from your config.
|
|
|
|
---
|
|
|
|
### Local
|
|
|
|
Add local MCP servers using `type` to `"local"` within the MCP object.
|
|
|
|
```jsonc title="opencode.jsonc" {15}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-local-mcp-server": {
|
|
"type": "local",
|
|
// 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. |
|
|
| `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
|
|
|
|
---
|
|
|
|
### 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",
|
|
"enabled": true,
|
|
"headers": {
|
|
"Authorization": "Bearer MY_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
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. |
|
|
| `timeout` | Number | | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
|
|
|
|
---
|
|
|
|
## Manage
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
### Global
|
|
|
|
This means that you can enable or disable them globally.
|
|
|
|
```json title="opencode.json" {14}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-mcp-foo": {
|
|
"type": "local",
|
|
"command": ["bun", "x", "my-mcp-command-foo"]
|
|
},
|
|
"my-mcp-bar": {
|
|
"type": "local",
|
|
"command": ["bun", "x", "my-mcp-command-bar"]
|
|
}
|
|
},
|
|
"tools": {
|
|
"my-mcp-foo": false
|
|
}
|
|
}
|
|
```
|
|
|
|
We can also use a glob pattern to disable all matching MCPs.
|
|
|
|
```json title="opencode.json" {14}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-mcp-foo": {
|
|
"type": "local",
|
|
"command": ["bun", "x", "my-mcp-command-foo"]
|
|
},
|
|
"my-mcp-bar": {
|
|
"type": "local",
|
|
"command": ["bun", "x", "my-mcp-command-bar"]
|
|
}
|
|
},
|
|
"tools": {
|
|
"my-mcp*": false
|
|
}
|
|
}
|
|
```
|
|
|
|
Here we are using the glob pattern `my-mcp*` to disable all MCPs.
|
|
|
|
---
|
|
|
|
### Per agent
|
|
|
|
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:
|
|
|
|
1. Disable it as a tool globally.
|
|
2. In your [agent config](/docs/agents#tools) enable the MCP server as a tool.
|
|
|
|
```json title="opencode.json" {11, 14-18}
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {
|
|
"my-mcp": {
|
|
"type": "local",
|
|
"command": ["bun", "x", "my-mcp-command"],
|
|
"enabled": true
|
|
}
|
|
},
|
|
"tools": {
|
|
"my-mcp*": false
|
|
},
|
|
"agent": {
|
|
"my-agent": {
|
|
"tools": {
|
|
"my-mcp*": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
#### Glob patterns
|
|
|
|
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://grep.app) 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.
|
|
```
|