MCP servers

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.

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.

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.

{
  "$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.

{
  "$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 MCP server.

{
  "$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.

use the mcp_everything tool to add the number 3 and 4

Options

Here are all the options for configuring a local MCP server.

Remote

Add remote MCP servers under by setting type to "remote".

{
  "$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

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.

{
  "$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.

{
  "$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 enable the MCP server as a tool.

{
  "$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 to search through docs.

{
  "$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.

{
  "$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.

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.

When you need to search docs, use `context7` tools.

Grep by Vercel

Add the Grep by Vercel MCP server to search through code snippets on GitHub.

{
  "$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.

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.

If you are unsure how to do something, use `gh_grep` to search code examples from github.