> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Configure Model Context Protocol servers to add external tools to OpenCode

## Overview

MCP (Model Context Protocol) servers add external tools to OpenCode. Configure local command-based servers or remote HTTP servers with optional OAuth authentication.

## Local MCP Server

```jsonc theme={null}
{
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      },
      "timeout": 5000
    }
  }
}
```

### Local Server Options

| Option        | Type      | Required | Description                   |
| ------------- | --------- | -------- | ----------------------------- |
| `type`        | `"local"` | Yes      | Server type                   |
| `command`     | string\[] | Yes      | Command to run                |
| `environment` | object    | No       | Environment variables         |
| `enabled`     | boolean   | No       | Enable on startup             |
| `timeout`     | number    | No       | Timeout in ms (default: 5000) |

## Remote MCP Server

```jsonc theme={null}
{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:API_KEY}"
      }
    }
  }
}
```

### Remote Server Options

| Option    | Type           | Required | Description                   |
| --------- | -------------- | -------- | ----------------------------- |
| `type`    | `"remote"`     | Yes      | Server type                   |
| `url`     | string         | Yes      | Server URL                    |
| `headers` | object         | No       | HTTP headers                  |
| `oauth`   | object / false | No       | OAuth config or disable       |
| `enabled` | boolean        | No       | Enable on startup             |
| `timeout` | number         | No       | Timeout in ms (default: 5000) |

## OAuth Configuration

```jsonc theme={null}
{
  "mcp": {
    "oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MCP_CLIENT_ID}",
        "clientSecret": "{env:MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}
```

| Option         | Type    | Description                                                            |
| -------------- | ------- | ---------------------------------------------------------------------- |
| `clientId`     | string  | OAuth client ID; dynamic client registration is attempted when omitted |
| `clientSecret` | string  | OAuth client secret, when required by the authorization server         |
| `scope`        | string  | Space-delimited OAuth scopes requested during authorization            |
| `callbackPort` | integer | Local callback port from 1–65535; defaults to 19876                    |
| `redirectUri`  | string  | Full redirect URI; takes precedence over `callbackPort`                |

## Per-Agent MCP Tools

Restrict MCP tools to specific agents:

```jsonc theme={null}
{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"]
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "researcher": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}
```

This disables MCP tools globally but enables them only for the `researcher` agent.

## Registry Shorthand

In registry component manifests, remote MCP servers use URL shorthand:

```jsonc theme={null}
"opencode": {
  "mcp": {
    "context7": "https://mcp.context7.com/mcp"
  }
}
```

This expands to `{ "type": "remote", "url": "https://...", "enabled": true }`.

## See Also

* [Plugin Development](/docs/reference/plugins) — Build plugins with embedded tools.
* [Custom Tools](/docs/reference/tools) — Custom tool implementations.
* [Permissions](/docs/reference/permissions) — Tool access control.