Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions docs/configuration/upstream-servers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>`, 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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/features/oauth-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down
2 changes: 1 addition & 1 deletion docs/mcp-go-oauth.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
Loading