How the authorization flow works
- Discover: The MCP resource challenges the client and advertises its authorization metadata.
- Identify: The host authenticates the human. A required principal resolver derives a tenant-scoped identity from that verified session.
- Approve: The server renders the requested purpose, tools, limits, redirect destination, and duration. The human chooses Allow or Deny; approval is bound to the browser and principal.
- Issue: After approval and Grantex consent, the authorization code is exchanged with PKCE, resource, and principal checks. Live Grantex consent requires the principal's passkey.
- Enforce: Before a protected tool runs, the resource checks signature, issuer, audience, scopes, local revocation, and current grant authority.
A valid grant authorizes a class of actions. For sensitive business decisions, configure a trusted, action-bound human decision verifier before execution.
What the host must provide
| Boundary | Package behavior | Host responsibility |
|---|---|---|
| Human identity | Rechecks the required principal resolver at approval and callback. | Authenticate the human and verify the session. Client IDs and agent text are not human identity. |
| Consent | Renders Allow and Deny with browser, CSRF, and principal binding. | Configure truthful tool labels, purpose, duration, and passkey enrollment for live Grantex consent. |
| State | Supports durable shared storage and atomic consumption. | Provision Postgres or Redis adapters and run the documented migrations. |
| Current authority | Can check the issuer's current grant state on every protected request. | Configure both local revocation checks and the trusted current-grant verifier; outages fail closed. |
| Sensitive actions | Can require and consume action-bound decisions. | Define trusted action data and independent approvers where policy requires them. |
| Spend and audit | Displays declared limits and exposes authorization hooks. | Enforce atomic spending at the service boundary and record actual tool execution separately. |
Install the published release
Use Node.js 22.12+ and the current Grantex SDK. The database adapter is an explicit deployment dependency.
npm install @grantex/mcp-auth@4.1.0 @grantex/sdk@0.8.2 pgFollow the complete deployment guide for the principal resolver, consent route, shared storage, resource binding, and current-grant verifier. The host still owns human login and session security.
Checks to run before protecting real tools
- Switch or log out the human between request and approval; the approval must fail.
- Try a replayed code, wrong resource, wrong principal, and missing PKCE verifier; each must fail.
- Revoke or expire a grant, then call the protected tool; the action must not run.
- Stop the issuer's current-authority service; protected requests must fail closed.
- Restart every replica and confirm pending state behaves as documented.
- Test the actual MCP client, TLS origin, host login, and live passkey ceremony.
Package tests cover these classes of denial and restart behavior. Your deployment still needs its own integration tests. Independent cross-vendor certification is not claimed.
Choose the right integration layer
MCP transport authorization controls access to the resource. Grantex adds the agent, human principal, grant, scope, and current authority at the protected tool boundary. The MCP integration guide and authorization comparison explain the distinction.
Common MCP authorization questions
Does MCP transport authorization prove what an agent may do?
No. It establishes client access to the HTTP resource. The protected tool must separately verify the acting agent's grant, principal, audience, exact scope, and current authority before execution.
Does MCP Auth authenticate the human?
No. The host application must authenticate the human and pass a verified, tenant-scoped identity through the required principal resolver. A client ID or a user name supplied by the agent cannot stand in for the human.
Is the HTTP authorization flow required for a local stdio MCP server?
No. MCP's HTTP authorization profile is transport-specific. A local stdio deployment obtains credentials through its host environment; it still needs agent-specific checks at a protected tool boundary. See the MCP authorization specification.