docs: document MCP CIMD client registration (#55796)

This commit is contained in:
Aiden Cline
2026-10-15 13:54:15 -05:00
committed by GitHub
Unverified
parent 775d1d0d71
commit d0732eadf8
7 changed files with 143 additions and 24 deletions
@@ -76,9 +76,11 @@ const authenticate = Effect.fn("cli.mcp.auth.run")(function* (name?: string) {
const exampleConfig = `
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp"
"servers": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp"
}
}
}`
@@ -223,6 +223,11 @@ OpenCode adds them to the session's directory for the life of the `opencode acp`
directory can use them. OpenCode passes HTTP headers through and doesn't use OAuth for these servers. It doesn't
advertise MCP over SSE, and it doesn't support MCP over ACP.
| Case | Behavior |
| -------------------------------- | ------------------------------------------------------------------- |
| Same name as a configured server | The client's server replaces the configured one in that directory. |
| [Policies](/policies) | `integration.use` rules still apply. |
```json
{ "type": "http", "name": "docs", "url": "https://mcp.example.com", "headers": [] }
```
+3 -2
View File
@@ -333,8 +333,9 @@ rate limits, and disabling search.
### MCP
Configure local and remote Model Context Protocol servers. Global timeouts can
be overridden by an individual server.
Configure local and remote Model Context Protocol servers. Global
`mcp.timeout` values apply to servers defined in configuration files; each
server's `timeout` overrides them.
```jsonc
{
@@ -66,10 +66,10 @@ The selected agent or provider system prompt is sent first. OpenCode then assemb
```text
1. Agent or provider system prompt
2. Built-in environment and date context
3. Code Mode tool guidance, when enabled
2. Code Mode tool guidance, when enabled
3. MCP server, reference, and skill guidance
4. Global and project AGENTS.md files, then configured instructions
5. Available skill, reference, and MCP guidance
5. Built-in date and environment context
6. Session-specific instruction entries supplied through the API
```
+115 -10
View File
@@ -82,7 +82,13 @@ A local server is a command that OpenCode starts over the MCP stdio transport. A
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
```
Use configuration for process options such as a working directory or environment variables:
Pass environment variables with repeated `--env` flags:
```sh
opencode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything
```
Use configuration for other process options such as a working directory:
```jsonc title="opencode.jsonc"
{
@@ -132,7 +138,13 @@ A remote server uses the MCP Streamable HTTP transport and requires an absolute
opencode mcp add context7 --url https://mcp.context7.com/mcp
```
Use configuration when the server needs headers or other options. Store secrets in environment variables rather than in the file:
Pass request headers with repeated `--header` flags. Quote `{env:NAME}` references so the shell writes them literally:
```sh
opencode mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'
```
Use configuration for other options. Store secrets in environment variables rather than in the file:
```jsonc title="opencode.jsonc"
{
@@ -176,9 +188,9 @@ Use `oauth: false` only when the server exclusively uses an API key or another h
## OAuth
OAuth is enabled for remote servers unless `oauth` is `false`. OpenCode discovers the authorization server, uses PKCE, refreshes tokens, and attempts dynamic client registration when supported; credentials stay outside project configuration.
OAuth is enabled for remote servers unless `oauth` is `false`. OpenCode discovers the authorization server, signs in with PKCE, and refreshes tokens. Credentials are stored outside project configuration.
For dynamic registration, configure only the server URL:
Most servers need only the URL:
```jsonc title="opencode.jsonc"
{
@@ -200,6 +212,38 @@ If the server needs authentication, run `/mcps`, select it, and complete authori
opencode mcp auth sentry
```
### Client registration
OpenCode identifies itself to the authorization server with the first method that applies:
| Method | Used when |
| --- | --- |
| Pre-registered client | `oauth.client_id` is configured. |
| [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents) (CIMD) | The authorization server supports CIMD and public clients, and `oauth.redirect_uri` is not set. |
| [Dynamic client registration](https://datatracker.ietf.org/doc/html/rfc7591) (DCR) | Neither of the above applies. OpenCode registers a client and reuses it on later sign-ins. |
An authorization server opts into CIMD through its metadata:
```json
{
"issuer": "https://auth.example.com",
"client_id_metadata_document_supported": true,
"token_endpoint_auth_methods_supported": ["none"]
}
```
With CIMD, OpenCode sends its metadata document URL as the `client_id` and skips registration:
```text
https://opencode.ai/oauth/opencode/client.json
```
The document allows the loopback redirects `http://127.0.0.1/callback` and `http://localhost/callback` without a port. Authorization servers accept any loopback port for these redirects, as [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) requires, so `callback_port` works with CIMD. A custom `redirect_uri` does not, so OpenCode falls back to DCR.
If the authorization server supports neither CIMD nor DCR, configure a pre-registered client.
### Pre-registered clients
When a provider gives you client credentials, use V2's snake_case OAuth fields:
```jsonc title="opencode.jsonc"
@@ -225,11 +269,11 @@ When a provider gives you client credentials, use V2's snake_case OAuth fields:
| Field | Description |
| --- | --- |
| `client_id` | Pre-registered client ID. Omit it to attempt dynamic registration. |
| `client_secret` | 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 the default. |
| `redirect_uri` | Pre-registered loopback URI whose path and port reach the local callback listener. |
| `client_id` | Pre-registered client ID. Takes priority over CIMD and DCR. |
| `client_secret` | Secret for a confidential client, sent in the token request body. Omit it for public clients. |
| `scope` | Space-delimited scopes to request. Defaults to the scope the server names when it rejects an unauthenticated request. |
| `callback_port` | Local callback port from `1` through `65535`. Defaults to the `redirect_uri` port, then an available ephemeral port. |
| `redirect_uri` | Pre-registered loopback URI whose path and port reach the local callback listener. Setting it disables CIMD. |
| `auth_server_metadata_url` | URL of the authorization server's OAuth or OpenID Connect metadata document. Set it when the MCP server does not publish protected resource metadata that names its authorization server. |
Remove stored OAuth credentials when you need to sign in again or switch accounts:
@@ -313,6 +357,12 @@ MCP prompts become commands named `<server>:<prompt>` with the same normalizatio
/context_7:find_docs
```
Command text fills the prompt's arguments in order. Separate them with spaces and quote values that contain spaces:
```text
/context_7:find_docs react "server components"
```
Choose short server names that remain unique after normalization. Under the default Code Mode, tools are grouped by the normalized server name:
```text
@@ -351,6 +401,55 @@ Use permission actions to hide or deny tools without disconnecting their server.
}
```
## Resources
Agents read MCP resources through two built-in tools, `list_mcp_resources` and `read_mcp_resource`. Control them with these permission actions:
| Action | Resource |
| --- | --- |
| `opencode_list_mcp_resources` | The server name. |
| `opencode_read_mcp_resource` | `<server>:<uri>` |
For example, allow every read from the `docs` server:
```jsonc
{
"permissions": [
{
"action": "opencode_read_mcp_resource",
"resource": "docs:*",
"effect": "allow",
},
],
}
```
## Server instructions
When a server returns instructions during initialization, OpenCode adds them to the system prompt:
```text
<mcp_instructions>
<server name="sentry">
Search for an existing issue before creating a new one.
</server>
</mcp_instructions>
```
For servers that use Code Mode, OpenCode adds a line that says where the agent can find the server's tools.
A server's instructions are omitted when the agent's permissions deny every one of its tools, or when they deny `execute` for a server that uses Code Mode.
## Input requests
Servers can ask for input during a call through MCP elicitation. OpenCode shows the request as a form, or as a link to open for URL requests:
```text
sentry is requesting input
```
Dismissing the form cancels the request.
## Context
For calls made on behalf of a session, OpenCode sends the session ID in `CallToolRequest.params._meta["ai.opencode/sessionID"]`. This applies to direct tools and Code Mode over stdio and Streamable HTTP:
@@ -391,6 +490,12 @@ opencode mcp auth sentry
opencode mcp logout sentry
```
Run `opencode mcp auth` without a name to pick from the OAuth-capable servers:
```sh
opencode mcp auth
```
To remove a server, delete its entry from the project or global configuration where it was added:
```jsonc
@@ -401,7 +506,7 @@ To remove a server, delete its entry from the project or global configuration wh
}
```
Edit configuration directly for OAuth client settings, timeouts, working directories, or persistent enablement:
Disconnecting a server in `/mcps` does not change configuration. Edit configuration directly for OAuth client settings, timeouts, working directories, or to keep a server disconnected:
```jsonc
{
@@ -120,7 +120,9 @@ currently use these actions and resources:
| `websearch` | Search query |
| `external_directory` | Canonical external directory boundary, normally ending in `/*` |
| `<server>_<tool>` | `*` for an MCP tool; unsupported characters in both names become `_` |
| `execute` | `*`; controls Code Mode availability, while nested tools enforce their rules |
| `opencode_list_mcp_resources` | MCP server name |
| `opencode_read_mcp_resource` | `<server>:<uri>` |
| `execute` | `*`; a deny removes Code Mode and the tools reached only through it, while nested tools enforce their rules |
For example, allow one skill and deny all other skills:
+9 -5
View File
@@ -212,10 +212,12 @@ results without adding every intermediate value to the model context.
Read package.json and README.md in parallel, then return their relevant setup details.
```
The runtime has no direct filesystem access, imports, timers, or `fetch`; it can
only call tools in its catalog. Permission `execute` with resource `*` controls
whether Code Mode is available. Nested built-in and MCP tools still enforce
their own permissions, and plugin tools enforce the permissions they assert.
The runtime has no direct filesystem access, imports, or timers. It provides
`fetch` for HTTP requests; everything else goes through tools in its catalog.
Denying `execute` with resource `*` removes Code Mode and every tool reached only
through it, including MCP tools from servers that do not set `codemode: false`.
Nested built-in and MCP tools still enforce their own permissions, and plugin
tools enforce the permissions they assert.
### Sessions
@@ -276,7 +278,9 @@ browser operations do not issue individual permission prompts.
[MCP servers](/mcp-servers) add tools whose names and inputs come from each
connected server. Their permission action is `<server>_<tool>` with resource
`*`. They are not a fixed part of the built-in catalog.
`*`. They are not a fixed part of the built-in catalog. By default, agents reach
them through `execute` under the server's namespace; set `codemode: false` on a
server to list its tools directly.
[Skills](/skills) add task instructions rather than new executable tools.
[Attachments](/attachments) put user-selected content into a prompt, while