​

@grantex/mcp-auth 3.0

Status. Version 3.0.0 is prepared in the repository and not yet published to npm. The current published release is @grantex/mcp-auth@2.0.2; its behaviour is described in the MCP Auth Server guide. Everything below describes 3.0.0 as built from source.

• Durable state. Clients, consent records, pending authorizations, authorization codes with their PKCE challenges, refresh-token bindings and revocations live in Postgres or Redis, so a restart or a second replica loses nothing.
• The current MCP authorization specification (2026-07-28): protected resource metadata (RFC 9728), resource indicators with audience binding (RFC 8707), PKCE S256 only, iss in authorization responses (RFC 9207), and OAuth Client ID Metadata Documents. A conformance suite maps each server-side MUST of the specification, plus the Security Best Practices’ confused-deputy requirements (consent and callback bound to the approving browser, CSRF-protected consent), to a test.
• A rendered consent page that shows purpose, tools, caps and duration before anything reaches Grantex, and a purpose that Grantex then binds the grant to.
• Tools refused at the MCP server, not merely hidden from tools/list, with scopes derived from Grantex tool manifests and a decision_required challenge for actions a person must approve.

​

How a request flows

1. An MCP client calls your MCP server without a token and receives 401 with WWW-Authenticate: Bearer resource_metadata="…".
2. It reads the protected-resource metadata, then this server’s authorization-server metadata.
3. It sends the user to /authorize with PKCE (S256) and resource. The client is either registered (dynamic registration or pre-registered) or identified by an https metadata-document URL.
4. /authorize validates the request and renders the consent page.
5. The Principal approves; only then does the server ask Grantex to authorize the grant, with the resource as its audience and grant.purpose as its purpose, and it sets a callback-binding cookie on that browser. The Principal may confirm again in Grantex.
6. Grantex redirects to /callback. Only if the browser presents the callback-binding cookie does the server issue a single-use code to the client’s redirect URI with iss.
7. The client redeems the code at /token (PKCE verifier, optional resource); the server exchanges the upstream code and returns the grant token only if its audience is the requested resource.
8. The MCP server’s requireMcpAuth verifies every request’s token (signature, issuer, audience, revocation) and refuses any tools/call the grant does not cover.

​

Install

git clone https://github.com/mishrasanjeev/grantex
cd grantex/packages/mcp-auth
npm ci && npm run build && npm pack

​

Deploying with Postgres

import pg from 'pg';
import { PostgresStorage, runMigrations } from '@grantex/mcp-auth/postgres';

export async function openPostgresStorage(databaseUrl: string) {
  const pool = new pg.Pool({ connectionString: databaseUrl, max: 10 });

  // Idempotent and serialised by an advisory lock, so every replica can run
  // it at start-up.
  await runMigrations(pool);

  const storage = new PostgresStorage({ db: pool });

  // Expired rows are already invisible to every read; purging bounds table size.
  const purge = setInterval(() => {
    storage.purgeExpired().catch((err: unknown) => console.error('mcp-auth purge failed', err));
  }, 5 * 60_000);
  purge.unref();

  return {
    storage,
    async close() {
      clearInterval(purge);
      await pool.end();
    },
  };
}

• Migrations ship in migrations/ (001_mcp_auth_state.sql). They are forward-only; runMigrations() applies each file once, in name order, in one transaction under an advisory lock, and records it in mcp_auth_schema_migrations. To use your own migration tool, apply the same files in name order and record them the same way.
• Tables: mcp_auth_clients, mcp_auth_pending_authorizations, mcp_auth_authorization_codes, mcp_auth_refresh_token_bindings, mcp_auth_consents, mcp_auth_revocations. Put them in a dedicated schema with the connection’s search_path if you share a database.
• Secrets at rest: codes, refresh tokens, consent ids and pending authorization ids are stored only as SHA-256 keys, and client secrets only as hashes. The record column holds binding data in clear JSON (client, redirect URI, PKCE challenge, scopes, resource) and, for an issued code, the upstream Grantex code for up to codeExpirationSeconds. That code is a single-use credential: restrict access to the tables and their backups.
• Single use is enforced with DELETE … RETURNING: of any number of concurrent redemptions of one code, exactly one succeeds.
• postgres (postgres.js) works through fromPostgresJs(sql).

​

Deploying with Redis

import { Redis } from 'ioredis';
import { RedisStorage, fromIoredis } from '@grantex/mcp-auth/redis';

export function openRedisStorage(redisUrl: string, keyPrefix = 'grantex:mcp-auth:') {
  // Redis 6.2 or later, with AOF or RDB persistence so client registrations
  // (stored without a TTL) survive a Redis restart.
  const redis = new Redis(redisUrl, { maxRetriesPerRequest: 2 });
  const storage = new RedisStorage({ redis: fromIoredis(redis), keyPrefix });

  return {
    storage,
    async close() {
      await redis.quit();
    },
  };
}

• Requires Redis 6.2 or later (GETDEL). Expiring records carry a matching PX TTL; the refresh-token take runs as a Lua script.
• Client registrations have no TTL: enable AOF or RDB persistence, or registered clients disappear with a Redis restart.
• Use a distinct keyPrefix per deployment when sharing an instance.
• node-redis works with { send: (command, args) => client.sendCommand([command, ...args]) }.

​

Operating it

• Replicas. Any number of processes can share one storage. Rate limits are per process (10/min for /authorize, 20/min for /token, /consent, /introspect, /revoke, 100/min otherwise); enforce global limits at your proxy.
• TLS and proxies. issuer must be the public https origin (http is accepted only for localhost). The consent form checks Origin against it, so a proxy must preserve the browser’s Origin and Sec-Fetch-Site headers.
• Grantex callback. Register {issuer}/callback (or callbackUrl) as a redirect URI on the Grantex agent.
• Storage failures refuse requests (500 at the authorization server, 503 from requireMcpAuth when revocation state is unreadable); they never grant access.
• InMemoryStorage (@grantex/mcp-auth/testing) is for tests and refuses to start with NODE_ENV=production.

​

Configuring the authorization server

import type { Grantex } from '@grantex/sdk';
import { createMcpAuthServer } from '@grantex/mcp-auth';
import type { LoadedManifest, McpAuthStorage } from '@grantex/mcp-auth';

export async function startAuthServer(options: {
  grantex: Grantex;
  storage: McpAuthStorage;
  manifest: LoadedManifest;
}) {
  return createMcpAuthServer({
    grantex: options.grantex,
    agentId: 'ag_acme_kyb_tools',
    storage: options.storage,

    // This authorization server, and the MCP server its tokens are for.
    issuer: 'https://auth.acme.example.com',
    resource: 'https://mcp.acme.example.com/mcp',
    resourceName: 'Acme KYB tools',
    grantexIssuer: 'https://grantex.dev',

    // scopes_supported and the consent page's tool list come from the manifest.
    manifests: [options.manifest],

    // What the grant is for, shown on the consent page. The purpose and
    // duration are sent to Grantex, which binds the grant to them.
    grant: {
      purpose: 'aml.cdd.onboarding',
      purposeDescription: 'Business onboarding checks for new applicants',
      duration: '8h',
    },

    consentUi: {
      appName: 'Acme Compliance',
      privacyUrl: 'https://acme.example.com/privacy',
      termsUrl: 'https://acme.example.com/terms',
    },
    consentPage: {
      theme: { accentColor: '#0b6e4f', radiusPx: 6 },
      text: { title: 'Allow case tools?', approve: 'Allow access' },
    },

    // Only accept metadata-document clients served from these hosts.
    clientIdMetadataDocuments: { allowedHosts: ['*.acme.example.com'] },
  });
}

​

Endpoints

​

Clients

• Client ID Metadata Documents (preferred by the specification). The client uses an https URL as client_id. The server fetches it with SSRF protections: only port 443 unless allowedPorts says otherwise; every address the host resolves to must be public (loopback, private, link-local, carrier-grade NAT, multicast, documentation, AS112, AMT, NAT64, 6to4 and IPv4-mapped ranges are refused) and the connection is pinned to the vetted address; redirects are not followed; the body is limited in size and time; the document must name its own URL as client_id, carry client_name and https or loopback redirect_uris, and use token_endpoint_auth_method: none. Results are cached per Cache-Control. Any failure is invalid_client with a reason code, never a redirect. Restrict hosts with allowedHosts.
• Dynamic registration (POST /register) remains for older clients. The client secret is returned once and stored as a hash.
• Pre-registered clients: write a ClientRegistration with storage.putClient() (use hashClientSecret() for a confidential client).

​

The consent page

• the application and the client (flagged when it identified itself with a metadata document, whose name is not verified);
• the host the Principal will be sent back to, prominently, with a warning when every redirect URI is on localhost;
• purpose and duration from grant. When grant.purpose is set, the page says that Grantex records the purpose on the grant; when it is not, the page says nothing about recording one. Either way it says that call limits are declared by the service and enforced only where the service applies them. The data region row always reads “None declared”, because a grant made through mcp-auth cannot carry a data region (see Purpose);
• the service (resourceName and resource);
• each tool the requested scopes cover with its permission and declared caps, and which tools need a decision grant;
• the scopes requested.

​

Customising it

import type { ConsentPageOptions } from '@grantex/mcp-auth';

export const consentPage: ConsentPageOptions = {
  lang: 'en-GB',
  theme: {
    accentColor: '#0b6e4f',
    textColor: '#111827',
    radiusPx: 4,
    fontFamily: 'Inter, system-ui, sans-serif',
  },
  text: {
    title: 'Allow case tools?',
    approve: 'Allow access',
    deny: 'Not now',
  },
  extraCss: '.card{box-shadow:0 1px 3px rgba(0,0,0,.12)}',
  // Replaces the "What you are granting" section. helpers.html escapes every
  // interpolated value; returning a plain string is refused.
  renderDetails: (model, { html }) => html`
    <section aria-labelledby="case-tools">
      <h2 id="case-tools">Case tools for ${model.purpose?.code ?? 'no declared purpose'}</h2>
      <ul>
        ${model.tools.map((tool) => html`<li>${tool.name}${tool.requiresDecision ? ' (needs approval per action)' : ''}</li>`)}
      </ul>
      <p>Access lasts ${model.duration ?? 'the default duration'}.</p>
    </section>`,
};

​

Protecting the MCP server

import express from 'express';
import { toolPolicyFromManifests } from '@grantex/mcp-auth';
import type { DecisionVerifier, LoadedManifest, RevocationChecker } from '@grantex/mcp-auth';
import { protectedResourceMetadataHandler, requireMcpAuth } from '@grantex/mcp-auth/express';
import type { McpAuthRequest } from '@grantex/mcp-auth/express';

export function createMcpApp(options: {
  manifest: LoadedManifest;
  /** The authorization server's storage: tokens revoked there are refused here. */
  revocations: RevocationChecker;
  decisions: DecisionVerifier;
  grantexIssuer: string;
}) {
  const resource = 'https://mcp.acme.example.com/mcp';
  const app = express();

  // RFC 9728: tells MCP clients which authorization server to use.
  app.get('/.well-known/oauth-protected-resource/mcp', protectedResourceMetadataHandler({
    resource,
    authorizationServers: ['https://auth.acme.example.com'],
    resourceName: 'Acme KYB tools',
  }));

  app.post(
    '/mcp',
    express.json(),
    requireMcpAuth({
      issuer: options.grantexIssuer,
      audience: resource,
      revocations: options.revocations,
      // A tools/call outside the grant is refused here with 403.
      tools: toolPolicyFromManifests([options.manifest]),
      // Tools marked requires_decision also need a person's decision grant.
      decisions: options.decisions,
    }),
    (req: McpAuthRequest, res) => {
      const message = req.body as { id?: unknown };
      // Only requests the grant covers reach your MCP handler.
      res.json({ jsonrpc: '2.0', id: message.id ?? null, result: { grantee: req.mcpGrant?.sub } });
    },
  );

  return app;
}

• Algorithms. Only RS256 and ES256. The algorithms option may narrow that to one of them; a list naming any other algorithm (PS256, EdDSA, HS256, …) throws when the middleware is created.
• typ. Must be at+jwt (or application/at+jwt). The auth service sets it on every grant token; only a pre-0.6 token (no urn:grantex:grant, with scp), issued before it did, may omit it.
• Grant tokens only. A token must carry urn:grantex:grant (0.6) or scp (before 0.6). The auth service’s OAuth access tokens, which are also at+jwt but carry only client_id, scope and a cnf.jkt, are refused.
• Scopes. Read from the space-delimited scope, falling back to scp when a 0.6 token omits scope (a grant with a scope containing whitespace). A pre-0.6 token is read from scp, because its scope was a lossy join. An empty scope (or scp: []) is an empty scope set, as the SDK verifiers read it: the token is admitted only where neither scopes nor tools requires a scope.
• Grant fields. agentDid, developerId, grantId and delegationDepth on the verified grant come from urn:grantex:grant, then from the legacy agt, dev, grnt and delegationDepth. A 0.6 token must name its agent and developer in one form or the other.
• Proof of possession is not checked. Validation step 5 of the profile requires a resource server to verify proof of possession when the token has cnf.jkt. The guard does not: a key-bound grant token is admitted as a bearer token. If your server needs sender-constrained tokens, verify the DPoP proof (RFC 9449) yourself and compare its key thumbprint with raw.cnf.jkt of the verified grant (req.mcpGrant, or c.get('mcpGrant') in Hono) before acting on the call.

​

Extension points

• Scopes from manifests. manifests (authorization server) and toolPolicyFromManifests() (MCP server) read plain manifest JSON in the 0.5 form ("tool": "read") and the 0.6 form ("tool": { "permission": "write", "caps": {…}, "requires_decision": true }), so a manifest loaded with the SDK’s 0.6 loader can be passed as its JSON. Each tool requires tool:<connector>:<permission>, honouring admin > delete > write > read. Duplicate tool names across manifests are refused unless you pass toolName.
• Decision grants. Every call to a requires_decision tool goes to the configured DecisionVerifier, which returns valid, absent or invalid with a sub-reason (action_mismatch, expired, consumed, same_approver). A verifier that returns valid must consume the decision grant atomically first, so one grant never authorises two calls; a batch with more than one such call is refused before any verifier runs. Without a verifier, such calls are refused:

import type { DecisionVerifier } from '@grantex/mcp-auth';

/**
 * Refuse every tool that declares requires_decision, for example on a
 * server that must never perform decisions. For Grantex decision grants use
 * grantexDecisionVerifier, which verifies and consumes them.
 */
export const decisionVerifier: DecisionVerifier = {
  async verify() {
    return { status: 'absent' };
  },
};

• Grantex decision grants. grantexDecisionVerifier(options) is the reference DecisionVerifier for decision grants issued by the Grantex auth service (spec/decision-grant.md). It reads one grant, or two comma-separated grants for a decision in four_eyes_on (the manifest’s or the grant’s urn:grantex:decision:v1 entry’s), from the grantex-decision-grant request header (header to change it); derives the semantic action from the tool name and the call’s case_id, decision, subject, amount and the manifest’s decision_fields; requires the access token’s developer (urn:grantex:grant.developer_id, or the legacy dev) and a connector from a manifest-derived tool policy (a call without either is refused as malformed); asks caseVersion(caseId, check) for the case’s current version from your own case state; verifies the grants with verify and consumes them with consume, answering valid only after the issuer confirmed consumption (consume_unavailable otherwise). Pass verifyDecisionGrants and (set, context) => grantex.decisions.consume(set, context) from @grantex/sdk 0.6 or later; they are injected so this package does not depend on an unreleased SDK. context is { agentDid, grantId, grantToken }: the agent (agt, its DID) and grant of the access token, and the access token itself as the guard verified it (check.grantToken). Pass it on, because an auth service with DECISION_GRANT_AGENT_BINDING=true establishes the calling agent from grantToken and consumes a decision requested for an agent only with that agent’s live grant token (wrong_agent otherwise). The token goes only to consume, and so only to the auth service that issued it. An SDK that predates agentDid or grantToken drops them and consumes as before, and an auth service with the binding off ignores them. Refusals carry the SDK’s sub-reason (action_mismatch, wrong_case, wrong_agent, case_changed, expired, consumed, same_approver, four_eyes_incomplete, malformed, …) in the decision_invalid body. Consumption spends the grant: if the tool call fails afterwards, a person has to approve again. The guard also reads the access token’s urn:grantex:decision:v1 entries (spec/grant-token-0.6.md): a tool listed there needs a decision grant even when its manifest does not declare requires_decision, and a token whose decision entries cannot be read is refused for every tools/call (decision_invalid / malformed_authorization_details).
• Authorize parameters. grant.authorizeParams returns extra parameters for the Grantex authorize call, for parameters a newer Grantex server accepts. It cannot override the agent, principal, scopes, audience, redirect URI, state or purpose: it may repeat grant.purpose, but a different purpose, or one when grant.purpose is unset, refuses the authorization with 500 server_error before Grantex is called. The purpose sent is always the one the consent page showed.

​

Purpose

​

Conformance

​

Migrating from 2.x

​

Known limitations

• The Grantex principal for every grant is the OAuth client_id, not the person who approved; all users of one client share it. See FINDINGS.md.
• A data region cannot be declared: grant.dataRegion is refused at start-up, because POST /v1/authorize takes no data region (see Purpose).
• A purpose outside the Grantex vocabulary is found only when Grantex refuses it, after the Principal approves the consent page, not at start-up (see Purpose).
• Rate limits are per process.
• onTokenIssued is declared but not called.