Skip to main content

​
Release and installation

Published release: @grantex/mcp-auth@4.0.0. Registry integrity, clean consumer flows, database/restart integration and Chromium tests were verified on September 29, 2026. This is the MCP Auth 4.0.0 deployment profile. Check Release Status for publication. Node.js 22.12+ and SDK 0.8.1+ are required. Version 2.0.2’s missing rendered page is historical; version 3 added the page, but used the OAuth client ID as the human principal. Version 4 closes that identity gap.

​
Human-confirmed request flow

  1. The MCP resource challenges unauthenticated calls and advertises resource metadata.
  2. The client discovers authorization metadata and starts authorization with PKCE S256 and the intended resource.
  3. The host authenticates the human. resolvePrincipal(request) derives a tenant-scoped external ID from verified host credentials, never client parameters.
  4. The server renders purpose, tools, declared limits, redirect destination and duration, with Allow and Deny. No upstream authorization occurs before approval.
  5. Approval rechecks the same human and browser/CSRF binding, then starts Grantex consent. Live Grantex consent still requires the principal’s passkey.
  6. The callback checks browser binding and the same authenticated principal before issuing a single-use code.
  7. Exchange checks PKCE, resource and Grantex’s returned principal subject. Refresh preserves that subject.
  8. The resource checks signature, issuer, audience, scopes, local revocation and online current-grant authority before execution. Sensitive actions require consumed, action-bound human decisions.
Logout or identity changes refuse approval/callback. A principal resolver or current-authority outage fails closed. The host owns login and session verification; the package cannot authenticate an unsigned identity assertion. See passkey registration.

​
Required resource enforcement

Configure both revocations and currentGrant: grantexCurrentGrantVerifier(grantex) in the resource guard or Express/Hono middleware. The latter calls the trusted issuer’s grantex.grants.verify on every protected request, without positive caching. Inactive authority returns 401; an issuer outage returns 503. It checks issuer-side current authority, not just a locally valid signature. Mark sensitive tools requires_decision and configure grantexDecisionVerifier with a trusted action resolver to consume decisions. Delegation consent alone does not approve every business decision. Four-eyes rules require the configured independent approvers. Never accept an agent’s claim that a human approved as decision evidence. /introspect requires confidential-client Basic authentication and checks current issuer authority by default. It reports inactive during an issuer outage. The warned allowUnauthenticatedIntrospection and introspectionCurrentGrant: 'none' options are evaluation-only, not recommended production configuration.

​
Deployment responsibilities

Revocation prevents subsequent requests; it cannot undo completed side effects or cancel a handler already executing. Data residency is not bound by this authorization endpoint. Gateway-wide rate limits, TLS and host session security remain deployment work.

​
Migration and validation

Read the complete deployment guide and enforcement migration. Drain pending requests, upgrade all replicas together and reauthorize old identity-unbound requests/refresh bindings. Do not mix v3/v4 against one state namespace. JSON binding fields do not need a new SQL schema; retain existing registered clients. allowLegacyClientPrincipal: true, currentGrant: 'none' and revocations: 'none' are explicit warned evaluation opt-outs, not production recommendations. Local memory storage is evaluation-only. The permanent suite covers identity switches, logout, denial, replay, concurrency, expiry, token subject substitution, issuer outage/revocation, Postgres/Redis restarts, Chromium layout and accessibility. Validate your actual MCP client, host sessions, TLS origin and live passkey ceremony before production. Independent cross-vendor or physical-authenticator certification is not claimed.
Last modified on September 29, 2026