MCP in OpenCode: remote servers in opencode.json

The short version: MCP servers in OpenCode are declared in the mcp block of opencode.json. A remote server needs "type": "remote" and a url; sign-in is a key in headers or opencode mcp auth. Below is a ready config plus the thing the short guides leave out: how not to bloat the agent's context with tools.

What MCP gives an agent in the terminal

OpenCode can already read the project, edit files and run commands. MCP adds what lives outside the repository: current library documentation from the web, reading the page that describes an error, generating icons and images for the UI as you go. What MCP is in general is covered in the overview of MCP servers.

Step 1. A key

If you have already pointed OpenCode at our API following "opencode: setting up your own provider", you have a key already: the same key opens the MCP servers too, on one shared balance. If not, get one here, no registration:

Put the key in an environment variable so it never reaches git:

export TWELVER_API_KEY="sk-<your-key>"

Step 2. The mcp block in opencode.json

The global config lives in ~/.config/opencode/opencode.json; the project one is opencode.json at the root of the repository. Add the servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twelver-web-search": {
      "type": "remote",
      "url": "https://twelver.app/api/mcp/v1/web-search",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:TWELVER_API_KEY}"
      }
    },
    "twelver-image": {
      "type": "remote",
      "url": "https://twelver.app/api/mcp/v1/image-generation",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:TWELVER_API_KEY}"
      }
    }
  }
}

Restart OpenCode and check the servers connected:

opencode mcp list

Without a key: OAuth

Remove headers and OpenCode will see that the server wants a sign-in and offer to do it in the browser. You can also start it by hand:

opencode mcp auth twelver-web-search

Signing in over OAuth requires a registered account. If something goes wrong, opencode mcp debug server-name shows which step the sign-in stopped at, and opencode mcp logout clears the stored tokens.

Step 3. Check it in a session

Ask the agent for something that needs a tool:

• "Look up in the documentation how caching headers are configured in the latest Next.js and fix next.config" — the agent will go to web-search, read the page, and only then touch the code.
• "Generate a 1:1 app icon in a flat style and put the link in the README" — that is text-to-image.

How not to overload the agent with tools

Every connected server adds its tool descriptions to every request to the model. That costs tokens and, worse, dilutes the model's attention: with twenty tools available it reaches for the wrong one more often. Three practical rules:

• Keep only what you need everywhere in the global config — usually that is search. Enable image generation in the frontend project's own config.
• Disable rather than delete: "enabled": false leaves the server in the config but does not load it at startup.
• Connect the set that matches the task. Twelver's servers are split into sets for exactly this: search separately, images separately, video separately.

Model and tools on one key

The thing that makes this pairing worth assembling: OpenCode can take both the model (through an OpenAI-compatible provider) and the tools (through MCP) from Twelver — on one key and one balance. The provider is set up in "opencode: setting up your own provider", MCP as above; both blocks live in the same opencode.json.

If it does not work

Not writing code only in the terminal? The same scheme for Codex and Cursor, and a shortlist of what a developer should connect is in the best MCP servers.