> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Auth Server

> MCP Auth 4 binds rendered consent to the authenticated human and checks current grant authority before protected tool execution.

## Release and installation

Published release: `@grantex/mcp-auth@4.1.0`. Its npm archive matches the
validated CI artifact. The 4.0 database/restart and Chromium evidence remains
historical; 4.1 adds high-risk decision-grant handling.

This is the MCP Auth **4.1.0** deployment profile. Check
[Release Status](/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](/legacy/mcp-auth-server-2); version 3 added the page, but used the
OAuth client ID as the human principal. Version 4 closes that identity gap.

```bash theme={null}
npm install @grantex/mcp-auth@4.1.0 @grantex/sdk@0.8.2 pg
```

## 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](/features/fido-webauthn).

## 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

| Concern | Version 4 behavior | Operator responsibility |
| - | - | - |
| Human identity | Required resolver, repeated at approval/callback | Verify login/session and namespace IDs by tenant |
| Consent | Rendered, single-use, browser/CSRF/principal bound | Configure truthful purpose, terms and labels |
| State | Postgres/Redis adapters and atomic consumption | Provision durable shared state and migrations |
| Tokens | PKCE/resource/principal binding through exchange/refresh | Protect credentials and shared state |
| Revocation | Explicit local checker and current issuer verification | Connect both sources; deny outages |
| Decisions | Decision-required tools fail closed without a verifier | Bind trusted semantic actions and consume approvals |
| Limits | Caps are displayed as declared | Apply SDK enforcement and atomic service accounting before side effects |

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](/mcp-auth) and
[enforcement migration](/migration-enforcement). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.