mcp_toolkit 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 375206ea98c72a64738894427abd86bf0e272f5fad3c359860cd684707e38da7
-  data.tar.gz: e37f4ca9689b78c871daabc65110c7b5676760806d9eadaec45b30ea687f9b79
+  metadata.gz: af5e847538e7fe188e7fb0b0b509f0f430d2c3d33c84fa21350e30367a409578
+  data.tar.gz: dc3233698fd64947b42330fe51bd230e249f37e9044d303eaf1915ea213e1695
 SHA512:
-  metadata.gz: 5920ce2f6e47c077d6f89a4078b74b82935a4be18f5a44cc415168b78e65f85aec6354ba7a3d81d1246f63d0c4d621503f5445b198ad42d80db2ab1ad129d750
-  data.tar.gz: '091c72fd1efc0d5dbea0298af70355f21436e194d37534aa98629ea786442fa4477b00b656de0a03b8ac31485ea38d8ad783de1a59bb927f82df75922f028f79'
+  metadata.gz: a1fc3088f0a6532ed7a52e7cf13e13ce372edbdcddd61f255fd93cb28df6c0c5fe3a3c17ef98cedf8c5a3be5f8c72d58f8f9bdbc28eac1e7b5ae3308a83cd21f
+  data.tar.gz: fb9a05e81f3895dc89d65dc45a33deef371387d8ba14bf223454f666b8bdeb9c828876a66ba9f6c54b19019b416cd88dc6c66dd5ab562fdc577d1b5148872aae

data/CHANGELOG.md

@@ -1,3 +1,55 @@
+## [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

data/README.md

@@ -543,16 +543,26 @@ origin-global.** The flow endpoints live under the engine's mount
 `/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
-(`/.well-known/oauth-protected-resource/mcp`), never the bare
-`/.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.
+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 = "/"`.

data/config/routes.rb

@@ -38,17 +38,31 @@ McpToolkit::Engine.routes.draw do
   # route above: the routes file is evaluated through the routes_reloader, after
   # the host's initializers/to_prepare, so the config is already set.
   #
-  # The two metadata documents are NOT here: a client looks for them at the origin
-  # root, which an engine mounted under a path cannot draw. The host draws them
-  # with `McpToolkit.draw_oauth_metadata_routes(self)`.
-  # `format: false` on each, as on the metadata routes the host draws: 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.
+  # `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/oauth/controller_methods.rb

@@ -37,6 +37,12 @@ module McpToolkit::Oauth::ControllerMethods
   # base64url of a SHA-256, which is always exactly 43 of the same alphabet.
   PKCE_VALUE = /\A[A-Za-z0-9\-._~]{43,128}\z/
 
+  # What the token endpoint actually honours. Named once because the discovery
+  # document and the registration response MUST agree — a client reads the first
+  # to find the second, so a disagreement is this server contradicting itself.
+  SUPPORTED_GRANT_TYPES = %w[authorization_code].freeze
+  SUPPORTED_RESPONSE_TYPES = %w[code].freeze
+
   included do
     # Safe to disable: the token endpoint is called server-to-server without a CSRF
     # token, and `approve` never acts on ambient authority — it reads no session and
@@ -86,22 +92,38 @@ module McpToolkit::Oauth::ControllerMethods
       authorization_endpoint: mcp_oauth_endpoint_url("authorize"),
       token_endpoint: mcp_oauth_endpoint_url("token"),
       registration_endpoint: mcp_oauth_endpoint_url("register"),
-      response_types_supported: ["code"],
-      grant_types_supported: ["authorization_code"],
+      response_types_supported: SUPPORTED_RESPONSE_TYPES,
+      grant_types_supported: SUPPORTED_GRANT_TYPES,
       code_challenge_methods_supported: ["S256"],
       token_endpoint_auth_methods_supported: ["none"]
     }
   end
 
-  # Stateless: persisting a `client_id` nothing reads would only grow a table of
-  # strings the bridge never consults.
+  # Stateless: nothing here is persisted (no endpoint reads a `client_id`). The
+  # response still names the `redirect_uris` the client sent, because a strict
+  # client validates that they come back and abandons a registration that drops
+  # them — the failure a hosted client hit against the pre-0.6.1 stub, which
+  # returned only a `client_id`. That echo AUTHORIZES nothing: `authorize` and
+  # `token` check every `redirect_uri` against the host's allowlist independently.
+  #
+  # The auth method and the grant/response types are SUBSTITUTED rather than
+  # 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 instead
+  # would contradict `authorization_server`, which is where that client got this
+  # endpoint, and would promise a flow `token` rejects: a `refresh_token` echoed
+  # back is a refresh answered `unsupported_grant_type`. No `client_secret` is
+  # issued, so `none` is the only auth method a client here could perform.
   def register
-    render json: {
+    body = {
       client_id: SecureRandom.uuid,
+      client_id_issued_at: Time.now.to_i,
+      redirect_uris: mcp_oauth_param_list(:redirect_uris),
       token_endpoint_auth_method: "none",
-      grant_types: ["authorization_code"],
-      response_types: ["code"]
-    }, status: :created
+      grant_types: mcp_oauth_registered_subset(:grant_types, SUPPORTED_GRANT_TYPES),
+      response_types: mcp_oauth_registered_subset(:response_types, SUPPORTED_RESPONSE_TYPES)
+    }
+    body[:client_name] = params[:client_name].to_s if params[:client_name].present?
+    render json: body, status: :created
   end
 
   # `formats: [:html]` because there is only an HTML template and `Accept` picks
@@ -151,6 +173,19 @@ module McpToolkit::Oauth::ControllerMethods
     McpToolkit.config
   end
 
+  # A registration parameter as a plain array of strings — RFC 7591 lists arrive
+  # as JSON arrays; empty when the client sent none.
+  def mcp_oauth_param_list(key)
+    Array(params[key]).map(&:to_s)
+  end
+
+  # What the client asked for, narrowed to what this server honours. A client that
+  # asked for NOTHING supported gets the default rather than an empty array, which
+  # would state a registration able to do nothing at all.
+  def mcp_oauth_registered_subset(key, supported)
+    (mcp_oauth_param_list(key) & supported).presence || supported
+  end
+
   # ---- request validation ---------------------------------------------------
 
   # Halts both legs before their action runs. Both problems RENDER rather than

data/lib/mcp_toolkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module McpToolkit
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Karol Galanciak