Skip to content

Commit d0732ea

Browse files
authored
docs: document MCP CIMD client registration (#55796)
1 parent 775d1d0 commit d0732ea

7 files changed

Lines changed: 143 additions & 24 deletions

File tree

‎packages/cli/src/commands/handlers/mcp/auth.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,11 @@ const authenticate = Effect.fn("cli.mcp.auth.run")(function* (name?: string) {
7676

7777
const exampleConfig = `
7878
"mcp": {
79-
"my-server": {
80-
"type": "remote",
81-
"url": "https://example.com/mcp"
79+
"servers": {
80+
"my-server": {
81+
"type": "remote",
82+
"url": "https://example.com/mcp"
83+
}
8284
}
8385
}`
8486

‎services/www/src/docs/content/cli/acp.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,11 @@ OpenCode adds them to the session's directory for the life of the `opencode acp`
223223
directory can use them. OpenCode passes HTTP headers through and doesn't use OAuth for these servers. It doesn't
224224
advertise MCP over SSE, and it doesn't support MCP over ACP.
225225

226+
| Case | Behavior |
227+
| -------------------------------- | ------------------------------------------------------------------- |
228+
| Same name as a configured server | The client's server replaces the configured one in that directory. |
229+
| [Policies](/policies) | `integration.use` rules still apply. |
230+
226231
```json
227232
{ "type": "http", "name": "docs", "url": "https://mcp.example.com", "headers": [] }
228233
```

‎services/www/src/docs/content/config.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -333,8 +333,9 @@ rate limits, and disabling search.
333333

334334
### MCP
335335

336-
Configure local and remote Model Context Protocol servers. Global timeouts can
337-
be overridden by an individual server.
336+
Configure local and remote Model Context Protocol servers. Global
337+
`mcp.timeout` values apply to servers defined in configuration files; each
338+
server's `timeout` overrides them.
338339

339340
```jsonc
340341
{

‎services/www/src/docs/content/instructions.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,10 @@ The selected agent or provider system prompt is sent first. OpenCode then assemb
6666

6767
```text
6868
1. Agent or provider system prompt
69-
2. Built-in environment and date context
70-
3. Code Mode tool guidance, when enabled
69+
2. Code Mode tool guidance, when enabled
70+
3. MCP server, reference, and skill guidance
7171
4. Global and project AGENTS.md files, then configured instructions
72-
5. Available skill, reference, and MCP guidance
72+
5. Built-in date and environment context
7373
6. Session-specific instruction entries supplied through the API
7474
```
7575

‎services/www/src/docs/content/mcp-servers.mdx‎

Lines changed: 115 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,13 @@ A local server is a command that OpenCode starts over the MCP stdio transport. A
8282
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
8383
```
8484

85-
Use configuration for process options such as a working directory or environment variables:
85+
Pass environment variables with repeated `--env` flags:
86+
87+
```sh
88+
opencode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything
89+
```
90+
91+
Use configuration for other process options such as a working directory:
8692

8793
```jsonc title="opencode.jsonc"
8894
{
@@ -132,7 +138,13 @@ A remote server uses the MCP Streamable HTTP transport and requires an absolute
132138
opencode mcp add context7 --url https://mcp.context7.com/mcp
133139
```
134140

135-
Use configuration when the server needs headers or other options. Store secrets in environment variables rather than in the file:
141+
Pass request headers with repeated `--header` flags. Quote `{env:NAME}` references so the shell writes them literally:
142+
143+
```sh
144+
opencode mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'
145+
```
146+
147+
Use configuration for other options. Store secrets in environment variables rather than in the file:
136148

137149
```jsonc title="opencode.jsonc"
138150
{
@@ -176,9 +188,9 @@ Use `oauth: false` only when the server exclusively uses an API key or another h
176188

177189
## OAuth
178190

179-
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.
191+
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.
180192

181-
For dynamic registration, configure only the server URL:
193+
Most servers need only the URL:
182194

183195
```jsonc title="opencode.jsonc"
184196
{
@@ -200,6 +212,38 @@ If the server needs authentication, run `/mcps`, select it, and complete authori
200212
opencode mcp auth sentry
201213
```
202214

215+
### Client registration
216+
217+
OpenCode identifies itself to the authorization server with the first method that applies:
218+
219+
| Method | Used when |
220+
| --- | --- |
221+
| Pre-registered client | `oauth.client_id` is configured. |
222+
| [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. |
223+
| [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. |
224+
225+
An authorization server opts into CIMD through its metadata:
226+
227+
```json
228+
{
229+
"issuer": "https://auth.example.com",
230+
"client_id_metadata_document_supported": true,
231+
"token_endpoint_auth_methods_supported": ["none"]
232+
}
233+
```
234+
235+
With CIMD, OpenCode sends its metadata document URL as the `client_id` and skips registration:
236+
237+
```text
238+
https://opencode.ai/oauth/opencode/client.json
239+
```
240+
241+
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.
242+
243+
If the authorization server supports neither CIMD nor DCR, configure a pre-registered client.
244+
245+
### Pre-registered clients
246+
203247
When a provider gives you client credentials, use V2's snake_case OAuth fields:
204248

205249
```jsonc title="opencode.jsonc"
@@ -225,11 +269,11 @@ When a provider gives you client credentials, use V2's snake_case OAuth fields:
225269

226270
| Field | Description |
227271
| --- | --- |
228-
| `client_id` | Pre-registered client ID. Omit it to attempt dynamic registration. |
229-
| `client_secret` | Secret for a pre-registered client. |
230-
| `scope` | Space-delimited scopes to request. |
231-
| `callback_port` | Local callback port from `1` through `65535`. An available ephemeral port is the default. |
232-
| `redirect_uri` | Pre-registered loopback URI whose path and port reach the local callback listener. |
272+
| `client_id` | Pre-registered client ID. Takes priority over CIMD and DCR. |
273+
| `client_secret` | Secret for a confidential client, sent in the token request body. Omit it for public clients. |
274+
| `scope` | Space-delimited scopes to request. Defaults to the scope the server names when it rejects an unauthenticated request. |
275+
| `callback_port` | Local callback port from `1` through `65535`. Defaults to the `redirect_uri` port, then an available ephemeral port. |
276+
| `redirect_uri` | Pre-registered loopback URI whose path and port reach the local callback listener. Setting it disables CIMD. |
233277
| `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. |
234278

235279
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
313357
/context_7:find_docs
314358
```
315359

360+
Command text fills the prompt's arguments in order. Separate them with spaces and quote values that contain spaces:
361+
362+
```text
363+
/context_7:find_docs react "server components"
364+
```
365+
316366
Choose short server names that remain unique after normalization. Under the default Code Mode, tools are grouped by the normalized server name:
317367

318368
```text
@@ -351,6 +401,55 @@ Use permission actions to hide or deny tools without disconnecting their server.
351401
}
352402
```
353403

404+
## Resources
405+
406+
Agents read MCP resources through two built-in tools, `list_mcp_resources` and `read_mcp_resource`. Control them with these permission actions:
407+
408+
| Action | Resource |
409+
| --- | --- |
410+
| `opencode_list_mcp_resources` | The server name. |
411+
| `opencode_read_mcp_resource` | `<server>:<uri>` |
412+
413+
For example, allow every read from the `docs` server:
414+
415+
```jsonc
416+
{
417+
"permissions": [
418+
{
419+
"action": "opencode_read_mcp_resource",
420+
"resource": "docs:*",
421+
"effect": "allow",
422+
},
423+
],
424+
}
425+
```
426+
427+
## Server instructions
428+
429+
When a server returns instructions during initialization, OpenCode adds them to the system prompt:
430+
431+
```text
432+
<mcp_instructions>
433+
<server name="sentry">
434+
Search for an existing issue before creating a new one.
435+
</server>
436+
</mcp_instructions>
437+
```
438+
439+
For servers that use Code Mode, OpenCode adds a line that says where the agent can find the server's tools.
440+
441+
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.
442+
443+
## Input requests
444+
445+
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:
446+
447+
```text
448+
sentry is requesting input
449+
```
450+
451+
Dismissing the form cancels the request.
452+
354453
## Context
355454

356455
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
391490
opencode mcp logout sentry
392491
```
393492

493+
Run `opencode mcp auth` without a name to pick from the OAuth-capable servers:
494+
495+
```sh
496+
opencode mcp auth
497+
```
498+
394499
To remove a server, delete its entry from the project or global configuration where it was added:
395500

396501
```jsonc
@@ -401,7 +506,7 @@ To remove a server, delete its entry from the project or global configuration wh
401506
}
402507
```
403508

404-
Edit configuration directly for OAuth client settings, timeouts, working directories, or persistent enablement:
509+
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:
405510

406511
```jsonc
407512
{

‎services/www/src/docs/content/permissions.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,9 @@ currently use these actions and resources:
120120
| `websearch` | Search query |
121121
| `external_directory` | Canonical external directory boundary, normally ending in `/*` |
122122
| `<server>_<tool>` | `*` for an MCP tool; unsupported characters in both names become `_` |
123-
| `execute` | `*`; controls Code Mode availability, while nested tools enforce their rules |
123+
| `opencode_list_mcp_resources` | MCP server name |
124+
| `opencode_read_mcp_resource` | `<server>:<uri>` |
125+
| `execute` | `*`; a deny removes Code Mode and the tools reached only through it, while nested tools enforce their rules |
124126

125127
For example, allow one skill and deny all other skills:
126128

‎services/www/src/docs/content/tools.mdx‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -212,10 +212,12 @@ results without adding every intermediate value to the model context.
212212
Read package.json and README.md in parallel, then return their relevant setup details.
213213
```
214214

215-
The runtime has no direct filesystem access, imports, timers, or `fetch`; it can
216-
only call tools in its catalog. Permission `execute` with resource `*` controls
217-
whether Code Mode is available. Nested built-in and MCP tools still enforce
218-
their own permissions, and plugin tools enforce the permissions they assert.
215+
The runtime has no direct filesystem access, imports, or timers. It provides
216+
`fetch` for HTTP requests; everything else goes through tools in its catalog.
217+
Denying `execute` with resource `*` removes Code Mode and every tool reached only
218+
through it, including MCP tools from servers that do not set `codemode: false`.
219+
Nested built-in and MCP tools still enforce their own permissions, and plugin
220+
tools enforce the permissions they assert.
219221

220222
### Sessions
221223

@@ -276,7 +278,9 @@ browser operations do not issue individual permission prompts.
276278

277279
[MCP servers](/mcp-servers) add tools whose names and inputs come from each
278280
connected server. Their permission action is `<server>_<tool>` with resource
279-
`*`. They are not a fixed part of the built-in catalog.
281+
`*`. They are not a fixed part of the built-in catalog. By default, agents reach
282+
them through `execute` under the server's namespace; set `codemode: false` on a
283+
server to list its tools directly.
280284

281285
[Skills](/skills) add task instructions rather than new executable tools.
282286
[Attachments](/attachments) put user-selected content into a prompt, while

0 commit comments

Comments
 (0)