hub_kernel-mcp 0.7.0 → 0.8.0

data/the_local/agents/hub_kernel-mcp-info.md

@@ -1,8 +1,8 @@
 ---
 name: hub_kernel-mcp-info
-description: Use to learn what hub_kernel-mcp offers — serving a host's hubs as MCP tools, how tools are named and scoped, and the vocabulary the install and develop locals assume.
+description: Use to learn what hub_kernel-mcp offers — serving a host's hubs as MCP tools, how tools are named and scoped, how a client such as Claude's connector screen finds the endpoint's sign-in, registers itself, is approved by a person through the browser, trades its code for an access token and a refresh token and later trades the refresh token for a new pair, how each sign-in step refuses a bad request or an unexpected error, how many clients one address may register in an hour, how the host's sign-in finds the person a token acts for, how a person sees and disconnects the apps connected as them, how expired sign-in records are removed, and the vocabulary the install and develop locals assume.
 tools: Read
-scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools, the OAuth discovery documents, 401 challenge and client registration that let a client such as Claude's connector screen find the endpoint's sign-in and register by itself, with each client recording the address it registered from and a configurable limit on how many clients one address may register per hour past which registration is refused, and the approval page where a person signed in to the host through the browser approves that client and is issued an authorization code, the token exchange that trades that code with its PKCE verifier for an access token lasting an hour and a refresh token, the refresh exchange that trades a refresh token for a new access token and a new refresh token and retires the one posted, and the lookup a host's sign-in calls to get the person a bearer token acts for, which records when the connection was last used, and the settings section a host registers with settings_hub that lists a person's connections with the app's name, when it connected and when it was last used, and disconnects one that is the person's own, and the prune task a host schedules with its own job runner that removes expired authorization codes, connections whose access and refresh tokens have both expired, and clients over a day old with no connection
 ---
 
 This local explains hub_kernel-mcp and makes no changes.
@@ -20,24 +20,68 @@ wants an assistant to read or change that data on a person's behalf. Every call
 passes through the host's own sign-in first, then hub_kernel-interface's
 permission check and account scope, so a tool can do nothing the signed-in
 person could not already do. A boot check refuses to start a host whose served
-hubs cannot be turned into valid tool names.
+hubs cannot be turned into valid tool names, or whose browser settings for the
+approval page are not all set.
+
+The gem also lets a client set itself up from the endpoint's address alone. A
+refused request tells the client where the endpoint is described, two discovery
+documents name the endpoint's sign-in and its registration address, and the
+client registers itself there with its name and redirect addresses. The client
+then sends the person to an approval page in the host, where they sign in
+through the host's usual browser sign-in and approve or deny the client. An
+approval gives the client an authorization code, which it trades at the token
+address for an access token lasting an hour and a refresh token. When the
+access token runs out, the client trades the refresh token at the same address
+for a new pair, so the person does not approve the client again. The client
+sends the access token on every request, and the host's sign-in asks the gem
+which person the token acts for. A person using Claude's connector screen only
+pastes the endpoint's address.
+
+A person can see which apps are connected as them, and cut one off. The gem
+ships a section for a host's settings page, registered through settings_hub,
+that lists each of the person's connections with the app's name, when it
+connected and when it was last used, and a Disconnect button for each. A
+disconnected app's tokens stop working at once.
+
+Registration needs no sign-in, so the gem keeps it and the records it leaves
+bounded. One address may register only a set number of clients in an hour, ten
+unless the host changes it. The gem also ships a prune task that removes
+authorization codes, connections and clients that can no longer be used. The
+gem does not run the task itself, so the host schedules it with its own job
+runner.
 
 ## Interface
 
 This local declares no entry points of its own.
 
-- Adding the gem to a host, mounting the endpoint, configuring which controller
-  and which person and account methods it uses, and running the boot check are
-  owned by the install local, `hub_kernel-mcp-install`.
-- The endpoint itself and the MCP requests it answers are owned by the develop
-  local, `hub_kernel-mcp-develop`.
+- Adding the gem to a host, mounting the endpoint and the discovery documents,
+  installing the client, authorization code and connection tables, configuring
+  which controllers, person, account and sign-in methods and layout it uses,
+  setting the registration limit, running the boot check, calling the token
+  lookup from the host's sign-in, registering the connections section and its
+  disconnect action with settings_hub, and scheduling the prune task are owned
+  by the install local, `hub_kernel-mcp-install`.
+- The endpoint itself, the MCP requests it answers, the discovery documents,
+  the challenge on a refused request, client registration, the approval page,
+  the token exchange, the refresh exchange, how each of them refuses, and the
+  query for a person's connections are owned by the develop local,
+  `hub_kernel-mcp-develop`.
 
 ## How to use it
 
-- To put hub_kernel-mcp into a Rails app, or to fix a host whose boot check
-  fails, use `hub_kernel-mcp-install`.
-- To change what the endpoint answers, add support for another MCP request, or
-  change how tools are listed, called or refused, use `hub_kernel-mcp-develop`.
+- To put hub_kernel-mcp into a Rails app, to let a connector screen sign in to
+  it, to point the approval page at the host's browser sign-in and layout, to
+  make the host's sign-in accept the access tokens this gem issues, to add the
+  connected apps section to the host's settings page, to raise or lower how
+  many clients one address may register in an hour, to schedule the removal of
+  expired sign-in records, or to fix a host whose boot check fails, use
+  `hub_kernel-mcp-install`.
+- To change what the endpoint answers, add support for another MCP request,
+  change how tools are listed, called or refused, change what the discovery
+  documents and registration say, change what the approval page checks and
+  shows, change when a code or a refresh token is traded for new tokens, change
+  how long either token lasts, change how a sign-in step refuses, or change
+  which connections count as a person's own, use `hub_kernel-mcp-develop`.
 - To decide which hubs are served at all, or to change permissions and account
   scope, work in hub_kernel-interface, which owns the served list and those
   checks.
@@ -64,3 +108,80 @@ This local declares no entry points of its own.
   as the same JSON-RPC error, `Unknown tool`, so a caller cannot tell the two
   apart. An unexpected error is reported to the host's error reporting and its
   message is never sent to the client.
+- **Challenge** — the header added to every 401 the endpoint returns, pointing
+  the client at the document that describes the endpoint.
+- **Discovery documents** — two OAuth documents served at the site root. The
+  resource document names the endpoint's address and its sign-in, which is the
+  site root. The sign-in document names the registration, approval and token
+  addresses under the endpoint's address, names the authorization code and
+  refresh grants as the ones it accepts, and requires PKCE with SHA-256 and no
+  client secret.
+- **Client and registration** — a client is an app that registered itself by
+  posting its name and redirect addresses, and is answered with a client id.
+  Every redirect address must be HTTPS, or plain HTTP on the client's own
+  machine, and a registration with none or with any other address is refused
+  with the reason. A registration body that is not valid JSON is refused as
+  invalid client metadata.
+- **Registration limit** — each client records the address it registered
+  from. Once one address has registered as many clients in the last hour as the
+  limit allows, ten by default, its next registration is refused with status
+  429 and the reason, and no client is created.
+- **Browser side** — the approval page runs on a host controller meant for
+  people in a browser, separate from the endpoint's controller. The host names
+  that controller, the method that makes a person sign in, the method that
+  returns the signed-in person, and the layout the page renders in.
+- **Approval page** — shows which client wants to connect as the signed-in
+  person, with an approve and a deny button. A request missing its client id or
+  redirect address, naming a client that is not registered, or naming a
+  redirect address the client did not register gets an error page saying which,
+  and nothing is sent to any address. A request without a SHA-256 PKCE
+  challenge is sent back to the client as an invalid request. A denial is sent
+  back to the client as access denied.
+- **Authorization code** — what an approval sends back to the client's redirect
+  address, along with the client's state. It is tied to the person, the client,
+  the redirect address and the PKCE challenge, lasts ten minutes, and only a
+  digest of it is stored.
+- **Token exchange** — the client posts its client id, its code, its redirect
+  address and its PKCE verifier to the token address, with no sign-in. A code
+  that is unknown, expired, already traded, issued to another client, sent with
+  a different redirect address or with a verifier that does not match is refused
+  as an invalid grant. A code is traded once. A code posted a second time also
+  stops the access and refresh tokens already issued from it. A grant other than
+  the authorization code and refresh grants is refused as unsupported, and a
+  body that cannot be read is refused as an invalid request.
+- **Access token, refresh token and connection** — what a traded code is
+  answered with: a bearer access token that lasts an hour and a refresh token
+  that lasts ninety days. The pair is stored as a connection tying the person
+  and the client to a digest of each token, so neither token itself is stored.
+- **Refresh exchange** — the client posts its client id and its refresh token to
+  the token address, asking for the refresh grant, with no sign-in. It is
+  answered with a new access token and a new refresh token on the same
+  connection, and the new refresh token lasts another ninety days. The refresh
+  token posted and the access token it was issued with both stop working. A
+  refresh token that is unknown, already used, issued to another client, or
+  unused for ninety days is refused as an invalid grant, and of two refreshes
+  posting the same token at once only one succeeds.
+- **Unexpected error at a sign-in step** — an error nobody planned for at the
+  registration address, the token address or a discovery document is answered
+  with status 500 and a server error. On the approval page it shows the error
+  page instead. Either way its message is never sent to the client or shown to
+  the person, and it is reported to the host's error reporting.
+- **Token lookup** — what the host's sign-in calls with the bearer token from a
+  request. It gives the person the access token acts for while the token is
+  unexpired, and nothing for an expired, replaced or unknown token. Each lookup
+  that finds a person records the time on the connection as when it was last
+  used. The account a call is made in still comes from the host's account
+  method.
+- **Connections section** — the part of a host's settings page that lists the
+  signed-in person's connections, oldest first, each with the app's name, when
+  it connected, and when it was last used or that it was never used. It is
+  given the person and the address its Disconnect buttons post to.
+- **Disconnect** — the action a Disconnect button runs. It deletes the
+  connection, so both of its tokens stop working at once. A connection that is
+  not the person's own is left alone and the person is told it is not one of
+  theirs.
+- **Prune** — the task that removes sign-in records nothing can use any more:
+  authorization codes past their ten minutes, connections whose access token
+  and refresh token have both expired, and clients registered over a day ago
+  that hold no connection and no authorization code. A connection with either
+  token still working is never removed. The gem never runs it on its own.

data/the_local/agents/hub_kernel-mcp-install.md

@@ -1,8 +1,8 @@
 ---
 name: hub_kernel-mcp-install
-description: Use to hook hub_kernel-mcp into a project — adding the gem, naming the controller the endpoint inherits from and the person and account methods on it, running the boot check after the served list is set, and mounting the engine.
+description: Use to hook hub_kernel-mcp into a project — adding the gem, naming the controller the endpoint inherits from and the person and account methods on it, naming the browser controller, sign-in method, person method and layout the approval page runs with, running the boot check after the served list is set, mounting the engine, and, for sign-in from a connector screen, installing the migrations, mounting the discovery documents, setting how many clients one address may register per hour, having the host's sign-in look up the person an access token acts for, registering the settings section that lists a person's connections and disconnects one, and scheduling the task that prunes sign-in records.
 tools: Bash, Read, Edit
-scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools, the OAuth discovery documents, 401 challenge and client registration that let a client such as Claude's connector screen find the endpoint's sign-in and register by itself, with each client recording the address it registered from and a configurable limit on how many clients one address may register per hour past which registration is refused, and the approval page where a person signed in to the host through the browser approves that client and is issued an authorization code, the token exchange that trades that code with its PKCE verifier for an access token lasting an hour and a refresh token, the refresh exchange that trades a refresh token for a new access token and a new refresh token and retires the one posted, and the lookup a host's sign-in calls to get the person a bearer token acts for, which records when the connection was last used, and the settings section a host registers with settings_hub that lists a person's connections with the app's name, when it connected and when it was last used, and disconnects one that is the person's own, and the prune task a host schedules with its own job runner that removes expired authorization codes, connections whose access and refresh tokens have both expired, and clients over a day old with no connection
 ---
 
 This local follows these steps exactly and invents none. Where a step names a
@@ -11,9 +11,10 @@ decision, it asks the developer and does not pick.
 ## What hub_kernel-mcp is
 
 A Rails engine that serves every method the host's hubs expose as MCP tools at
-one JSON-RPC endpoint. Hook it in when the host already serves hubs through
-hub_kernel-interface and wants an MCP client to call them on a signed-in
-person's behalf.
+one JSON-RPC endpoint, with a browser page where a signed-in person approves a
+client such as Claude's connector screen. Hook it in when the host already
+serves hubs through hub_kernel-interface and wants an MCP client to call them on
+a signed-in person's behalf.
 
 ## Interface
 
@@ -22,7 +23,23 @@ person's behalf.
   `hub_kernel-interface` `~> 0.6`.
 - `mount HubKernel::Mcp::Engine` — mounts the endpoint in the host's
   `config/routes.rb` at the path given. The path answers POST with JSON-RPC and
-  answers GET with status 405.
+  answers GET with status 405. A client registers at `<path>/register`, a person
+  approves it at `<path>/authorize`, the client trades the approval's code for an
+  access token and a refresh token at `<path>/token` and later trades the
+  refresh token there for a new pair, and every 401 the endpoint answers carries a
+  `WWW-Authenticate` header pointing at the discovery documents.
+- `mount HubKernel::Mcp::Discovery` — mounts the two OAuth discovery documents
+  in the host's `config/routes.rb`. It must be mounted at `"/.well-known"`,
+  since the endpoint's 401 header names that path.
+- `bin/rails hub_kernel_mcp:install:migrations` — copies the gem's seven
+  migrations into the host's `db/migrate`. They create the
+  `hub_kernel_mcp_clients` table, which holds each client that registers, the
+  `hub_kernel_mcp_authorization_codes` table, which holds each code the
+  approval page issues, and the `hub_kernel_mcp_connections` table, which holds
+  each access token issued for a code. They then add the refresh token's
+  columns, a `last_used_at` column and an indexed `code_digest` column to
+  `hub_kernel_mcp_connections`, and a `registered_from` column, indexed with
+  `created_at`, to `hub_kernel_mcp_clients`.
 - `HubKernel::Mcp.base_controller=` — the name, as a String, of the host
   controller the endpoint inherits from. Its before-actions, including sign-in,
   run before any hub is asked. Defaults to `"ActionController::API"`, which has
@@ -31,12 +48,56 @@ person's behalf.
   base controller that returns the person a request is made for. No default.
 - `HubKernel::Mcp.account_method=` — the name, as a Symbol, of the method on the
   base controller that returns the account a request is scoped to. No default.
+- `HubKernel::Mcp.browser_controller=` — the name, as a String, of the host
+  controller the approval page inherits from. It must render HTML views, so it
+  is an `ActionController::Base` subclass. No default.
+- `HubKernel::Mcp.sign_in_method=` — the name, as a Symbol, of the method on the
+  browser controller that sends a person who is not signed in through the
+  host's sign-in. The approval page calls it with no arguments before anything
+  else. No default.
+- `HubKernel::Mcp.browser_person_method=` — the name, as a Symbol, of the method
+  on the browser controller that returns the signed-in person. That person must
+  be a record with a global id, since the issued code keeps the person by it.
+  No default.
+- `HubKernel::Mcp.browser_layout=` — the name, as a String, of the host layout
+  the approval page is shown in. No default.
+- `HubKernel::Mcp.registration_limit=` — the number, as an Integer, of clients
+  one IP address may register in the last hour. A registration past it is
+  answered with status 429 and `too_many_registrations`. Defaults to `10`.
 - `HubKernel::Mcp.check!` — the boot check. Raises
   `HubKernel::Mcp::UnservableHubError` when any served hub cannot be served as
-  tools, and returns nothing otherwise.
+  tools, or when any of the four browser settings is not set, and returns
+  nothing otherwise.
 - `HubKernel::Mcp::UnservableHubError` — the error `check!` raises. Its message
   names every problem found, one per line. It is the same class as
   `HubKernel::Interface::UnservableHubError`, so rescuing either catches it.
+- `HubKernel::Mcp::Connection.person_for` — takes the bearer token a client
+  sends, as a String, and returns the person who approved the client the token
+  was issued to. Returns `nil` for a token that is unknown, more than an hour
+  old, replaced by a refresh, or disconnected. Each time it returns a person it
+  records the time as the connection's last use. The host's sign-in on the base
+  controller calls it.
+- `SettingsHub.section` — settings_hub's call that registers a section on the
+  host's settings page. The host calls it once to register the connections
+  section, naming the partial and the action below.
+- `hub_kernel/mcp/connections` — the partial that lists the signed-in person's
+  connections, one per approved client, each with the app's name, when it
+  connected, when it was last used or `Never used`, and a Disconnect button. It
+  takes two locals: `person`, and `submit_url`, the address each button sends a
+  PATCH carrying `connection_id` to.
+- `HubKernel::Mcp::Disconnect` — the action the Disconnect button runs. It is
+  built with `new(person:, account:, values:)`, where `values[:connection_id]`
+  names the connection, and `call` returns a result. The result's `ok?` is true
+  when the person's own connection was removed, and false with a `message` of
+  `That connection is not one of yours` otherwise. A removed connection's access
+  and refresh tokens stop working at once.
+- `bin/rails hub_kernel_mcp:prune` — the task the host schedules. It runs
+  `HubKernel::Mcp::Prune.call` once and exits.
+- `HubKernel::Mcp::Prune.call` — removes authorization codes past their ten
+  minutes, connections whose access token and refresh token have both expired,
+  and clients created more than a day ago that have no connection and no
+  authorization code. A connection whose access token or refresh token still
+  works is never removed. Takes no arguments and returns nothing the host uses.
 
 ## How to use it
 
@@ -65,20 +126,41 @@ person's behalf.
    on the base controller or a class it inherits from. If either is missing,
    ask what it should return before adding it.
 
-4. Create `config/initializers/hub_kernel_mcp.rb` with the three answers:
+4. Ask the developer which host controller the approval page should inherit
+   from. It is the controller the host's browser pages use, usually
+   `ApplicationController`, and must be an `ActionController::Base` subclass.
+   Then ask for three names on it:
+
+   - the method that sends a person who is not signed in to the host's sign-in,
+     such as Devise's `:authenticate_user!`;
+   - the method that returns the signed-in person, such as `:current_user`;
+   - the layout the page is shown in, such as `"application"`.
+
+   All four are required, even when no connector screen will sign in: the boot
+   check names each one left unset, and the approval page's controller cannot
+   load without the browser controller. Do not choose any of them yourself.
+
+5. Create `config/initializers/hub_kernel_mcp.rb` with the answers from steps 2
+   to 4:
 
    ```ruby
    HubKernel::Mcp.base_controller = "Api::HubBaseController"
    HubKernel::Mcp.person_method = :current_person
    HubKernel::Mcp.account_method = :current_account
+
+   HubKernel::Mcp.browser_controller = "ApplicationController"
+   HubKernel::Mcp.sign_in_method = :authenticate_user!
+   HubKernel::Mcp.browser_person_method = :current_user
+   HubKernel::Mcp.browser_layout = "application"
    ```
 
    Set these in an initializer, not in `to_prepare`, so they are set before the
-   endpoint's controller loads. The controller name is a String. Leaving
-   `person_method` or `account_method` unset makes every `tools/list` and
-   `tools/call` request answer with JSON-RPC error -32603, `Internal error`.
+   gem's controllers load. Both controller names and the layout are Strings, and
+   the three method names are Symbols. Leaving `person_method` or
+   `account_method` unset makes every `tools/list` and `tools/call` request
+   answer with JSON-RPC error -32603, `Internal error`.
 
-5. Find where the host sets its served list, `HubKernel::Interface.hubs = [...]`,
+6. Find where the host sets its served list, `HubKernel::Interface.hubs = [...]`,
    inside `Rails.application.config.to_prepare`. Add `HubKernel::Mcp.check!` on
    the line after it, in the same block:
 
@@ -95,27 +177,209 @@ person's behalf.
    the developer that the hubs to serve are chosen in hub_kernel-interface
    first, and do not invent the list.
 
-6. Ask the developer what path to mount the endpoint at, then add the mount to
+7. Ask the developer what path to mount the endpoint at, then add the mount to
    `config/routes.rb`:
 
    ```ruby
    mount HubKernel::Mcp::Engine => "/mcp"
    ```
 
+8. Ask the developer whether a client such as Claude's connector screen should
+   find the endpoint's sign-in, register and be approved by a person, so a
+   person only pastes the endpoint's address. If not, stop here and skip steps
+   9 to 16.
+
+9. Copy the gem's migrations into the host and run them:
+
+   ```
+   bin/rails hub_kernel_mcp:install:migrations db:migrate
+   ```
+
+   This adds seven migrations to the host's `db/migrate` and the
+   `hub_kernel_mcp_clients`, `hub_kernel_mcp_authorization_codes` and
+   `hub_kernel_mcp_connections` tables to `db/schema.rb`. Commit all eight
+   files.
+
+10. Add the discovery mount to `config/routes.rb`, at the site root beside the
+    endpoint's mount, at exactly `"/.well-known"`:
+
+    ```ruby
+    mount HubKernel::Mcp::Engine => "/mcp"
+    mount HubKernel::Mcp::Discovery => "/.well-known"
+    ```
+
+    If the host already routes anything under `/.well-known`, show the developer
+    those routes and ask how to combine them before adding the mount.
+
+11. Ask the developer whether one IP address may register more or fewer than
+    ten clients an hour. Keep the default of `10` unless they name another
+    number, and if they do, add it to `config/initializers/hub_kernel_mcp.rb`:
+
+    ```ruby
+    HubKernel::Mcp.registration_limit = 20
+    ```
+
+    The limit counts clients by the address Rails reports as `request.remote_ip`.
+    If the host runs behind a proxy or load balancer that Rails does not trust,
+    every client is counted under the proxy's address and the limit is shared by
+    all of them. Ask the developer whether the host runs behind one, and if so
+    whether `request.remote_ip` already reports the caller's address, and do not
+    change the host's proxy settings yourself.
+
+12. Check how the base controller from step 2 refuses a caller who is not
+    signed in. A connector screen finds the sign-in only from a response with
+    status 401. If the controller redirects to a sign-in page or answers any
+    other status, tell the developer, and ask whether to change it to answer
+    401 for this endpoint.
+
+13. Check whether the base controller's sign-in accepts the access token a
+    connector screen sends on every request, as `Authorization: Bearer <token>`.
+    The gem issues the token but does not sign anyone in with it, so the base
+    controller's person method must look the token up:
+
+    ```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
+    ```
+
+    If the base controller already signs callers in another way, such as with
+    an API key, ask the developer whether a bearer token from
+    `HubKernel::Mcp::Connection.person_for` should be accepted in addition to
+    it or in its place, and do not choose. A `nil` from `person_for` must end in
+    a 401, as in step 12. Then check that the account method from step 3 returns
+    an account for a person signed in this way, since every call is made in that
+    account. If it reads the account from something a token request does not
+    carry, such as a session or a subdomain, tell the developer and ask what it
+    should return.
+
+14. Check the layout from step 4. The approval page runs inside the gem's
+    engine, so a route helper the layout calls for one of the host's own routes,
+    such as `root_path`, must be written `main_app.root_path`. If the layout
+    calls any host route helper without `main_app.`, show the developer each one
+    and ask whether to prefix them or to name a different layout.
+
+15. Ask the developer whether a person should see the apps connected as them
+    and be able to disconnect one, and whether the host's settings page is
+    built with settings_hub. If they want the section and the host uses
+    settings_hub, register it where the host registers its other settings_hub
+    sections:
+
+    ```ruby
+    SettingsHub.section :connections, area: :user, title: "Connected apps",
+      renders: "hub_kernel/mcp/connections", runs: "HubKernel::Mcp::Disconnect"
+    ```
+
+    Ask the developer for the title, and do not change `area: :user`, since the
+    list is the signed-in person's own. If the host has no settings_hub section
+    registered anywhere yet, ask where sections are registered before adding
+    one. If the host does not use settings_hub, ask the developer where the list
+    should appear, then render the partial there with the signed-in person and
+    a host route that accepts a PATCH:
+
+    ```erb
+    <%= render "hub_kernel/mcp/connections", person: current_user, submit_url: connections_path %>
+    ```
+
+    That route's action builds
+    `HubKernel::Mcp::Disconnect.new(person: current_user, account: nil, values: { connection_id: params[:connection_id] })`,
+    calls `call`, and shows the result's `message` when `ok?` is false. Ask the
+    developer for the route's path and where to send the person afterwards, and
+    do not choose either.
+
+16. Schedule the prune task with the host's own job runner. The gem schedules
+    nothing, so without this step expired codes, unusable connections and
+    unused clients stay in the database. Ask the developer which job runner the
+    host uses, such as Solid Queue's recurring tasks, cron or the hosting
+    platform's scheduler, and how often the task should run, and do not choose
+    either. The scheduled entry runs one of:
+
+    ```
+    bin/rails hub_kernel_mcp:prune
+    ```
+
+    ```ruby
+    HubKernel::Mcp::Prune.call
+    ```
+
+    Use the rake task where the runner runs a shell command, and the Ruby call
+    where it runs a job or a line of Ruby inside the app. For Solid Queue, the
+    entry goes in the host's `config/recurring.yml`, with the environment and
+    schedule the developer named in place of the ones shown:
+
+    ```yaml
+    production:
+      prune_hub_kernel_mcp:
+        command: "HubKernel::Mcp::Prune.call"
+        schedule: every day at 3am
+    ```
+
+    If the host already has a recurring-task file, add the entry beside the
+    others and show the developer where it went.
+
 ## Conventions
 
 - After installing, boot the app or run `bin/rails runner "HubKernel::Mcp.check!"`.
   An `UnservableHubError` there lists every problem to fix, one per line: a
   problem hub_kernel-interface's own check finds, a served name holding two
   underscores in a row, a tool name holding a character other than a letter, a
-  digit, an underscore or a hyphen, or a tool name longer than 64 characters.
-  A tool name is `<served name>__<method>`.
-- Fix a check failure by changing the served name or the hub method in the host,
-  never by removing the check. Inside `to_prepare` the check runs again after
-  every code reload.
+  digit, an underscore or a hyphen, a tool name longer than 64 characters, or a
+  browser setting that is not set. A tool name is `<served name>__<method>`.
+- Fix a check failure by changing the served name, the hub method or the
+  initializer in the host, never by removing the check. Inside `to_prepare` the
+  check runs again after every code reload.
 - Run the check again whenever the served list changes or a hub gains a method.
 - A change to `config/initializers/hub_kernel_mcp.rb` takes effect only after
   the app restarts.
+- With discovery installed, check it with
+  `curl -i -X POST <host>/mcp` while signed out: the response should be 401 with
+  a `WWW-Authenticate` header naming
+  `<host>/.well-known/oauth-protected-resource/mcp`, and a GET to that address
+  should name the endpoint.
+- With the approval page installed, open `<host>/mcp/authorize` in a browser
+  while signed out: the host's sign-in should take over. Signed in, the same
+  address with no query shows a page saying
+  `The approval request is missing client_id`.
+- With the token lookup installed, check it with
+  `bin/rails runner "p HubKernel::Mcp::Connection.person_for('unknown')"`,
+  which should print `nil`, and with `curl -i -X POST <host>/mcp` carrying
+  `Authorization: Bearer unknown`, which should answer 401.
+- Run `bin/rails hub_kernel_mcp:install:migrations` again after upgrading the
+  gem, then `db:migrate`. It copies only migrations the host does not have yet.
+  A host that installed an earlier version with fewer than seven migrations gets
+  the missing ones this way. Until they are run, the registration address or
+  the token address answers status 500 with `server_error`, or the token lookup
+  and the connections list fail on the missing `last_used_at` column.
+- With the prune task scheduled, run `bin/rails hub_kernel_mcp:prune` once by
+  hand. It prints nothing and exits 0. It removes only codes past their ten
+  minutes, connections with no working token, and clients over a day old with
+  no connection or code, so running it more often than scheduled is safe.
+- An unexpected error at the registration address, the token address, a
+  discovery document or the approval page is reported to the host's error
+  reporting through `Rails.error`, and its message is never sent to the client
+  or shown to the person. When a client reports `server_error` or the approval
+  page says `Signing in failed unexpectedly`, read the host's error reporting
+  for the cause.
+- With the connections section installed, sign in and open the settings page:
+  each app approved as that person is listed, a connection whose token has not
+  been looked up since the `last_used_at` migration ran shows `Never used`, and
+  Disconnect removes the row. A request with that connection's access token
+  then answers 401.
+- An access token lasts one hour. A refresh token lasts ninety days from when
+  it was issued, works only for the client it was issued to, and works once:
+  trading it retires it and the access token issued with it. A client that
+  lets its refresh token expire signs in again through the approval page.
+- A token issued before the refresh token migration was run has no refresh
+  token, so its client signs in again through the approval page once the
+  access token expires.
 - Out of scope: choosing which hubs are served and setting permissions and
-  account scope, which belong to hub_kernel-interface, and changing what the
-  endpoint answers, which belongs to `hub_kernel-mcp-develop`.
+  account scope, which belong to hub_kernel-interface, building the settings
+  page itself, which belongs to settings_hub, and changing what the endpoint,
+  the discovery documents, the approval page or the connections section
+  answer, which belongs to `hub_kernel-mcp-develop`.

data/the_local/interface.yml

@@ -1,13 +1,26 @@
-scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools, the OAuth discovery documents, 401 challenge and client registration that let a client such as Claude's connector screen find the endpoint's sign-in and register by itself, with each client recording the address it registered from and a configurable limit on how many clients one address may register per hour past which registration is refused, and the approval page where a person signed in to the host through the browser approves that client and is issued an authorization code, the token exchange that trades that code with its PKCE verifier for an access token lasting an hour and a refresh token, the refresh exchange that trades a refresh token for a new access token and a new refresh token and retires the one posted, and the lookup a host's sign-in calls to get the person a bearer token acts for, which records when the connection was last used, and the settings section a host registers with settings_hub that lists a person's connections with the app's name, when it connected and when it was last used, and disconnects one that is the person's own, and the prune task a host schedules with its own job runner that removes expired authorization codes, connections whose access and refresh tokens have both expired, and clients over a day old with no connection
 
 install:
   - gem "hub_kernel-mcp"
   - mount HubKernel::Mcp::Engine
+  - mount HubKernel::Mcp::Discovery
+  - bin/rails hub_kernel_mcp:install:migrations
   - HubKernel::Mcp.base_controller=
   - HubKernel::Mcp.person_method=
   - HubKernel::Mcp.account_method=
+  - HubKernel::Mcp.browser_controller=
+  - HubKernel::Mcp.sign_in_method=
+  - HubKernel::Mcp.browser_person_method=
+  - HubKernel::Mcp.browser_layout=
+  - HubKernel::Mcp.registration_limit=
   - HubKernel::Mcp.check!
   - HubKernel::Mcp::UnservableHubError
+  - HubKernel::Mcp::Connection.person_for
+  - SettingsHub.section
+  - hub_kernel/mcp/connections
+  - HubKernel::Mcp::Disconnect
+  - bin/rails hub_kernel_mcp:prune
+  - HubKernel::Mcp::Prune.call
 
 develop:
   - POST /
@@ -15,10 +28,41 @@ develop:
   - ping
   - tools/list
   - tools/call
+  - POST /register
+  - GET /authorize
+  - POST /authorize
+  - POST /token
+  - grant_type=refresh_token
+  - WWW-Authenticate
+  - GET /.well-known/oauth-protected-resource
+  - GET /.well-known/oauth-authorization-server
+  - HubKernel::Mcp::Connection.of
 
 sources:
   - lib/hub_kernel/mcp.rb
   - lib/hub_kernel/mcp/engine.rb
+  - lib/hub_kernel/mcp/discovery.rb
+  - lib/hub_kernel/mcp/challenge.rb
   - config/routes.rb
+  - db/migrate/20261007000000_create_hub_kernel_mcp_clients.rb
+  - db/migrate/20261008000000_create_hub_kernel_mcp_authorization_codes.rb
+  - db/migrate/20261009000000_create_hub_kernel_mcp_connections.rb
+  - db/migrate/20261009000001_add_refresh_token_to_hub_kernel_mcp_connections.rb
+  - db/migrate/20261009000002_add_last_used_at_to_hub_kernel_mcp_connections.rb
+  - db/migrate/20261009000003_add_code_digest_to_hub_kernel_mcp_connections.rb
+  - db/migrate/20261009000004_add_registered_from_to_hub_kernel_mcp_clients.rb
+  - app/models/hub_kernel/mcp/client.rb
+  - app/models/hub_kernel/mcp/authorization_code.rb
+  - app/models/hub_kernel/mcp/connection.rb
+  - app/models/hub_kernel/mcp/disconnect.rb
+  - app/models/hub_kernel/mcp/prune.rb
+  - lib/tasks/hub_kernel_mcp.rake
   - app/controllers/hub_kernel/mcp/messages_controller.rb
+  - app/controllers/hub_kernel/mcp/discovery_controller.rb
+  - app/controllers/hub_kernel/mcp/registrations_controller.rb
+  - app/controllers/hub_kernel/mcp/authorizations_controller.rb
+  - app/controllers/hub_kernel/mcp/tokens_controller.rb
+  - app/views/hub_kernel/mcp/authorizations/new.html.erb
+  - app/views/hub_kernel/mcp/authorizations/refused.html.erb
+  - app/views/hub_kernel/mcp/_connections.html.erb
   - README.md