diff options
| -rw-r--r-- | .opencode/command/commit.md | 4 | ||||
| -rw-r--r-- | packages/web/src/content/docs/mcp-servers.mdx | 209 |
2 files changed, 175 insertions, 38 deletions
diff --git a/.opencode/command/commit.md b/.opencode/command/commit.md index f2038b2a6..9d6dedcd1 100644 --- a/.opencode/command/commit.md +++ b/.opencode/command/commit.md @@ -1,3 +1,7 @@ +--- +description: Git commit and push +--- + commit and push make sure it includes a prefix like diff --git a/packages/web/src/content/docs/mcp-servers.mdx b/packages/web/src/content/docs/mcp-servers.mdx index 535e22839..4dc77b954 100644 --- a/packages/web/src/content/docs/mcp-servers.mdx +++ b/packages/web/src/content/docs/mcp-servers.mdx @@ -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. + +--- + +## 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. -```json title="opencode.json" {15} +```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" +```jsonc title="opencode.jsonc" {15} { "$schema": "https://opencode.ai/config.json", "mcp": { - "my-remote-mcp": { - "type": "remote", - "url": "https://my-mcp-server.com", + "my-local-mcp-server": { + "type": "local", + // Or ["bun", "x", "my-mcp-command"] + "command": ["npx", "-y", "my-mcp-command"], "enabled": true, - "headers": { - "Authorization": "Bearer MY_API_KEY" + "environment": { + "MY_ENV_VAR": "my_env_var_value" } } } } ``` -Local and remote servers can be used together within the same `mcp` config object. +The command is how the local MCP server is started. You can also pass in a list of environment variables as well. -```json title="opencode.json" +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": { - "my-local-mcp-server": { + "mcp_everything": { "type": "local", - "command": ["bun", "x", "my-mcp-command"], - "enabled": true, - "environment": { - "MY_ENV_VAR": "my_env_var_value" - } - }, + "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. +``` |