From d0732eadf883bdc64c0b0ea91e9c4ee0fe51d8c3 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Thu, 15 Oct 2026 13:54:15 -0500 Subject: [PATCH] docs: document MCP CIMD client registration (#55796) --- .../cli/src/commands/handlers/mcp/auth.ts | 8 +- services/www/src/docs/content/cli/acp.mdx | 5 + services/www/src/docs/content/config.mdx | 5 +- .../www/src/docs/content/instructions.mdx | 6 +- services/www/src/docs/content/mcp-servers.mdx | 125 ++++++++++++++++-- services/www/src/docs/content/permissions.mdx | 4 +- services/www/src/docs/content/tools.mdx | 14 +- 7 files changed, 143 insertions(+), 24 deletions(-) diff --git a/packages/cli/src/commands/handlers/mcp/auth.ts b/packages/cli/src/commands/handlers/mcp/auth.ts index 77fe7bfb637..34402379375 100644 --- a/packages/cli/src/commands/handlers/mcp/auth.ts +++ b/packages/cli/src/commands/handlers/mcp/auth.ts @@ -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" + } } }` diff --git a/services/www/src/docs/content/cli/acp.mdx b/services/www/src/docs/content/cli/acp.mdx index d43cee4d1b9..7caf9cb97e7 100644 --- a/services/www/src/docs/content/cli/acp.mdx +++ b/services/www/src/docs/content/cli/acp.mdx @@ -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": [] } ``` diff --git a/services/www/src/docs/content/config.mdx b/services/www/src/docs/content/config.mdx index 70b66e3c93b..fbe8b1a2d6d 100644 --- a/services/www/src/docs/content/config.mdx +++ b/services/www/src/docs/content/config.mdx @@ -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 { diff --git a/services/www/src/docs/content/instructions.mdx b/services/www/src/docs/content/instructions.mdx index 516f3f7f981..1161e4e7577 100644 --- a/services/www/src/docs/content/instructions.mdx +++ b/services/www/src/docs/content/instructions.mdx @@ -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 ``` diff --git a/services/www/src/docs/content/mcp-servers.mdx b/services/www/src/docs/content/mcp-servers.mdx index 4951db4ff3b..0d50c913627 100644 --- a/services/www/src/docs/content/mcp-servers.mdx +++ b/services/www/src/docs/content/mcp-servers.mdx @@ -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 `:` 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` | `:` | + +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 + + + Search for an existing issue before creating a new one. + + +``` + +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 { diff --git a/services/www/src/docs/content/permissions.mdx b/services/www/src/docs/content/permissions.mdx index 7d4192532f4..d2a0fead14a 100644 --- a/services/www/src/docs/content/permissions.mdx +++ b/services/www/src/docs/content/permissions.mdx @@ -120,7 +120,9 @@ currently use these actions and resources: | `websearch` | Search query | | `external_directory` | Canonical external directory boundary, normally ending in `/*` | | `_` | `*` 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` | `:` | +| `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: diff --git a/services/www/src/docs/content/tools.mdx b/services/www/src/docs/content/tools.mdx index 5cde00bf60a..7b11e511af1 100644 --- a/services/www/src/docs/content/tools.mdx +++ b/services/www/src/docs/content/tools.mdx @@ -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 `_` 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