docs: update MCP OAuth documentation (DCR + refresh token)#50
Merged
Conversation
- mcp-api.md: replace outdated 501 stub docs with live OAuth 2.1 flow documentation covering DCR, PKCE, authorization code grant, refresh token grant, and config TTL options - agent-integration.md: add OAuth Dynamic Client Registration section with opencode configuration example - CHANGELOG.md: add entries for #45, #46, #47 under Unreleased Fixes #47
There was a problem hiding this comment.
Pull request overview
Updates the documentation around MCP OAuth support (discovery, DCR, PKCE) and adds corresponding entries to the Unreleased changelog.
Changes:
- Replaces the outdated “501 Not Implemented” OAuth section in
docs/mcp-api.mdwith an OAuth 2.1 + PKCE + DCR walkthrough and endpoint reference. - Adds an “OAuth Dynamic Client Registration” section to
docs/agent-integration.mdwith an opencode configuration example. - Adds Unreleased CHANGELOG entries for issues #45–#47.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 12 comments.
| File | Description |
|---|---|
| docs/mcp-api.md | Rewrites OAuth documentation and examples for MCP discovery/registration/authorize/token. |
| docs/agent-integration.md | Adds OAuth DCR guidance and opencode configuration steps. |
| CHANGELOG.md | Adds Unreleased entries referencing OAuth-related work (#45–#47). |
Comments suppressed due to low confidence (3)
docs/mcp-api.md:176
- The registration response example includes
grant_types: ["authorization_code", "refresh_token"], buthandleOAuthRegistercurrently returns onlyauthorization_code(seeinternal/mcp/serverbootstrap/oauth.go:123-131). The example should match the real response.
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"redirect_uris": ["http://127.0.0.1:4321/callback"]
docs/mcp-api.md:200
- The token exchange response example includes a
refresh_token, buthandleOAuthTokencurrently returns onlyaccess_token,token_type, andexpires_in(internal/mcp/serverbootstrap/oauth.go:269-273). Update the example to reflect the actual payload.
{
"access_token": "a1b2c3d4...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "e5f6a7b8..."
docs/mcp-api.md:208
- This section documents the refresh-token grant and token rotation, but the token endpoint currently rejects any
grant_typeother thanauthorization_codewithunsupported_grant_type(internal/mcp/serverbootstrap/oauth.go:234-236). Please remove/mark as not yet supported until the refresh flow is implemented.
### Token Refresh
```json
POST /mcp/oauth/token
Content-Type: application/x-www-form-urlencoded
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `/.well-known/oauth-authorization-server` | GET | 200 | Authorization server metadata (RFC 8414) | | ||
| | `/mcp/oauth/authorize` | POST | 501 | OAuth authorization stub | | ||
| | `/mcp/oauth/token` | POST | 501 | OAuth token exchange stub | | ||
| | `/oauth/register` | POST | 201 | Dynamic client registration (RFC 7591) | |
Comment on lines
148
to
152
| "response_types_supported": ["code"], | ||
| "code_challenge_methods_supported": ["S256"], | ||
| "token_endpoint_auth_methods_supported": ["none"], | ||
| "grant_types_supported": ["authorization_code", "refresh_token"] | ||
| } |
| } | ||
| ``` | ||
|
|
||
| Client registrations are **persistent** across server restarts (stored in `<vault-dir>/mcp-oauth-clients.json`). |
Comment on lines
+229
to
+237
| OAuth token TTLs are configurable via `config.yaml`: | ||
|
|
||
| ```yaml | ||
| mcp: | ||
| oauth: | ||
| access_token_ttl: 1h # default: 24h | ||
| refresh_token_ttl: 720h # default: 720h (30 days) | ||
| ``` | ||
|
|
Comment on lines
+216
to
+218
| - **DCR (RFC 7591)**: Clients register via `POST /oauth/register` and receive a | ||
| `client_id`. Registrations persist across server restarts. | ||
| - **PKCE (RFC 7636)**: Authorization code flow with S256 code challenge method. |
Comment on lines
+250
to
+257
| Token TTLs can be customized in `config.yaml`: | ||
|
|
||
| ```yaml | ||
| mcp: | ||
| oauth: | ||
| access_token_ttl: 1h # how long access tokens are valid (default: 24h) | ||
| refresh_token_ttl: 720h # how long refresh tokens are valid (default: 30d) | ||
| ``` |
Comment on lines
+263
to
+265
| - **Automatic rotation** — refresh tokens keep connections alive without | ||
| re-authentication | ||
| - **Persistent registration** — survives server restarts |
Comment on lines
+12
to
+14
| - OAuth 2.1 + PKCE + DCR: persistent client registry survives server restarts (#45) | ||
| - OAuth refresh token grant (RFC 6749 §6) with configurable TTLs (#46) | ||
| - Config options `mcp.oauth.access_token_ttl` (default 24h) and `mcp.oauth.refresh_token_ttl` (default 30d) (#46) |
|
|
||
| ### Fixed | ||
|
|
||
| - OAuth error response: `unauthorized_client` → `invalid_client` with `WWW-Authenticate` header (#45) |
| | `/mcp/oauth/authorize` | POST | 501 | OAuth authorization stub | | ||
| | `/mcp/oauth/token` | POST | 501 | OAuth token exchange stub | | ||
| | `/oauth/register` | POST | 201 | Dynamic client registration (RFC 7591) | | ||
| | `/mcp/oauth/authorize` | GET | 302/400 | Authorization request (RFC 6749 §4.1.1) | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #47
What
Describe the change in a few sentences.
Why
Explain the problem, user need, or maintenance reason.
Testing
make fmtmake vetmake lintGOWORK=off go test ./...Safety