MCP servers

OpenCode can connect to Model Context Protocol servers and make their tools, prompts, and instructions available to agents. MCP tools consume model context, so enable only the servers you need.

Configure servers

Define each server by a unique name under mcp.servers in your OpenCode configuration. V2 does not place server names directly under mcp.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"],
      },
    },
  },
}

Servers connect automatically unless disabled is true. There is no V2 enabled field.

{
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"],
        "disabled": true,
      },
    },
  },
}

As with other configuration, a server in a higher-precedence project config replaces a server with the same name from a lower-precedence config. Use different names when you need separate connections or accounts.

Local servers

A local server is a command that OpenCode starts using the MCP stdio transport.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
        "cwd": ".",
        "environment": {
          "LOG_LEVEL": "info",
          "MCP_API_KEY": "{env:MCP_API_KEY}",
        },
      },
    },
  },
}

Use {env:NAME} to substitute an environment variable while loading config. Shell expressions such as $NAME are not expanded in JSON strings.

Remote servers

A remote server uses the MCP Streamable HTTP transport. Its url must be a valid absolute URL.

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

Use oauth: false for a server that exclusively uses an API key or another header-based credential.

OAuth

OAuth support is enabled for remote servers unless oauth is false. OpenCode discovers the authorization server, uses PKCE, refreshes tokens, and attempts dynamic client registration when the server supports it. OAuth credentials are stored outside project configuration.

For a server that supports dynamic client registration, only the remote server is required:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "sentry": {
        "type": "remote",
        "url": "https://mcp.sentry.dev/mcp",
      },
    },
  },
}

When a server reports that it needs authentication, start its OAuth flow using an MCP management interface and complete authorization in the browser.

If the provider issued client credentials, configure them using V2’s snake_case field names:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "company-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp",
        "oauth": {
          "client_id": "{env:MCP_CLIENT_ID}",
          "client_secret": "{env:MCP_CLIENT_SECRET}",
          "scope": "tools:read tools:execute",
          "callback_port": 19876,
          "redirect_uri": "http://127.0.0.1:19876/callback",
        },
      },
    },
  },
}

Timeouts

Timeouts are positive integer milliseconds. Configure defaults under mcp.timeout; a server’s timeout fields override matching defaults.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timeout": {
      "startup": 45000,
      "catalog": 30000,
      "execution": 600000,
    },
    "servers": {
      "slow-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp",
        "timeout": {
          "catalog": 60000,
        },
      },
    },
  },
}

Names and permissions

OpenCode combines the server name and MCP tool name as <server>_<tool>. Characters other than letters, numbers, _, and - are replaced with _; for example, server context 7 and tool resolve.library/id become context_7_resolve_library_id. MCP prompts become available as commands named <server>:<prompt> using the same normalization.

Choose short server names that remain unique after normalization. Under the default Code Mode, MCP tools are grouped by the normalized server name.

Set codemode to false on a server when its tools should remain on the provider’s native tool list:

{
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "codemode": false,
      },
    },
  },
}

Use permission actions to hide or deny a server’s tools without stopping its connection:

{
  "permissions": [
    {
      "action": "context7_*",
      "resource": "*",
      "effect": "deny",
    },
  ],
}

Session context

When OpenCode invokes an MCP tool on behalf of a session, it includes the invoking session’s ID in CallToolRequest.params._meta.sessionID. This applies to direct tool calls and Code Mode over both stdio and Streamable HTTP.

The ID is request metadata, not a tool argument, so it does not appear in the model-visible tool schema. Treat it as an opaque correlation value: it identifies the invoking OpenCode session rather than the MCP transport session, can be absent for calls without session context, and must not be used by itself for authentication or authorization. Remote MCP servers receive the raw ID and may log or retain it.

Manage servers

OpenCode interfaces can add servers to project or global configuration, list configured servers and their connection status, authenticate remote servers, and remove stored OAuth credentials. Edit configuration directly for OAuth client settings, timeouts, working directories, or enablement.