MCP in opencode: connecting local and remote servers

MCP lets you give an agent access to external tools: an error tracker, documentation, a database, a design system. In opencode, connecting MCP takes one block in the config, but there are nuances: two server types, authentication, and above all that every connected tool lands in the model context and costs money. Here is how to connect opencode mcp servers properly.

All parameters were checked against the MCP servers section of opencode.ai/docs as of October 18, 2026. If your version differs, take key names from there.

How opencode understands MCP

Servers are declared in opencode.json in the mcp block. The key is a unique server name, and you can refer to the server by that name in a prompt. Once connected, the server's tools are available to the model alongside the built-in ones. To disable a server without deleting it, set "enabled": false.

There are two server types: local (opencode starts the process on your machine) and remote (the server already runs at an address, and opencode reaches it over the network).

A local server

The local type requires command, an array of the command and its arguments:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      }
    }
  }
}

Other parameters from the docs: cwd (the process working directory, with relative paths resolved from the workspace), environment (environment variables) and timeout (milliseconds allowed to fetch the tool list, 5000 by default). If a server starts slowly, for instance npx downloads the package on first run, raise timeout, otherwise the tools will not register in time.

To check, just ask in chat, as in the docs example: use the mcp_everything tool to add the number 3 and 4. The server name in the prompt hints to the model which tools to use.

A remote server

For remote, url is required. If the server needs a header, add headers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

A value via {env:NAME} is read from the environment, so the secret never lands in a file you commit to git. It is the same trick as for the model key.

OAuth

If a server requires OAuth, opencode handles the 401 response itself and starts the authorization flow, and with dynamic client registration (RFC 7591) nothing else needs configuring. For pre-registered clients, credentials go in the oauth block. You can start authorization manually:

opencode mcp auth sentry

The docs example with Sentry: "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {}. After authorizing, Sentry tools are available in prompts: "show the latest unresolved issues, use sentry".

Figma and other MCP servers

The query "opencode figma mcp" is common, but there is no universal recipe here. Figma has its own MCP instructions, and in opencode it is the same mcp block: either remote with an address or local with a launch command, depending on which server variant you use. Take exact addresses, tool names and plan requirements from Figma's documentation; we do not repeat them here so as not to mislead you. The same principle works for any server that has instructions for MCP clients.

Limit a server to a specific agent

The docs warn plainly: MCP servers add tools to the context, and some, such as the GitHub MCP, can nearly fill it. So with many servers it is worth enabling them per agent:

1. Disable the server for everyone with a name pattern in tools.
2. Enable it again in the definition of the agent that needs it.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  },
  "tools": { "sentry*": false },
  "agent": {
    "triage": {
      "description": "Triages errors from Sentry",
      "mode": "subagent",
      "tools": { "sentry*": true }
    }
  }
}

MCP tools are registered with a prefix from the server name. The pattern sentry* disables or enables all of them at once, and sentry_* is more precise. In the agents section the docs note that tools is deprecated in favor of permission, and wildcard names work there too: for example "sentry_*": "deny". If you are unsure which your version supports, check the Agents section.

What extra tools cost

Tool descriptions are sent to the model on every request. Take an illustrative number: say the connected servers add 15,000 tokens of descriptions and a session makes 40 requests. That is 15,000 × 40 = 600,000 input tokens for descriptions alone.

Zukko prices on October 18, 2026 for claude-sonnet-5 ($ per 1M tokens): input 0.4, cache read 0.05.

• Without cache: 0.6 × 0.4 = $0.24.
• If the descriptions are read from cache (Anthropic format): 0.6 × 0.05 = $0.03, plus a one-time cache write.

The 15,000 figure is an illustration, not a measurement: the real size depends on the servers. You can find it by comparing the spend of the same short task with and without the server. The gateway sees the cache when Claude is connected as the anthropic provider with the address https://api.zukko.pro/v1, as described in the opencode documentation↗. In the OpenAI format, all Claude input is billed at the input price.

If tools do not appear

• Check timeout and that the command runs in a regular terminal.
• Make sure enabled is not false and that a pattern in tools does not block the server globally.
• For remote servers, check headers and OAuth.
• The selected model must be able to call tools. If the agent says it sees neither files nor tools, read the article on tool calling↗.
• A 404 on the model request itself is a provider matter, not MCP: in opencode the Zukko address must be https://api.zukko.pro/v1.

Security separately. The model reads everything an MCP server returns as text: a ticket or a page may contain an instruction addressed to the agent. Give servers minimal rights, do not enable auto-approval for dangerous actions, and keep keys in the environment. Create a separate key for the model itself on the API keys page↗ with a daily limit.

FAQ

Where does the config live, globally or per project?

Both. Global: ~/.config/opencode/opencode.json, project: opencode.json in the root. The project file has priority and values are merged, so shared servers can stay global.

How many servers can I connect?

We do not know a technical limit, but each one adds tools to the context and to the spend. Connect only what you use, and enable servers per agent.

How do I connect a local Python server?

Type local, with the command in an array, for example ["python", "/path/server.py"]. Pass environment variables through environment.

How is MCP different from function calling in a model?

Function calling is the model's ability to ask for a tool to be run. MCP is a standard for plugging a set of tools in from outside. More in MCP server: what it is and how to connect it↗.