MCP servers - OpenCode

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.

opencode.jsonc

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

opencode.jsonc

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

Field	Required	Description
`type`	Yes	Must be `"local"`.
`command`	Yes	Executable followed by its arguments.
`cwd`	No	Process working directory. Relative paths resolve from the workspace directory; the workspace is the default.
`environment`	No	String environment variables added to the inherited OpenCode process environment.
`disabled`	No	Set to `true` to prevent the server from connecting. Defaults to `false`.
`codemode`	No	Set to `false` to expose the server’s tools directly to the model instead of through Code Mode. Defaults to `true`.
`timeout`	No	Per-server timeout overrides.

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.

opencode.jsonc

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

Field	Required	Description
`type`	Yes	Must be `"remote"`.
`url`	Yes	Streamable HTTP endpoint.
`headers`	No	String HTTP headers sent to the MCP endpoint.
`oauth`	No	OAuth client settings, or `false` to disable OAuth support.
`disabled`	No	Set to `true` to prevent the server from connecting. Defaults to `false`.
`codemode`	No	Set to `false` to expose the server’s tools directly to the model instead of through Code Mode. Defaults to `true`.
`timeout`	No	Per-server timeout overrides.

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:

opencode.jsonc

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

When the server reports that it needs authentication, run /connect in the TUI:

/connect

Select the MCP server under Services, then complete the browser authorization flow. You can also authenticate from the command line:

opencode2 mcp auth sentry

The CLI command prints the authorization URL and waits for the redirect to OpenCode’s loopback callback server. If the provider issued client credentials, configure them using V2’s snake_case field names:

opencode.jsonc

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

OAuth field	Description
`client_id`	Pre-registered OAuth client ID. If omitted, OpenCode attempts dynamic client registration.
`client_secret`	Client secret for a pre-registered client.
`scope`	Space-delimited scopes to request.
`callback_port`	Local callback port, from `1` through `65535`. An available ephemeral port is used by default.
`redirect_uri`	Pre-registered loopback redirect URI. Its path and port must reach the local callback listener.

Remove stored credentials with:

opencode2 mcp logout sentry

Timeouts

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

opencode.jsonc

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

Timeout	Default	Applies to
`startup`	30 seconds	Establishing the transport and initializing the server.
`catalog`	30 seconds	Listing tools, prompts, resources, and resource templates.
`execution`	12 hours	Calling tools, getting prompts, and reading resources.

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 appear as slash 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"
    }
  ]
}

CLI commands

V2 provides these MCP management commands:

# Add a local server to the project config
opencode2 mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything

# Add a remote server to the project config
opencode2 mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'

# Add to the global config instead
opencode2 mcp add context7 --global --url https://mcp.context7.com/mcp

# List configured servers and connection status
opencode2 mcp list

# Authenticate or remove OAuth credentials
opencode2 mcp auth context7
opencode2 mcp logout context7

mcp add accepts either --url for a remote server or a command after -- for a local server, not both. Use --header NAME=VALUE only with remote servers and --env NAME=VALUE only with local servers. Edit the config directly for OAuth, timeout, working-directory, or enablement settings.

​Configure servers

​Local servers

​Remote servers

​OAuth

​Timeouts

​Names and permissions

​CLI commands

Configure servers

Local servers

Remote servers

OAuth

Timeouts

Names and permissions

CLI commands