MCP Server Authorization with OAuth 2.1 and Grantex

Current MCP HTTP authorization, the OAuth 2.1 draft profile, and safe evaluation limits for @grantex/mcp-auth 2.0.2.

Release status — updated July 12, 2026: @grantex/mcp-auth@2.0.2 exposes useful OAuth endpoint and token-validation building blocks, but it is single-process evaluation software. It is not a complete implementation of the current MCP HTTP authorization specification. The MCP Auth feature guide is the authoritative package reference.

Remote MCP servers often need transport-level authorization before a client can call sensitive tools. The current MCP authorization specification defines an optional authorization flow for HTTP-based transports. It profiles a selected set of OAuth standards, including OAuth 2.0 Protected Resource Metadata (RFC 9728), authorization-server discovery, resource indicators, access-token audience validation, and an OAuth 2.1 authorization-code flow.

OAuth 2.1 is still an IETF Internet-Draft, not a published RFC. In this article, “OAuth 2.1” means the draft-based profile required by the current MCP HTTP authorization specification. Authorization is optional in MCP, and the HTTP flow is not the credential model for local STDIO servers.

Short answer: for production, use an established, MCP-compatible authorization server for the HTTP OAuth flow. Then enforce agent-specific Grantex grants again at each sensitive tool or service boundary.

MCP authorization and Grantex solve different layers

MCP HTTP authorization establishes whether an MCP client may access a protected MCP resource on behalf of a resource owner. Grantex can add a narrower decision at tool execution time: which agent may perform which action, for which principal and resource, under which constraints.

A production architecture should keep those responsibilities explicit:

1. Established authorization server: use a maintained authorization server that supports the current MCP profile, user authentication and consent, durable authorization-code state, secure client onboarding, token issuance, and revocation.
2. MCP protected resource: expose RFC 9728 protected-resource metadata, advertise the permitted authorization server, and validate every access token’s issuer, audience, expiry, and required MCP scopes.
3. Grantex tool enforcement: after transport authorization succeeds, use a primary Grantex SDK or direct, validated grant verification at each sensitive tool boundary. Bind the decision to the agent, principal, action, resource, constraints, and current revocation state.
4. Audit and deny safely: record both the transport authorization context and the tool-level Grantex decision. Deny the call if either layer fails.

This makes Grantex complementary to the MCP authorization server; it does not ask @grantex/mcp-auth@2.0.2 to serve as the production OAuth control plane.

What @grantex/mcp-auth 2.0.2 implements

For local inspection, createMcpAuthServer() returns a Fastify instance with these six routes:

Endpoint	Implemented behavior
/.well-known/oauth-authorization-server	Authorization-server metadata discovery
/register	Dynamic client registration backed by ClientStore
/authorize	PKCE S256 plus client and redirect-URI validation, followed by a Grantex authorization request
/token	PKCE validation plus Grantex exchange and refresh calls
/introspect	JWT signature and claim validation against JWKS
/revoke	Decode the JWT jti and request Grantex revocation

The package also exports Express and Hono middleware that validates JWT signatures, claims, algorithms, expiry, and required scopes. This endpoint surface does not itself provide the MCP server’s RFC 9728 protected-resource metadata or make the end-to-end flow conformant with the current MCP authorization specification.

Reproducible evaluation install

Use exact package versions and commit both package.json and the generated lockfile:

npm install --save-exact @grantex/mcp-auth@2.0.2 @grantex/sdk@0.3.13

Use Node.js 18 or newer. After the lockfile is committed, reproduce the same dependency graph in CI with:

npm ci

Do not replace the version pins with latest in an evaluation record.

Start the evaluation endpoint surface

import { Grantex } from '@grantex/sdk';
import { createMcpAuthServer } from '@grantex/mcp-auth';

const grantex = new Grantex({
  baseUrl: 'https://api.grantex.dev',
  apiKey: process.env.GRANTEX_API_KEY!,
});

const authServer = await createMcpAuthServer({
  grantex,
  agentId: 'ag_your_mcp_server',
  scopes: ['tools:read', 'tools:execute'],
  issuer: 'https://your-auth-server.example.com',
});

await authServer.listen({ port: 3001 });

This starts the published endpoint surface for inspection. It does not create a production MCP authorization deployment or prove end-to-end token issuance.

Six material limits in 2.0.2

1. Process-local state: client registrations use process memory unless you provide a ClientStore, and authorization codes always use the non-configurable InMemoryCodeStore. Restarts and multi-replica authorize/token flows are unsafe.
2. No consent page: consentUi adds discovery metadata only. The package does not register /consent or render a user-approval interface.
3. Incomplete code handoff: the package does not persist the authorization code returned by the Grantex SDK for the token handler. A real backend exchange can therefore fail.
4. Inactive issuance hook: the onTokenIssued type is declared but the hook is not invoked in 2.0.2.
5. No current revocation lookup: introspection and middleware perform local JWT validation but do not query current revocation state. Use an online state check or synchronized revocation data when immediate revocation matters.
6. No server-wide redirect allowlist: allowedRedirectUris is declared but is not enforced as a server-wide allowlist in this release. Authorization checks the redirect URI registered for the individual client instead.

Evaluation-only middleware boundary

import { requireMcpAuth } from '@grantex/mcp-auth/express';

app.use('/mcp', requireMcpAuth({
  issuer: 'https://your-auth-server.example.com',
  scopes: ['tools:execute'],
}));

This middleware performs local signature, claim, algorithm, expiry, and scope checks. It is not protected-resource discovery, a live revocation check, user consent, or tool-level agent authorization.

Production checklist

• Follow the current MCP HTTP authorization specification rather than treating an older endpoint list as the protocol.
• Use an established authorization server and maintained MCP SDK, with exact versions pinned in your own lockfile.
• Publish and validate RFC 9728 protected-resource metadata for the actual MCP resource identifier.
• Validate issuer, audience, expiry, scopes, and revocation before accepting the transport token.
• Enforce the narrower Grantex grant at every sensitive tool or downstream service boundary.
• Test denial paths, consent, authorization-code replay, redirect URIs, multi-replica state, token expiry, and revocation end to end.

Related documentation

• MCP Auth Server package status
• Grantex release status
• MCP tool-server integration
• Self-hosting guide
• Current MCP HTTP authorization specification
• OAuth 2.1 Internet-Draft status