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