You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d0732ea
Browse filesBrowse the repository at this point in the historyBrowse files
Use configuration for other options. Store secrets in environment variables rather than in the file:
136
148
137
149
```jsonc title="opencode.jsonc"
138
150
{
@@ -176,9 +188,9 @@ Use `oauth: false` only when the server exclusively uses an API key or another h
176
188
177
189
## OAuth
178
190
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.
180
192
181
-
For dynamic registration, configure only the server URL:
193
+
Most servers need only the URL:
182
194
183
195
```jsonc title="opencode.jsonc"
184
196
{
@@ -200,6 +212,38 @@ If the server needs authentication, run `/mcps`, select it, and complete authori
200
212
opencode mcp auth sentry
201
213
```
202
214
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:
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
+
203
247
When a provider gives you client credentials, use V2's snake_case OAuth fields:
204
248
205
249
```jsonc title="opencode.jsonc"
@@ -225,11 +269,11 @@ When a provider gives you client credentials, use V2's snake_case OAuth fields:
225
269
226
270
| Field | Description |
227
271
| --- | --- |
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. |
233
277
|`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. |
234
278
235
279
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
313
357
/context_7:find_docs
314
358
```
315
359
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
+
316
366
Choose short server names that remain unique after normalization. Under the default Code Mode, tools are grouped by the normalized server name:
317
367
318
368
```text
@@ -351,6 +401,55 @@ Use permission actions to hide or deny tools without disconnecting their server.
351
401
}
352
402
```
353
403
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
+
354
453
## Context
355
454
356
455
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
391
490
opencode mcp logout sentry
392
491
```
393
492
493
+
Run `opencode mcp auth` without a name to pick from the OAuth-capable servers:
494
+
495
+
```sh
496
+
opencode mcp auth
497
+
```
498
+
394
499
To remove a server, delete its entry from the project or global configuration where it was added:
395
500
396
501
```jsonc
@@ -401,7 +506,7 @@ To remove a server, delete its entry from the project or global configuration wh
401
506
}
402
507
```
403
508
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:
0 commit comments