hub_kernel-mcp 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c892de0b21d83e1d2068595a30e59930be423fa5b30dc539ffaedf3c304be263
-  data.tar.gz: 22114b0e2e4a5aa6c3389dc7c7580079a9091a5ac46bcfc6e7b53585eddcce16
+  metadata.gz: 6c25e5f3f088ea410414724954e79aaf5571f10d7c9060ad2a0a6298487df3fb
+  data.tar.gz: 2cc4f2810b8804056784ff5eae16d4a40134d43bdb61e06dca949f4ca9230ef1
 SHA512:
-  metadata.gz: 507a819510592862a8a2641075062fecf56f052de877ee8b7dc2fc7dd1ac66b7aace212dd7272cc33c6c65d80a1f9dbd792c7b63cf326a378fdbacca0a257dfb
-  data.tar.gz: b9e8d051ef5ef2f781499d69d17866e29b91475a7ba9e49f3648a8c10fcaa3f644da6acac643398d06421ee58e89479dd80c99dc3f7e50456bb848c0b6e3fc4f
+  metadata.gz: 6e0a335dfa07e60b06c07c3d7f29557c3a9983dc8195ba5301a3b26d1fa3bb14f9925e1a9e76fa911b6e09c35efdbb9e9d84f81923deafafde457de86f28af96
+  data.tar.gz: 9ba71b706c1b4b06fcfd9661515f8902837d91a6715f6e84e767b4e6ea12f766fc553b39eb0d7cc367ad871d30c176de35ed837d2567e03ab77c19b116890968

data/README.md

@@ -89,6 +89,154 @@ An unexpected error's own message is never sent to the client. It is reported to
 app's error reporting through `Rails.error`. A GET to the endpoint's address is answered with
 status 405, since the endpoint offers no sessions or server-sent events.
 
+## Signing in from a connector screen
+
+A client such as Claude's connector screen finds the endpoint's sign-in by itself and
+registers there, so a person only pastes the endpoint's address. Install the gem's migrations,
+then mount its discovery documents at the site root beside the endpoint:
+
+```sh
+bin/rails hub_kernel_mcp:install:migrations db:migrate
+```
+
+```ruby
+mount HubKernel::Mcp::Engine => "/mcp"
+mount HubKernel::Mcp::Discovery => "/.well-known"
+```
+
+Every 401 from the endpoint carries a `WWW-Authenticate` header naming where the endpoint is
+described:
+
+```
+Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp"
+```
+
+That document names the endpoint's address and its sign-in, the site root. The sign-in's own
+document, at `/.well-known/oauth-authorization-server`, names the registration, approval and
+token addresses under the endpoint's address, such as `/mcp/register`, and says a client must
+use PKCE with SHA-256.
+
+A client registers by posting its name and redirect addresses to the registration address:
+
+```json
+{ "client_name": "Claude", "redirect_uris": [ "https://claude.ai/api/mcp/auth_callback" ] }
+```
+
+It is answered with status 201 and a client id. A registration with no redirect address, or
+with one that is neither HTTPS nor on the client's own machine, is answered with status 400,
+`invalid_redirect_uri`, and the reason. A body that is not valid JSON is answered with status
+400 and `invalid_client_metadata`. One address may register ten clients an hour, and a
+registration past that is answered with status 429 and `too_many_registrations`. A host sets a
+different limit with:
+
+```ruby
+HubKernel::Mcp.registration_limit = 20
+```
+
+The approval address is a browser page. It runs inside a controller of the host's, so the
+host's own sign-in decides who is approving. Name that controller, the method on it that signs a
+person in, the method that gives the signed-in person, and the layout the page is shown in:
+
+```ruby
+HubKernel::Mcp.browser_controller = "ApplicationController"
+HubKernel::Mcp.sign_in_method = :authenticate_user!
+HubKernel::Mcp.browser_person_method = :current_user
+HubKernel::Mcp.browser_layout = "application"
+```
+
+`HubKernel::Mcp.check!` names each of the four a host has not set. The person the page gives is
+kept by its global id, so it must be a record that has one.
+
+A person who is not signed in is sent through the host's sign-in. A signed-in person sees the
+name of the app asking to connect, with an Approve and a Deny button. Approving sends them back
+to the client's redirect address with a code and the client's `state`. Denying sends them back
+with `error=access_denied` and no code. A request missing its `client_id` or `redirect_uri`,
+naming a client that is not registered, or naming a redirect address the client did not
+register shows an error page saying which, and sends the person nowhere. A request with no PKCE
+challenge, or one whose method is not `S256`, is sent back with `error=invalid_request`.
+
+The client trades the code at the token address, posting it form-encoded with its PKCE verifier,
+the redirect address it was approved for and its client id:
+
+```
+grant_type=authorization_code&code=<code>&code_verifier=<verifier>&redirect_uri=<redirect>&client_id=<client id>
+```
+
+It is answered with an access token that lasts an hour and a refresh token:
+
+```json
+{ "access_token": "<token>", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "<refresh token>" }
+```
+
+A code is used up by the trade. A code posted with a verifier that does not match its challenge,
+with another client id or redirect address, a second time, or more than ten minutes after it was
+made is answered with status 400, `invalid_grant` and a description, and gives no token. A code
+posted a second time also stops the access and refresh tokens already issued from it.
+
+When the access token expires, the client posts its refresh token and client id to the same
+address:
+
+```
+grant_type=refresh_token&refresh_token=<refresh token>&client_id=<client id>
+```
+
+It is answered the same way, with a new access token and a new refresh token, and the refresh
+token it posted stops working. A refresh token posted by a client other than the one it was
+issued to, one already traded, or one unused for ninety days is answered with status 400,
+`invalid_grant` and a description, and the person signs in again. Any other `grant_type` is
+answered with `unsupported_grant_type`, and a body that cannot be read with `invalid_request`.
+
+An unexpected error at the registration or token address or a discovery document is answered
+with status 500 and `server_error`, and on the approval page with an error page. Its message is
+never sent to the client or shown to the person. It is reported to the host app's error
+reporting through `Rails.error`.
+
+The client then sends the token on every request to the endpoint as `Authorization: Bearer
+<token>`. The host's own sign-in, the base controller the endpoint inherits from, asks the gem
+for the person a token acts for:
+
+```ruby
+class Api::McpBaseController < ActionController::API
+  include ActionController::HttpAuthentication::Token::ControllerMethods
+
+  before_action { head :unauthorized unless current_person }
+
+  private
+
+  def current_person = authenticate_with_http_token { |token| HubKernel::Mcp::Connection.person_for(token) }
+end
+```
+
+`HubKernel::Mcp::Connection.person_for` gives the person while the token is unexpired, and `nil`
+for an expired or unknown token. Every call is made in the account the host's account method
+gives, so that method must give one for a person signed in this way.
+
+A person can see the apps connected as them and disconnect one. The gem ships a section for a
+host's settings page: the `hub_kernel/mcp/connections` partial, which lists each of the person's
+connections with the app's name, when it connected and when it was last used, and the
+`HubKernel::Mcp::Disconnect` action its Disconnect buttons run. A host using settings_hub
+registers both:
+
+```ruby
+SettingsHub.section :connections, area: :user, title: "Connected apps",
+  renders: "hub_kernel/mcp/connections", runs: "HubKernel::Mcp::Disconnect"
+```
+
+The partial takes the `person` and the `submit_url` its buttons send a `connection_id` to by
+PATCH. The action is built with `new(person:, account:, values:)`, and `call` answers a result
+whose `ok?` is false, with a `message`, when the connection is not the person's own. A
+disconnected connection's access and refresh tokens stop working at once.
+
+A host runs one task, on whatever schedule its job runner keeps, to remove sign-in records that
+can no longer be used: authorization codes past their ten minutes, connections whose access and
+refresh tokens have both expired, and clients over a day old with no connection.
+
+```sh
+bin/rails hub_kernel_mcp:prune
+```
+
+A connection whose access token or refresh token still works is never removed.
+
 ## Installation
 
 ```ruby

data/app/controllers/hub_kernel/mcp/authorizations_controller.rb

@@ -0,0 +1,69 @@
+require "uri"
+
+module HubKernel
+  module Mcp
+    class AuthorizationsController < HubKernel::Mcp.browser_controller.constantize
+      APPROVAL_PARAMS = %i[response_type client_id redirect_uri state code_challenge code_challenge_method].freeze
+
+      layout -> { HubKernel::Mcp.browser_layout }
+
+      before_action { send(HubKernel::Mcp.sign_in_method) }
+      around_action :report_unexpected_errors
+      before_action :refuse_missing_values, :refuse_unknown_client, :refuse_unregistered_redirect
+      before_action :refuse_without_pkce
+
+      helper_method :approval_params
+
+      def new
+      end
+
+      def create
+        return redirect_to_client(error: "access_denied") unless params[:decision] == "approve"
+
+        code = AuthorizationCode.issue(person: send(HubKernel::Mcp.browser_person_method), client: @client, redirect_uri: params[:redirect_uri], code_challenge: params[:code_challenge])
+        redirect_to_client(code: code)
+      end
+
+      private
+
+      def report_unexpected_errors
+        yield
+      rescue StandardError => error
+        Rails.error.report(error, handled: true)
+        @reason = "Signing in failed unexpectedly"
+        render :refused, status: :internal_server_error
+      end
+
+      def refuse_missing_values
+        missing = %i[client_id redirect_uri].find { |name| params[name].blank? }
+        refuse_on_page("The approval request is missing #{missing}") if missing
+      end
+
+      def refuse_unknown_client
+        @client = Client.find_by(uid: params[:client_id])
+        refuse_on_page("The app asking to connect is not registered") unless @client
+      end
+
+      def refuse_unregistered_redirect
+        refuse_on_page("This app asked to send you to an address it did not register") unless @client.redirect_uris.include?(params[:redirect_uri])
+      end
+
+      def refuse_on_page(reason)
+        @reason = reason
+        render :refused, status: :bad_request
+      end
+
+      def refuse_without_pkce
+        redirect_to_client(error: "invalid_request", error_description: "A PKCE challenge using S256 is required") unless params[:code_challenge].present? && params[:code_challenge_method] == "S256"
+      end
+
+      def redirect_to_client(answer)
+        uri = URI.parse(params[:redirect_uri])
+        uri.query = [ uri.query, answer.merge(state: params[:state]).compact.to_query ].compact_blank.join("&")
+        redirect_to uri.to_s, allow_other_host: true
+      end
+
+      def approval_params = params.permit(*APPROVAL_PARAMS)
+    end
+  end
+end

data/app/controllers/hub_kernel/mcp/discovery_controller.rb

@@ -0,0 +1,29 @@
+module HubKernel
+  module Mcp
+    class DiscoveryController < ActionController::API
+      rescue_from(StandardError) do |error|
+        Rails.error.report(error, handled: true)
+        render status: :internal_server_error, json: { error: "server_error", error_description: "The sign-in failed unexpectedly" }
+      end
+
+      def resource = render(json: { resource: endpoint_url, authorization_servers: [ request.base_url ] })
+
+      def sign_in
+        render json: {
+          issuer: request.base_url,
+          registration_endpoint: "#{endpoint_url}/register",
+          authorization_endpoint: "#{endpoint_url}/authorize",
+          token_endpoint: "#{endpoint_url}/token",
+          response_types_supported: [ "code" ],
+          grant_types_supported: [ "authorization_code", "refresh_token" ],
+          token_endpoint_auth_methods_supported: [ "none" ],
+          code_challenge_methods_supported: [ "S256" ]
+        }
+      end
+
+      private
+
+      def endpoint_url = request.base_url + HubKernel::Mcp::Engine.routes.find_script_name({})
+    end
+  end
+end

data/app/controllers/hub_kernel/mcp/registrations_controller.rb

@@ -0,0 +1,28 @@
+module HubKernel
+  module Mcp
+    class RegistrationsController < ActionController::API
+      rescue_from(StandardError) do |error|
+        Rails.error.report(error, handled: true)
+        render status: :internal_server_error, json: { error: "server_error", error_description: "The sign-in failed unexpectedly" }
+      end
+      rescue_from(ActionDispatch::Http::Parameters::ParseError) { render(status: :bad_request, json: { error: "invalid_client_metadata", error_description: "The registration body is not valid JSON" }) }
+
+      def create
+        return refuse_past_limit if Client.where(registered_from: request.remote_ip, created_at: 1.hour.ago..).count >= HubKernel::Mcp.registration_limit
+
+        client = Client.new(name: params[:client_name], redirect_uris: Array(params[:redirect_uris]), registered_from: request.remote_ip)
+        return refuse(client) unless client.save
+
+        render status: :created, json: { client_id: client.uid, client_name: client.name, redirect_uris: client.redirect_uris, token_endpoint_auth_method: "none" }
+      end
+
+      private
+
+      def refuse_past_limit
+        render status: :too_many_requests, json: { error: "too_many_registrations", error_description: "This address has registered #{HubKernel::Mcp.registration_limit} clients in the last hour, which is the limit" }
+      end
+
+      def refuse(client) = render(status: :bad_request, json: { error: "invalid_redirect_uri", error_description: client.errors.full_messages.to_sentence })
+    end
+  end
+end

data/app/controllers/hub_kernel/mcp/tokens_controller.rb

@@ -0,0 +1,51 @@
+module HubKernel
+  module Mcp
+    class TokensController < ActionController::API
+      UNUSABLE_CODE = "The code is unknown, used, expired, or does not match this client, redirect address or verifier".freeze
+      UNUSABLE_REFRESH_TOKEN = "The refresh token is unknown, used, unused for ninety days, or belongs to another client".freeze
+
+      rescue_from(StandardError) do |error|
+        Rails.error.report(error, handled: true)
+        render status: :internal_server_error, json: { error: "server_error", error_description: "The sign-in failed unexpectedly" }
+      end
+      rescue_from(ActionDispatch::Http::Parameters::ParseError) { refuse("invalid_request", "The token request body could not be read") }
+
+      def create
+        case params[:grant_type]
+        when "authorization_code" then answer(exchanged, UNUSABLE_CODE)
+        when "refresh_token" then answer(refreshed, UNUSABLE_REFRESH_TOKEN)
+        else refuse("unsupported_grant_type", "The token address takes authorization_code or refresh_token")
+        end
+      end
+
+      private
+
+      def answer(tokens, refusal)
+        return refuse("invalid_grant", refusal) unless tokens
+
+        render json: { access_token: tokens.access_token, token_type: "Bearer", expires_in: Connection::LIFETIME.to_i, refresh_token: tokens.refresh_token }
+      end
+
+      def refuse(error, description) = render(status: :bad_request, json: { error: error, error_description: description })
+
+      def exchanged
+        code_digest = AuthorizationCode.digest(params[:code].to_s)
+        code = AuthorizationCode.find_by(code_digest: code_digest)
+        return stop_tokens_issued_from(code_digest) unless code
+
+        Connection.issue(person: code.person, client: code.client, code_digest: code_digest) if exchangeable?(code)
+      end
+
+      def stop_tokens_issued_from(code_digest)
+        Connection.where(code_digest: code_digest).delete_all
+        nil
+      end
+
+      def refreshed = Connection.refresh(params[:refresh_token], client: Client.find_by(uid: params[:client_id]))
+
+      def exchangeable?(code) = code.present? && code.expires_at.future? && code.client.uid == params[:client_id] && code.redirect_uri == params[:redirect_uri] && code.verifies?(params[:code_verifier]) && used_up?(code)
+
+      def used_up?(code) = AuthorizationCode.where(id: code.id).delete_all == 1
+    end
+  end
+end

data/app/models/hub_kernel/mcp/authorization_code.rb

@@ -0,0 +1,27 @@
+require "base64"
+require "digest"
+require "securerandom"
+
+module HubKernel
+  module Mcp
+    class AuthorizationCode < ActiveRecord::Base
+      LIFETIME = 10.minutes
+
+      belongs_to :client
+
+      def self.issue(person:, client:, redirect_uri:, code_challenge:)
+        code = SecureRandom.urlsafe_base64(32)
+        create!(code_digest: digest(code), person_gid: person.to_global_id.to_s, client: client, redirect_uri: redirect_uri, code_challenge: code_challenge, expires_at: LIFETIME.from_now)
+        code
+      end
+
+      def self.digest(code) = Digest::SHA256.hexdigest(code)
+
+      def person = GlobalID::Locator.locate(person_gid)
+
+      def verifies?(verifier)
+        ActiveSupport::SecurityUtils.secure_compare(Base64.urlsafe_encode64(Digest::SHA256.digest(verifier.to_s), padding: false), code_challenge)
+      end
+    end
+  end
+end

data/app/models/hub_kernel/mcp/client.rb

@@ -0,0 +1,32 @@
+require "uri"
+
+module HubKernel
+  module Mcp
+    class Client < ActiveRecord::Base
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+      has_secure_token :uid
+
+      validate :redirect_uris_named, :redirect_uris_allowed
+
+      private
+
+      def redirect_uris_named
+        errors.add(:base, "A client must register at least one redirect address") if redirect_uris.blank?
+      end
+
+      def redirect_uris_allowed
+        Array(redirect_uris).reject { |address| allowed_redirect?(address.to_s) }.each do |address|
+          errors.add(:base, "#{address} is neither HTTPS nor on the client's own machine")
+        end
+      end
+
+      def allowed_redirect?(address)
+        uri = URI.parse(address)
+        uri.hostname.present? && (uri.scheme == "https" || (uri.scheme == "http" && LOCAL_HOSTS.include?(uri.hostname)))
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+  end
+end

data/app/models/hub_kernel/mcp/connection.rb

@@ -0,0 +1,50 @@
+require "digest"
+require "securerandom"
+
+module HubKernel
+  module Mcp
+    class Connection < ActiveRecord::Base
+      LIFETIME = 1.hour
+      REFRESH_LIFETIME = 90.days
+
+      Tokens = Data.define(:access_token, :refresh_token)
+
+      belongs_to :client
+
+      scope :of, ->(person) { where(person_gid: person.to_global_id.to_s) }
+
+      def self.issue(person:, client:, code_digest: nil)
+        tokens = new_tokens
+        create!(person_gid: person.to_global_id.to_s, client: client, code_digest: code_digest, **digests_for(tokens))
+        tokens
+      end
+
+      def self.refresh(refresh_token, client:)
+        connection = where(refresh_expires_at: Time.current..).find_by(refresh_token_digest: digest(refresh_token.to_s), client: client)
+        return unless connection
+
+        tokens = new_tokens
+        renewed = where(id: connection.id, refresh_token_digest: connection.refresh_token_digest).update_all(updated_at: Time.current, **digests_for(tokens))
+        tokens if renewed == 1
+      end
+
+      def self.person_for(token)
+        connection = where(expires_at: Time.current..).find_by(token_digest: digest(token.to_s))
+        connection&.touch(:last_used_at)
+        connection&.person
+      end
+
+      def self.digest(token) = Digest::SHA256.hexdigest(token)
+
+      def self.new_tokens = Tokens.new(access_token: SecureRandom.urlsafe_base64(32), refresh_token: SecureRandom.urlsafe_base64(32))
+
+      def self.digests_for(tokens)
+        { token_digest: digest(tokens.access_token), refresh_token_digest: digest(tokens.refresh_token), expires_at: LIFETIME.from_now, refresh_expires_at: REFRESH_LIFETIME.from_now }
+      end
+
+      private_class_method :new_tokens, :digests_for
+
+      def person = GlobalID::Locator.locate(person_gid)
+    end
+  end
+end

data/app/models/hub_kernel/mcp/disconnect.rb

@@ -0,0 +1,19 @@
+module HubKernel
+  module Mcp
+    class Disconnect
+      Result = Data.define(:message) do
+        def ok? = message.nil?
+      end
+
+      def initialize(values:, person: nil, account: nil)
+        @person = person
+        @values = values
+      end
+
+      def call
+        disconnected = Connection.of(@person).where(id: @values[:connection_id]).delete_all
+        Result.new(message: disconnected.zero? ? "That connection is not one of yours" : nil)
+      end
+    end
+  end
+end

data/app/models/hub_kernel/mcp/prune.rb

@@ -0,0 +1,12 @@
+module HubKernel
+  module Mcp
+    module Prune
+      def self.call
+        now = Time.current
+        AuthorizationCode.where(expires_at: ...now).delete_all
+        Connection.where(expires_at: ...now).where("refresh_expires_at IS NULL OR refresh_expires_at < ?", now).delete_all
+        Client.where(created_at: ...1.day.ago).where.not(id: Connection.select(:client_id)).where.not(id: AuthorizationCode.select(:client_id)).delete_all
+      end
+    end
+  end
+end

data/app/views/hub_kernel/mcp/_connections.html.erb

@@ -0,0 +1,10 @@
+<ul>
+  <% HubKernel::Mcp::Connection.of(person).includes(:client).order(:created_at).each do |connection| %>
+    <li>
+      <strong><%= connection.client.name %></strong>
+      <span>Connected <%= l(connection.created_at, format: :long) %></span>
+      <span><%= connection.last_used_at ? "Last used #{l(connection.last_used_at, format: :long)}" : "Never used" %></span>
+      <%= button_to "Disconnect", submit_url, method: :patch, params: { connection_id: connection.id } %>
+    </li>
+  <% end %>
+</ul>

data/app/views/hub_kernel/mcp/authorizations/new.html.erb

@@ -0,0 +1,9 @@
+<h1><%= @client.name %> wants to connect as you</h1>
+
+<%= form_with url: request.path, method: :post do |form| %>
+  <% approval_params.each do |name, value| %>
+    <%= hidden_field_tag name, value %>
+  <% end %>
+  <%= form.button "Approve", name: "decision", value: "approve" %>
+  <%= form.button "Deny", name: "decision", value: "deny" %>
+<% end %>

data/app/views/hub_kernel/mcp/authorizations/refused.html.erb

@@ -0,0 +1 @@
+<h1><%= @reason %></h1>

data/config/routes.rb

@@ -1,4 +1,8 @@
 HubKernel::Mcp::Engine.routes.draw do
   post "/", to: "messages#create"
   get "/", to: "messages#refuse_get"
+  post "register", to: "registrations#create"
+  get "authorize", to: "authorizations#new"
+  post "authorize", to: "authorizations#create"
+  post "token", to: "tokens#create"
 end

data/db/migrate/20261007000000_create_hub_kernel_mcp_clients.rb

@@ -0,0 +1,10 @@
+class CreateHubKernelMcpClients < ActiveRecord::Migration[8.1]
+  def change
+    create_table :hub_kernel_mcp_clients do |t|
+      t.string :uid, null: false, index: { unique: true }
+      t.string :name
+      t.json :redirect_uris, null: false
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20261008000000_create_hub_kernel_mcp_authorization_codes.rb

@@ -0,0 +1,13 @@
+class CreateHubKernelMcpAuthorizationCodes < ActiveRecord::Migration[8.1]
+  def change
+    create_table :hub_kernel_mcp_authorization_codes do |t|
+      t.string :code_digest, null: false, index: { unique: true }
+      t.references :client, null: false, foreign_key: { to_table: :hub_kernel_mcp_clients }
+      t.string :person_gid, null: false
+      t.string :redirect_uri, null: false
+      t.string :code_challenge, null: false
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20261009000000_create_hub_kernel_mcp_connections.rb

@@ -0,0 +1,11 @@
+class CreateHubKernelMcpConnections < ActiveRecord::Migration[8.1]
+  def change
+    create_table :hub_kernel_mcp_connections do |t|
+      t.string :token_digest, null: false, index: { unique: true }
+      t.references :client, null: false, foreign_key: { to_table: :hub_kernel_mcp_clients }
+      t.string :person_gid, null: false
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20261009000001_add_refresh_token_to_hub_kernel_mcp_connections.rb

@@ -0,0 +1,7 @@
+class AddRefreshTokenToHubKernelMcpConnections < ActiveRecord::Migration[8.1]
+  def change
+    add_column :hub_kernel_mcp_connections, :refresh_token_digest, :string
+    add_column :hub_kernel_mcp_connections, :refresh_expires_at, :datetime
+    add_index :hub_kernel_mcp_connections, :refresh_token_digest, unique: true
+  end
+end

data/db/migrate/20261009000002_add_last_used_at_to_hub_kernel_mcp_connections.rb

@@ -0,0 +1,5 @@
+class AddLastUsedAtToHubKernelMcpConnections < ActiveRecord::Migration[8.1]
+  def change
+    add_column :hub_kernel_mcp_connections, :last_used_at, :datetime
+  end
+end

data/db/migrate/20261009000003_add_code_digest_to_hub_kernel_mcp_connections.rb

@@ -0,0 +1,6 @@
+class AddCodeDigestToHubKernelMcpConnections < ActiveRecord::Migration[8.1]
+  def change
+    add_column :hub_kernel_mcp_connections, :code_digest, :string
+    add_index :hub_kernel_mcp_connections, :code_digest
+  end
+end

data/db/migrate/20261009000004_add_registered_from_to_hub_kernel_mcp_clients.rb

@@ -0,0 +1,6 @@
+class AddRegisteredFromToHubKernelMcpClients < ActiveRecord::Migration[8.1]
+  def change
+    add_column :hub_kernel_mcp_clients, :registered_from, :string
+    add_index :hub_kernel_mcp_clients, [ :registered_from, :created_at ]
+  end
+end

data/lib/hub_kernel/mcp/challenge.rb

@@ -0,0 +1,21 @@
+require "rack/request"
+
+module HubKernel
+  module Mcp
+    class Challenge
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        headers["www-authenticate"] = challenge(Rack::Request.new(env)) if status == 401
+        [ status, headers, body ]
+      end
+
+      private
+
+      def challenge(request) = %(Bearer resource_metadata="#{request.base_url}/.well-known/oauth-protected-resource#{request.script_name}")
+    end
+  end
+end

data/lib/hub_kernel/mcp/discovery.rb

@@ -0,0 +1,12 @@
+require "action_dispatch"
+
+module HubKernel
+  module Mcp
+    Discovery = ActionDispatch::Routing::RouteSet.new.tap do |routes|
+      routes.draw do
+        get "oauth-protected-resource(/*resource)", to: "hub_kernel/mcp/discovery#resource"
+        get "oauth-authorization-server", to: "hub_kernel/mcp/discovery#sign_in"
+      end
+    end
+  end
+end

data/lib/hub_kernel/mcp/engine.rb

@@ -1,7 +1,11 @@
+require "hub_kernel/mcp/challenge"
+
 module HubKernel
   module Mcp
     class Engine < ::Rails::Engine
       isolate_namespace HubKernel::Mcp
+
+      middleware.use HubKernel::Mcp::Challenge
     end
   end
 end

data/lib/hub_kernel/mcp/version.rb

@@ -1,5 +1,5 @@
 module HubKernel
   module Mcp
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end