Skip to main content
The mcpresource module is a zero-dependency Go module for MCP resource servers. It validates bearer JWTs, enforces audience claims, checks RFC 8693 actor chains and delegation grants through AS introspection when a token carries them, and emits the correct WWW-Authenticate response on failure.

Install

mcpresource has no third-party dependencies. Importing it does not pull in theauth core or any storage adapter.

Wire the middleware

What the middleware validates

On every request the middleware:
  1. Extracts the bearer token from the Authorization: Bearer ... header.
  2. Verifies the JWT signature against a cached JWKS (refreshes on kid miss and at the configured cache TTL). EdDSA, ES256 and RS256 are accepted; RSA keys must be at least 2048 bits and the key type must match the header alg.
  3. Enforces the aud claim against the resource URI passed to mcpresource.New. aud may be a string or an array.
  4. Checks exp, nbf, and iat with a 60-second clock skew tolerance (configurable).
  5. If a RevocationChecker is installed (see below), asks it whether the token was revoked. A revoked token, or a checker error without WithRevocationFailOpen, gets a 401.
  6. For tokens that carry an act claim or a delegation_grant_id, calls AS introspection and rejects the request if the AS reports active: false, for example because a delegation grant was revoked. Tokens with neither claim are not introspected. Introspection results are cached for the cache TTL, or for the shorter Cache-Control: max-age the AS returns.
  7. On any failure: emits HTTP 401 with WWW-Authenticate: Bearer error="invalid_token", resource_metadata="..." per RFC 6750 and RFC 9728.

The Principal type

Per-tool guards and tool metadata

Mount these after v.Middleware: See Protect MCP tools for examples and the limits of each.

Options

Which options you need

Neither WithJWKS nor WithIntrospection is required on its own, but with neither set the validator rejects every token and Validator.Diagnostics() reports no-verification-source. Log the diagnostics at startup. With WithJWKS only, tokens are validated offline (signature, audience, expiry). That path cannot see revocation: a revoked token stays valid until exp. Add WithIntrospection so act and delegation_grant_id tokens are checked against the AS, and add WithRevocationChecker or WithDeviceRevocationIntrospection for tokens revoked before exp.

Concurrent safety

The JWKS and introspection caches use sync.RWMutex internally so concurrent reads do not serialize. Cache writes (on miss or TTL expiry) take a write lock for the minimum duration.

Runnable example

See examples/mcp-server/ for a complete standalone demo.
Last modified on October 17, 2026