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:- Extracts the bearer token from the
Authorization: Bearer ...header. - Verifies the JWT signature against a cached JWKS (refreshes on
kidmiss and at the configured cache TTL).EdDSA,ES256andRS256are accepted; RSA keys must be at least 2048 bits and the key type must match the headeralg. - Enforces the
audclaim against the resource URI passed tomcpresource.New.audmay be a string or an array. - Checks
exp,nbf, andiatwith a 60-second clock skew tolerance (configurable). - If a
RevocationCheckeris installed (see below), asks it whether the token was revoked. A revoked token, or a checker error withoutWithRevocationFailOpen, gets a 401. - For tokens that carry an
actclaim or adelegation_grant_id, calls AS introspection and rejects the request if the AS reportsactive: 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 shorterCache-Control: max-agethe AS returns. - 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 afterv.Middleware:
See Protect MCP tools for examples and the limits of each.
Options
Which options you need
NeitherWithJWKS 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 usesync.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
Seeexamples/mcp-server/ for a complete standalone demo.