mcp_toolkit 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9e89469906c5d75ea46174ecf1e7368ffbe93669ec80526e559f683c778516b
-  data.tar.gz: 6c97881a9edbd3df1185069364c99457e90fecb4ecf95a7a6c85612e9f5d0d2e
+  metadata.gz: af5e847538e7fe188e7fb0b0b509f0f430d2c3d33c84fa21350e30367a409578
+  data.tar.gz: dc3233698fd64947b42330fe51bd230e249f37e9044d303eaf1915ea213e1695
 SHA512:
-  metadata.gz: 21daf10ed0e045d978a698482d87581222994cb3ba7aba15f6252f236b5d102bb71a27c29e6d0f05f2e762889fd3dbc8fb58fb3ca5c8293870b46d81145bf540
-  data.tar.gz: 96ddb6e0fb9c72353b17d725a171b6c065537cabb55b8d9f3d208d6bad71bf76291c5394678dedba38e742474d6351234bef6d56240fff0dd9ed5649ce465196
+  metadata.gz: a1fc3088f0a6532ed7a52e7cf13e13ce372edbdcddd61f255fd93cb28df6c0c5fe3a3c17ef98cedf8c5a3be5f8c72d58f8f9bdbc28eac1e7b5ae3308a83cd21f
+  data.tar.gz: fb9a05e81f3895dc89d65dc45a33deef371387d8ba14bf223454f666b8bdeb9c828876a66ba9f6c54b19019b416cd88dc6c66dd5ab562fdc577d1b5148872aae

data/CHANGELOG.md

@@ -1,3 +1,242 @@
+## [0.6.1] - 2026-07-20
+
+Two additive fixes for hosted MCP clients whose OAuth setup could not complete
+against the 0.6.0 bridge: it now answers the metadata documents at the path-APPENDED
+discovery locations as well as the RFC 8414 path-inserted ones, and its Dynamic
+Client Registration response now states the registration (per RFC 7591) instead of
+returning a bare `client_id`. Both are bridge-gated and change nothing for a host
+with the bridge off, or for a client that already worked.
+
+### Fixed
+
+- **Authorization-server discovery for clients that path-APPEND the well-known
+  segment.** For an MCP endpoint at `https://host/mcp`, the issuer is path-ful,
+  and RFC 8414 §3.1 places its metadata at the path-INSERTED
+  `/.well-known/oauth-authorization-server/mcp` — which the bridge already served.
+  But some MCP clients (observed with a hosted client in the wild) instead request
+  the path-APPENDED `https://host/mcp/.well-known/oauth-authorization-server`, got
+  a 404 with no fallback, never obtained a `registration_endpoint`, and reported a
+  registration failure. The bridge now answers the metadata at BOTH forms.
+
+- **Dynamic Client Registration response now states the registration.** The stub
+  returned only a `client_id`. A strict client validates that the `redirect_uris`
+  it registered come back and abandons a registration that drops them — a plausible
+  cause of the same "couldn't register" failure, independent of the discovery gap
+  above. `register` now returns the client's `redirect_uris` and `client_name`
+  alongside `client_id_issued_at` (RFC 7591 §3.2.1). Echoing a `redirect_uri`
+  AUTHORIZES nothing: the bridge still stores no client, and `authorize`/`token`
+  check every one against the host allowlist independently, so a value reflected
+  here is not thereby permitted.
+
+  The `token_endpoint_auth_method` and the grant/response types are **substituted,
+  not echoed** — RFC 7591 §3.2.1 states the metadata as REGISTERED and lets a server
+  replace what it does not support. Reflecting the client's request would contradict
+  the discovery document that named this endpoint (`token_endpoint_auth_methods_supported:
+  ["none"]`, `grant_types_supported: ["authorization_code"]`) and promise a flow the
+  token endpoint rejects — a reflected `refresh_token` is a refresh answered
+  `unsupported_grant_type`. The supported sets are now named once and shared by both
+  documents, so they cannot drift apart.
+
+### Added
+
+- **Path-appended metadata routes under the engine mount** (drawn only when
+  `oauth_bridge?`): `GET <mcp>/.well-known/oauth-authorization-server`,
+  `GET <mcp>/.well-known/oauth-protected-resource`, and the OIDC discovery alias
+  `GET <mcp>/.well-known/openid-configuration` (which returns the
+  authorization-server document). All stay UNDER the mount, so they claim nothing
+  origin-global and cannot collide with an OAuth provider the host already runs;
+  the RFC 8414 path-inserted documents the host draws at the origin root are
+  unchanged. Every identifier is still derived from the live request origin, so
+  the document served at an appended location is byte-identical to the inserted
+  one, and both carry `Cache-Control: no-store`.
+
+## [0.6.0] - 2026-07-16
+
+An OAuth 2.1 authorization bridge for the authority role, so hosted MCP clients
+that will only authenticate by discovering an authorization server and running a
+browser flow can reach a server whose tokens are issued out-of-band. Additive and
+opt-in: a host that configures nothing behaves exactly as it did on 0.5.0.
+
+### Added
+
+- **OAuth authorization bridge (authority-only, opt-in).** A standards-shaped
+  envelope around the tokens a host ALREADY issues — not an identity provider. Its
+  authorization page asks an operator to paste an existing access token, and the
+  `access_token` it returns IS that token, verified through the same
+  `config.token_authenticator` the transport uses. Scopes, expiry, revocation and
+  tenancy stay entirely with the host; the bridge widens nobody's reach.
+
+  Deliberately not implemented, because none of it gates anything here: client
+  registration returns an identifier and stores nothing (no endpoint reads a
+  `client_id`); there is no consent step (pasting a token you already hold is the
+  grant); no refresh token is issued (the pasted token's own expiry is the real
+  lifetime, so a client re-runs the flow rather than refreshing a shadow of it).
+
+  Deliberately NOT mocked, because faking either would create a real vulnerability
+  rather than skip a ceremony: `redirect_uri` is checked against the host's policy
+  on BOTH legs (below), and the PKCE `code_verifier` is verified (constant-time)
+  against the stored S256 `code_challenge`.
+
+  **Which clients may receive a code.** The authorization page is served from the
+  host's own origin, under its own certificate, and asks an operator to paste a
+  live token — so an unvetted `redirect_uri` does not merely add an open redirect,
+  it makes the host's own domain a credential-phishing page: an attacker sends the
+  operator an authorize link carrying the attacker's own `code_challenge`, the
+  operator pastes, and the code is delivered to the attacker, who redeems it with
+  the verifier they chose. PKCE cannot help — they own the verifier.
+
+  So every redirect target must be named by exact string in
+  `config.oauth_allowed_redirect_uris`, with exactly ONE exception:
+  **loopback** (`http://127.0.0.1:*`, `localhost`, `[::1]`), enabled by
+  `config.oauth_allow_loopback_redirects`. It is the exception because it is the
+  one target that CANNOT be named even in principle — an MCP client on an
+  operator's machine listens on an ephemeral port chosen at runtime, so no list
+  could enumerate it (RFC 8252 §7.3 exists for this) — and because a loopback
+  address resolves on the operator's OWN machine, so the attack above, which needs
+  the code to reach a REMOTE attacker, does not work through it.
+
+  A private-use scheme (`cursor://…`, §7.1) is NOT covered: its redirect URI is a
+  fixed string, so it just goes in the allowlist. There is no forcing reason to
+  accept one unnamed, and whole schemes cannot be accepted generically anyway —
+  separating a private-use scheme from a registered network one (`ssh:`, `ldap:`,
+  `gopher:`, each naming a REMOTE host) would mean enumerating the IANA registry,
+  and a denylist of the ones you thought of is the shape that fails open.
+
+  Loopback is judged on the PARSED URI: `http://127.0.0.1@evil.example/` has host
+  `evil.example` and is remote, as is `http://127.0.0.1.evil.example/`; a fragment
+  is refused.
+
+  Endpoints — `GET`/`POST` `<mcp>/oauth/authorize`, `POST <mcp>/oauth/token`,
+  `POST <mcp>/oauth/register`, plus the two metadata documents. A `/.well-known/*`
+  path cannot be drawn by an engine mounted under a path, so a host adds one line at
+  the top level of its route set: `McpToolkit.draw_oauth_metadata_routes(self)` (a
+  no-op unless the bridge is configured). Every identifier is derived from the live
+  request origin, so each host name an app answers on works without further
+  configuration.
+
+  **Additive to a host's own OAuth provider, and it claims nothing origin-global.**
+  The flow endpoints live under the engine's mount (`<mcp>/oauth/*`), so a host
+  already serving OAuth at the conventional top-level `/oauth/*` — as an app with
+  Doorkeeper for its own API does — keeps every one of those routes. The metadata
+  documents are PATH-SCOPED to the mount
+  (`/.well-known/oauth-protected-resource/mcp`), never the bare
+  `/.well-known/oauth-authorization-server`: the bare paths are origin-global and
+  mean "the authorization server of this whole origin", which belongs to that
+  pre-existing provider. RFC 8414 §3.1 exists for exactly this ("Using path
+  components enables supporting multiple issuers per host"), and the MCP
+  authorization spec (2025-11-25) requires a client given a path-ful issuer to try
+  the path-INSERTED URLs with no root fallback — so the issuer is the MCP endpoint
+  URL itself. A host mounted AT its origin root has no path to insert and gets the
+  bare paths, which is correct there.
+- `config.oauth_allowed_redirect_uris` (default `[]`; entries are validated at
+  assignment and the list is frozen — an unparseable, scheme-less,
+  fragment-bearing or *opaque* URI raises, as does cleartext `http://` to a remote
+  host and the `javascript:`/`data:`/`file:` schemes a browser treats as script.
+  Naming bad schemes is sound here and nowhere else: this list is what the HOST
+  wrote, so there is no unlisted scheme for an attacker to slip through — unlike
+  the request-time policy, which is why that one takes the opposite shape),
+  `config.oauth_allow_loopback_redirects` (default `false`),
+  `config.oauth_resource_path` (default `"/mcp"` — must match the engine's mount
+  point), `config.oauth_authorization_code_ttl` (default `60`),
+  `config.oauth_signing_secret` (defaults to the Rails app's `secret_key_base`),
+  and `config.oauth_parent_controller` (default `"ActionController::Base"`).
+- `config.oauth_bridge?` — whether the bridge is live. Gated on the authority role;
+  on a `token_authenticator` being set, since the bridge verifies the pasted token
+  through it on both legs and drawing no route beats an authorization page that
+  takes an operator's token and then errors; and on at least one redirect target
+  being named (an allowlist entry or the loopback switch), so it cannot run
+  without a bound answer to who may receive a code. A satellite — whose tokens
+  belong to its central app — never draws it.
+- The token response is served `Cache-Control: no-store` + `Pragma: no-cache`, a
+  MUST of RFC 6749 §5.1 for any response carrying a token. Both metadata documents
+  get the same headers for a subtler reason: they name the
+  `authorization_endpoint` an operator will be sent to and are built from the
+  caller-influenced request origin (`request.base_url` honours `X-Forwarded-Host`),
+  so a shared cache holding one could hand every client an origin an attacker
+  chose, with the document itself vouching for it. Hosts should also pin
+  `config.hosts`, which Rails leaves empty in production by default.
+- `POST <mcp>/oauth/authorize` answers **303**, not Rails' default 302. That POST
+  carried the operator's token in its body, and only 303 unambiguously tells the
+  browser to fetch the callback with GET and no body (RFC 9700 §4.12).
+- The authority transport's 401 now carries
+  `WWW-Authenticate: Bearer resource_metadata="..."` when the bridge is configured —
+  the header a hosted client waits for before it will start a flow at all. Absent
+  otherwise, so an opted-out host's 401 is unchanged.
+
+### Notes
+
+- **An authorization code leaves nothing usable in the cache.** The entry is keyed
+  by the code's SHA256, and its payload is sealed with `MessageEncryptor`
+  (AES-256-GCM) under a key HMAC'd from `config.oauth_signing_secret` **and** the
+  code. Worth the few lines because what is parked there for the code's lifetime
+  is not the short-lived credential an authorization server would normally hold:
+  it is the operator's pre-existing, long-lived, full-scope token, in a store
+  hosts are told to point at their shared `Rails.cache`.
+
+  The secret is in the key for a specific reason: **the code alone must not be
+  it.** Rails logs an authorization code twice per flow at INFO — `Redirected to
+  ...?code=...` (only `config.filter_redirect` touches that line) and the token
+  endpoint's `Parameters:` (no stock `filter_parameters` entry matches `code`) —
+  so keying on the code alone would leave the key to the cache sitting in the one
+  artifact that is more widely read, longer retained and more replicated than the
+  60-second entry it protects. With the secret mixed in, the cache, the logs and
+  the code together still open nothing.
+
+  The serializer is pinned to `NullSerializer` for a similar reason: every
+  ActiveSupport default across the supported range (`:marshal`, and 7.1+'s
+  `:json_allow_marshal`) reaches `Marshal.load`, so a host with cache-write access
+  forging one blob would have had code execution. `JSON.parse` is now the only
+  parser that sees the payload.
+
+  Codes are also single-use by the DELETE rather than the read, so of two
+  concurrent redemptions exactly one proceeds (verified on MemoryStore, Redis and
+  MemCache stores).
+- The bridge's controller is built from its own `config.oauth_parent_controller`
+  rather than the `parent_controller` the transport uses. The transport is a
+  JSON-only endpoint whose parent is typically `ActionController::API`, which
+  cannot render an HTML view — and the authorization page is one. Keeping them
+  separate means enabling the bridge changes nothing about the transport. Point
+  `oauth_parent_controller` at your own `ApplicationController` to inherit app
+  branding; the page renders with `layout: false` either way.
+- The engine adds `access_token` and `code_verifier` to `config.filter_parameters`
+  itself. The bridge takes a live token in a POST body and Rails logs parameters
+  at INFO, so filtering it is the gem's business — a `rails new` app happens to
+  ship a `:token` entry that covers `access_token` by substring, but that is a
+  host default the gem does not own and an `--api` host may not have.
+- **Serve the bridge over HTTPS** (`config.force_ssl`). The authorization page
+  receives a live access token; on cleartext it is on the wire. A cleartext remote
+  `redirect_uri` is refused in the allowlist for the same reason, but the gem
+  cannot make a host's own origin HTTPS.
+- The bad-paste page answers **422 as an integer**, not a symbol: the gemspec pins
+  no Rack floor and neither symbol spans the supported range
+  (`:unprocessable_content` raises below Rack 3.1, `:unprocessable_entity` is
+  deprecated above it), so a symbol would turn a mistyped paste into an
+  unauthenticated 500 on Rails 7.x.
+- `config.oauth_allowed_redirect_uris` is **frozen** once assigned, and
+  `config.oauth_signing_secret=` validates its input. Both are the same lesson:
+  validation that can be bypassed (`<<` onto the reader) or skipped (a bare
+  writer) is a suggestion, and both failures surface at request time — after an
+  operator has pasted a live token.
+- **A host MUST pin `config.hosts`.** Every identifier the bridge publishes is
+  derived from `request.base_url`, which honours `X-Forwarded-Host`. Rails does
+  not pin it for you — it populates `config.hosts` in development and leaves it
+  empty in production, where empty means no host checking at all.
+- **A host MUST point `config.cache_store` at a shared store** before running the
+  bridge on more than one worker. The default is an in-process MemoryStore, which
+  cannot carry a code from the worker that issued it to the worker that redeems
+  it: the flow then fails roughly (N-1)/N of the time, intermittently, and only
+  after the operator has pasted a live token. Warned about once at boot rather
+  than gated, because a MemoryStore is correct in a single process and
+  `Rails.cache` IS one in a stock development environment.
+- The bridge's two browser legs are guarded by a `before_action` rather than a
+  check inside each action, so the guard cannot be routed around: `authorize` is
+  a common method name, and a gem defining one on `ActionController::Base` would
+  drop the action from Rails' `action_methods` and have Rails serve the template
+  by implicit render — skipping a guard that lived in the body.
+- A host restyles the page by defining its own
+  `app/views/mcp_toolkit/oauth/authorize.html.erb`, which takes precedence over the
+  engine's.
+
 ## [0.5.0] - 2026-07-14
 
 Authority-path discoverability + backward-compatibility work (driven by an

data/README.md

@@ -403,6 +403,190 @@ mount McpToolkit::Engine => "/mcp"   # POST /mcp/tokens/introspect now works
 Drawing it is safe even on an app that is not an authority: with no
 `token_authenticator`, it simply answers `{ "valid": false }`.
 
+### OAuth authorization bridge (authority-only, opt-in)
+
+Some MCP clients will not accept a token you hand them. They authenticate one way
+only: discover an authorization server, run an authorization-code + PKCE flow in a
+browser, and use whatever `access_token` comes back. The MCP authorization spec
+also forbids a token in the request URI, so `?token=<...>` is not a fallback for
+them either. If your tokens are issued out-of-band — an admin UI, a CLI, a support
+process — those clients cannot reach your server at all.
+
+The bridge is a standards-shaped **envelope around the tokens you already issue**.
+It is not an identity provider: its authorization page asks the operator to paste
+an access token they already hold, and the `access_token` it returns **is that
+token**, verified through the same `token_authenticator` your transport uses.
+Scopes, expiry, revocation and tenancy stay exactly where you put them, and it
+creates no new way to obtain a token.
+
+```ruby
+# config/initializers/mcp_toolkit.rb
+McpToolkit.configure do |c|
+  c.auth_role = :authority
+  c.token_authenticator = ->(plaintext) { AccessToken.authenticate(plaintext) }
+
+  # REQUIRED for the bridge on any multi-worker deployment. The default is an
+  # in-process MemoryStore, which cannot carry an authorization code from the
+  # worker that issues it to the worker that redeems it — the flow then fails
+  # intermittently, *after* the operator has pasted their token.
+  c.cache_store = Rails.cache
+
+  # Naming who may receive an authorization code is what switches the bridge on.
+  c.oauth_allowed_redirect_uris = ["https://client.example/callback"]
+  c.oauth_resource_path = "/mcp" # must match the engine's mount point
+
+  # Optional: let any MCP client running on your operators' OWN machines connect
+  # without an allowlist entry each (RFC 8252 — see below). This is an opt-in
+  # signal in its own right, so it alone can switch the bridge on.
+  c.oauth_allow_loopback_redirects = true
+end
+```
+
+```ruby
+# config/routes.rb — the helper call must be TOP LEVEL. A `/.well-known/*` path
+# cannot be drawn by an engine mounted under a path, so the metadata routes have
+# to live in your own route set. A no-op unless the bridge is configured.
+Rails.application.routes.draw do
+  McpToolkit.draw_oauth_metadata_routes(self)
+  mount McpToolkit::Engine => "/mcp"
+end
+```
+
+That yields the whole flow — `GET /.well-known/oauth-protected-resource/mcp`,
+`GET /.well-known/oauth-authorization-server/mcp`, `POST /mcp/oauth/register`,
+`GET`/`POST /mcp/oauth/authorize`, `POST /mcp/oauth/token` — plus a
+`WWW-Authenticate: Bearer resource_metadata="..."` header on the transport's 401,
+which is what makes a client start the flow at all. Every identifier is derived
+from the live request origin, so each host name your app answers on works with no
+further configuration.
+
+**What is deliberately absent**, because none of it gates anything here: client
+registration returns an identifier and stores nothing (no endpoint reads a
+`client_id`); there is no consent step (pasting a token you hold *is* the grant);
+no refresh token is issued (the pasted token's own expiry is the real lifetime, so
+a client re-runs the flow instead of refreshing a shadow of it).
+
+**What is not faked**, because faking either would be a real vulnerability rather
+than a skipped ceremony: `redirect_uri` is checked against your policy on both
+legs (below), and the PKCE `code_verifier` is verified against the stored S256
+challenge in constant time.
+
+### Which clients may receive a code
+
+This is the bridge's load-bearing control, so it is worth knowing why it is shaped
+the way it is. The authorization page is served from **your** origin under **your**
+certificate and asks an operator to paste a live token. So an unvetted
+`redirect_uri` does not merely add an open redirect — it makes your own domain a
+credential-phishing page: an attacker sends the operator an authorize link
+carrying the attacker's own `code_challenge`, the operator pastes, the code is
+delivered to the attacker, and they redeem it with the verifier they chose. PKCE
+does not help (they own the verifier), nor does the single-use code, nor
+re-verifying the token. A full authorization server blocks this with a consent
+screen naming the client plus an authenticated session; this bridge mocks both
+away, which is exactly what the redirect policy compensates for.
+
+So **every target must be named by exact string**, with exactly one exception:
+
+| Target | Rule | Why |
+|---|---|---|
+| Anything remote (`https://client.example/cb`) | Exact string, in `oauth_allowed_redirect_uris` | The phishing vector. Never opened up. |
+| Private-use scheme (`cursor://…`, `com.example.app:/cb`) | Exact string, in `oauth_allowed_redirect_uris` | Keeps the code on the device, but its URI is a fixed string — so just name it. |
+| Loopback (`http://127.0.0.1:*`, `localhost`, `[::1]`) | `oauth_allow_loopback_redirects` | The only target that **cannot** be named: the client picks an ephemeral port at runtime (RFC 8252 §7.3). And it resolves on the operator's own machine, so the attack above cannot reach it. |
+
+The loopback exception exists because an allowlist entry is *impossible* there,
+not because native clients are trusted. A private-use scheme keeps the code on the
+device too, but nothing forces it to be unnamed — and whole **schemes** cannot be
+accepted generically anyway: telling a private-use scheme from a registered
+network one (`ssh:`, `ldap:`, `gopher:` — each naming a **remote** host) would
+mean enumerating the IANA registry, and a denylist of the ones you happened to
+think of is the shape that fails open.
+
+Loopback is judged on the *parsed* URI, so `http://127.0.0.1@evil.example/` (host
+`evil.example`) and `http://127.0.0.1.evil.example/` are both correctly seen as
+remote, and a fragment is refused.
+
+**What the allowlist does not cover.** It binds which URL a code may be sent to —
+not *whose session at that URL* receives it. A hosted MCP client is one callback
+shared by every one of its users, so an attacker can start a flow in their own
+account there, send an operator the resulting authorize link, and have the code
+land back at that client carrying the attacker's `state`. Whether the operator's
+token then ends up in the attacker's account is decided by whether **the client**
+binds `state` to the browser session that began the flow (RFC 6819 §4.4.1.7). An
+authorization server cannot bind a code to a session it never saw, so this is not
+something the bridge — or a full authorization server, which has the identical
+exposure — can close. **Only allowlist clients you believe handle `state`
+correctly.**
+
+### Deployment note
+
+Every identifier the bridge publishes is derived from the live request origin
+(`request.base_url`), which honours `X-Forwarded-Host`. **You MUST pin
+`config.hosts`** so Rails' `HostAuthorization` rejects a forged header before it
+reaches the bridge — Rails does *not* do this for you: it populates `config.hosts`
+in development and leaves it **empty in production**, where empty means no
+checking at all. Both metadata documents are served
+`Cache-Control: no-store` regardless, so no shared cache can hand one client an
+origin another client chose.
+
+**Serve it over HTTPS** (`config.force_ssl = true`). The authorization page
+receives a live access token in a POST body; on cleartext that token is on the
+wire. The gem refuses a cleartext remote `redirect_uri` in the allowlist for the
+same reason, but it cannot make your own origin HTTPS for you.
+
+The engine adds `access_token` and `code_verifier` to `config.filter_parameters`
+itself, so the pasted token stays out of your logs even on a host that ships no
+filter list of its own — nothing to configure.
+
+**It is additive to an OAuth provider you already run, and it claims nothing
+origin-global.** The flow endpoints live under the engine's mount
+(`/mcp/oauth/*`), so if you already serve OAuth at the conventional top-level
+`/oauth/*` — as an app with Doorkeeper for its own API does — you keep every one of
+those routes.
+
+The metadata documents are **path-scoped** to the mount, never the bare
+origin-global `/.well-known/oauth-authorization-server`. That matters: the bare
+paths are origin-global and mean *"the authorization server of this whole origin"*,
+which belongs to a provider you already run, not to an MCP server sharing the host.
+RFC 8414 §3.1 exists for exactly this — *"Using path components enables supporting
+multiple issuers per host"* — and the MCP authorization spec (2025-11-25) requires
+a client given a path-ful issuer to try the path-**inserted** URLs, with no root
+fallback. So the issuer is your MCP endpoint URL, and both documents hang off it.
+
+A path-ful issuer, though, has two readings of *where* under the origin its
+metadata lives, and MCP clients disagree: some **insert** the well-known segment
+before the resource path (`/.well-known/oauth-authorization-server/mcp` — the RFC
+form the host draws), others **append** it after
+(`/mcp/.well-known/oauth-authorization-server`). The bridge serves both: the
+inserted forms at the origin root (`draw_oauth_metadata_routes`), and the appended
+forms — plus the `openid-configuration` OIDC alias — under the engine mount,
+automatically whenever the bridge is on. Both stay path-scoped and claim nothing
+origin-global; a client discovers the authorization server whichever convention it
+follows.
+
+If your MCP endpoint IS its origin root (a dedicated MCP domain), there is no path
+to insert and you get the bare paths — correct there, since your server really is
+that origin's only authorization server. Set `oauth_resource_path = "/"`.
+
+`oauth_allowed_redirect_uris` is empty and `oauth_allow_loopback_redirects`
+is off by default, which leaves `config.oauth_bridge?` false and the routes
+undrawn — the bridge cannot run without bounds on where codes may go. A satellite
+never draws it at all (its tokens belong to its central app, so there is nothing
+for it to authorize against), and neither does an authority with no
+`token_authenticator`, since the bridge verifies the pasted token through it on
+both legs and could not work without one.
+
+The bridge's controller has its **own** parent, `config.oauth_parent_controller`
+(default `ActionController::Base`), deliberately separate from the
+`parent_controller` your transport uses. The transport is a JSON-only endpoint you
+may well have pointed at `ActionController::API`, which cannot render an HTML view
+— and the authorization page is one. Keeping them apart means enabling the bridge
+changes nothing about your transport. Point it at your own `ApplicationController`
+to inherit branding; the page renders with `layout: false` either way, so an app
+layout that needs asset-pipeline context is not pulled in.
+
+To restyle the page, define your own `app/views/mcp_toolkit/oauth/authorize.html.erb`
+— your app's view path takes precedence over the engine's.
+
 ## Authority + gateway server (own tools + upstreams, no SDK)
 
 Beyond the SDK-backed satellite path, the toolkit also ships a **hand-rolled

data/app/views/mcp_toolkit/oauth/authorize.html.erb

@@ -0,0 +1,83 @@
+<%#
+  The bridge's only human-facing surface: paste an access token you already hold.
+
+  Rendered with `layout: false`, so this is a whole document and carries its own
+  styles inline — it must not depend on the host's asset pipeline. A host that
+  wants its own branding defines app/views/mcp_toolkit/oauth/authorize.html.erb
+  in its own tree, which takes precedence over this one.
+
+  The authorization parameters ride through as hidden fields because the bridge
+  keeps no state between the two legs. They are re-validated on POST — the
+  redirect_uri against the allowlist — so a tampered field cannot widen anything.
+%>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex, nofollow">
+    <title>Connect to <%= McpToolkit.config.server_name %></title>
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+        padding: 1.5rem; box-sizing: border-box;
+        font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.5;
+        background: #f4f4f5; color: #18181b;
+      }
+      main { width: 100%; max-width: 26rem; background: #fff; border-radius: 0.75rem; padding: 2rem;
+             box-shadow: 0 1px 3px rgb(0 0 0 / 0.1), 0 8px 24px rgb(0 0 0 / 0.06); }
+      h1 { margin: 0 0 0.5rem; font-size: 1.25rem; }
+      p { margin: 0 0 1.5rem; color: #52525b; font-size: 0.9375rem; }
+      label { display: block; margin-bottom: 0.375rem; font-size: 0.875rem; font-weight: 600; }
+      input[type="password"] {
+        width: 100%; box-sizing: border-box; padding: 0.625rem 0.75rem; font-size: 1rem;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        border: 1px solid #d4d4d8; border-radius: 0.375rem; background: #fff; color: inherit;
+      }
+      input[type="password"]:focus { outline: 2px solid #2563eb; outline-offset: 1px; border-color: #2563eb; }
+      button {
+        width: 100%; margin-top: 1.25rem; padding: 0.625rem 1rem; font-size: 0.9375rem; font-weight: 600;
+        color: #fff; background: #18181b; border: 0; border-radius: 0.375rem; cursor: pointer;
+      }
+      button:hover { background: #3f3f46; }
+      .error {
+        margin: 0 0 1.25rem; padding: 0.75rem; border-radius: 0.375rem; font-size: 0.875rem;
+        background: #fef2f2; border: 1px solid #fecaca; color: #991b1b;
+      }
+      @media (prefers-color-scheme: dark) {
+        body { background: #18181b; color: #fafafa; }
+        main { background: #27272a; box-shadow: none; border: 1px solid #3f3f46; }
+        p { color: #a1a1aa; }
+        input[type="password"] { background: #18181b; border-color: #52525b; }
+        button { background: #fafafa; color: #18181b; }
+        button:hover { background: #d4d4d8; }
+        .error { background: #450a0a; border-color: #7f1d1d; color: #fecaca; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Connect to <%= McpToolkit.config.server_name %></h1>
+      <p>Paste your access token to finish connecting. It is not shown again after this step.</p>
+
+      <% if @mcp_oauth_error.present? %>
+        <div class="error" role="alert"><%= @mcp_oauth_error %></div>
+      <% end %>
+
+      <%= form_tag request.path, method: :post do %>
+        <%= hidden_field_tag :redirect_uri, params[:redirect_uri] %>
+        <%= hidden_field_tag :state, params[:state] %>
+        <%= hidden_field_tag :code_challenge, params[:code_challenge] %>
+        <%= hidden_field_tag :code_challenge_method, params[:code_challenge_method] %>
+
+        <label for="access_token">Access token</label>
+        <%= password_field_tag :access_token, nil, id: "access_token", autocomplete: "off",
+                               autocapitalize: "off", autocorrect: "off", spellcheck: false,
+                               autofocus: true, required: true %>
+
+        <button type="submit">Connect</button>
+      <% end %>
+    </main>
+  </body>
+</html>

data/config/routes.rb

@@ -30,4 +30,39 @@ McpToolkit::Engine.routes.draw do
   # is true whenever `auth_role == :authority`). The controller also fails safe
   # (no `token_authenticator` => `{ valid: false }`), so this is defence in depth.
   post "tokens/introspect", to: "tokens#introspect" if McpToolkit.config.authority?
+
+  # The OAuth authorization bridge (McpToolkit::Oauth::ControllerMethods). Drawn
+  # only when the bridge is configured — `oauth_bridge?` is authority-only AND
+  # requires a redirect-uri allowlist — so a satellite, or any host that has not
+  # opted in, gets no such routes at all. Same reasoning as the introspection
+  # route above: the routes file is evaluated through the routes_reloader, after
+  # the host's initializers/to_prepare, so the config is already set.
+  #
+  # `format: false` on each: without it Rails' optional `(.:format)` segment
+  # matches, so `/mcp/oauth/authorize.json` reaches the action, finds no JSON
+  # template, and 500s — an unauthenticated error on a public endpoint, for a
+  # format the bridge never speaks.
+  if McpToolkit.config.oauth_bridge?
+    get "oauth/authorize", to: "oauth#authorize", format: false
+    post "oauth/authorize", to: "oauth#approve", format: false
+    post "oauth/token", to: "oauth#token", format: false
+    post "oauth/register", to: "oauth#register", format: false
+
+    # The metadata documents, ALSO served path-APPENDED to the mount
+    # (`/mcp/.well-known/oauth-authorization-server`), in addition to the RFC 8414
+    # §3.1 / RFC 9728 §3.1 path-INSERTED locations the host draws at the origin
+    # root via `McpToolkit.draw_oauth_metadata_routes`. A path-ful issuer has two
+    # readings of where its metadata lives, and MCP clients disagree: some INSERT
+    # the well-known segment before the resource path (the RFC form), others APPEND
+    # it after. Observed in the wild — a hosted client requesting
+    # `<mcp>/.well-known/oauth-authorization-server` and getting a 404 it could not
+    # recover from, so it never reached registration. Serving both meets either
+    # convention. Unlike the origin-root bare paths, these stay UNDER the mount, so
+    # they claim nothing origin-global and cannot collide with an OAuth provider
+    # the host already runs. `openid-configuration` is the OIDC discovery alias a
+    # client may probe instead; it answers the same authorization-server document.
+    get ".well-known/oauth-authorization-server", to: "oauth#authorization_server", format: false
+    get ".well-known/oauth-protected-resource", to: "oauth#protected_resource", format: false
+    get ".well-known/openid-configuration", to: "oauth#authorization_server", format: false
+  end
 end

data/lib/mcp_toolkit/authority/controller_methods.rb

@@ -381,6 +381,7 @@ module McpToolkit::Authority::ControllerMethods
   # ---- error renders --------------------------------------------------
 
   def mcp_render_unauthorized(message)
+    mcp_set_authenticate_challenge
     render json: {
       jsonrpc: McpToolkit::Protocol::JSONRPC_VERSION,
       id: nil,
@@ -391,6 +392,29 @@ module McpToolkit::Authority::ControllerMethods
     }, status: :unauthorized
   end
 
+  # Points an unauthenticated caller at the OAuth bridge's protected-resource
+  # metadata (RFC 9728). This header is what a hosted MCP client waits for before
+  # it will start an authorization flow at all — without it, a 401 is just a
+  # failure. It also makes the metadata's location OURS to state rather than the
+  # client's to guess: RFC 9728 has the client fetch this URL directly, so the
+  # path-scoped location is found without probing the origin's bare well-known
+  # path. Emitted only when the bridge is configured, so a host that has not opted
+  # in keeps its 401 byte-identical.
+  #
+  # `request.base_url` honours `X-Forwarded-Host`, so it is caller-influenced and
+  # cannot be interpolated into a quoted-string parameter unescaped: a host
+  # carrying a `"` would close the quotes and let a caller append auth-params of
+  # their own. A URL has no business containing one, so refuse rather than escape
+  # — an origin that odd is a misconfiguration to notice, not to render.
+  def mcp_set_authenticate_challenge
+    return unless mcp_config.oauth_bridge?
+
+    metadata_url = "#{request.base_url}#{mcp_config.oauth_protected_resource_path}"
+    return if metadata_url.include?('"')
+
+    response.headers["WWW-Authenticate"] = %(Bearer resource_metadata="#{metadata_url}")
+  end
+
   def mcp_render_session_not_found
     render json: {
       jsonrpc: McpToolkit::Protocol::JSONRPC_VERSION,