From b96ff4cb0bb308c1022285b3e8da2607a8d3f4dd Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Thu, 27 Aug 2026 13:37:48 +0300 Subject: [PATCH] docs(oauth): document the callback-port pin on the published site page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `redirect_uri` pin was documented only in `docs/configuration.md`, which is not in the Docusaurus include list, so the link added in #1070 resolved to nothing and broke the docs build on main. Move the guidance to `configuration/upstream-servers.md`, which is the per-server page the site actually publishes, and point both links at it. Verified with a local `npm run build` — no broken links. --- docs/configuration/upstream-servers.md | 37 ++++++++++++++++++++++++++ docs/features/oauth-authentication.md | 2 +- docs/mcp-go-oauth.md | 2 +- 3 files changed, 39 insertions(+), 2 deletions(-) diff --git a/docs/configuration/upstream-servers.md b/docs/configuration/upstream-servers.md index fa018fcdf..722946c18 100644 --- a/docs/configuration/upstream-servers.md +++ b/docs/configuration/upstream-servers.md @@ -59,6 +59,43 @@ Servers requiring OAuth 2.1 authentication: } ``` +#### Pinning the callback port with `redirect_uri` + +By default mcpproxy asks the OS for a free loopback port on the first OAuth +login, then persists that port and reuses it. If the saved port is taken next +time, a different one is allocated — so the callback URL is not guaranteed to +stay put. + +Some providers require the port to match the registered callback URL exactly. +GitHub OAuth Apps are the common case: even with GitHub's wildcard matching +enabled, that matching covers subdomains and subdirectory paths — the host and +port must still match exactly. Set `redirect_uri` to pin it: + +```json +{ + "oauth": { + "client_id": "Iv1.abc123", + "redirect_uri": "http://127.0.0.1:54108/oauth/callback" + } +} +``` + +mcpproxy binds that exact port and sends that exact string to the provider. +Register the identical URL with the provider. + +The value must be an RFC 8252 loopback redirect: `http` scheme, a loopback host, +an explicit port, and the `/oauth/callback` path. Prefer `127.0.0.1`; +`localhost` is accepted but the listener binds `127.0.0.1`, while +`http://[::1]:PORT/oauth/callback` binds the IPv6 loopback. + +A malformed value, or a pinned port already in use, fails the login with an +error that names `oauth.redirect_uri` — in the connection error and the +server's `health.detail`, in `mcpproxy upstream logs `, and in the main +log. The write surfaces (REST config API, Web UI, the `upstream_servers` MCP +tool) reject a bad value up front; hand-editing `mcp_config.json` bypasses that +by design, so a bad value already on disk is reported at connect time rather +than stopping the daemon from booting. + ## Configuration Options | Option | Type | Required | Description | diff --git a/docs/features/oauth-authentication.md b/docs/features/oauth-authentication.md index 0adeaae9b..e9ecb990a 100644 --- a/docs/features/oauth-authentication.md +++ b/docs/features/oauth-authentication.md @@ -46,7 +46,7 @@ OAuth authentication is used when connecting to MCP servers that require authori |--------|------|-------------| | `client_id` | string | OAuth client identifier (uses Dynamic Client Registration if empty) | | `client_secret` | string | OAuth client secret (optional, can reference secure storage) | -| `redirect_uri` | string | Pins the loopback callback URL. Must be `http`, a loopback host, an explicit port and the `/oauth/callback` path (e.g. `http://127.0.0.1:54108/oauth/callback`); register the identical URL with the provider. Omit it to let mcpproxy allocate a port and persist it. See [Pinning the callback port](../configuration.md#pinning-the-callback-port-with-redirect_uri). | +| `redirect_uri` | string | Pins the loopback callback URL. Must be `http`, a loopback host, an explicit port and the `/oauth/callback` path (e.g. `http://127.0.0.1:54108/oauth/callback`); register the identical URL with the provider. Omit it to let mcpproxy allocate a port and persist it. See [Pinning the callback port](../configuration/upstream-servers.md#pinning-the-callback-port-with-redirect_uri). | | `scopes` | array | Requested OAuth scopes | | `pkce_enabled` | boolean | PKCE is always enabled for security; this flag is currently ignored | | `extra_params` | object | Additional authorization parameters (e.g., RFC 8707 resource) | diff --git a/docs/mcp-go-oauth.md b/docs/mcp-go-oauth.md index 11b2ffee9..3ab7a829e 100644 --- a/docs/mcp-go-oauth.md +++ b/docs/mcp-go-oauth.md @@ -213,7 +213,7 @@ This enables runtime onboarding of AI agents. the host and port must still match the registered callback exactly, and `http://127.0.0.1:*` is not valid syntax there. For those, pin the port with the per-server `oauth.redirect_uri` setting and register that exact string with the provider. - See [Pinning the callback port](configuration.md#pinning-the-callback-port-with-redirect_uri). + See [Pinning the callback port](configuration/upstream-servers.md#pinning-the-callback-port-with-redirect_uri). - Use Cloudflare Workers for fixed-domain callbacks. **Go Code** (authorization-server side, only for servers that permit wildcards):