agentleFS
Sign inStart free
ScaleDockHQScaleDockHQ/scaledock-skills/skills/mcp-authorization/SKILL.md

mcp-authorization

Skill1 starsChanged 31 days agoMITView on GitHub

MCP authorization: secure MCP servers with OAuth 2.1 as resource servers, and build MCP clients that discover, register and request audience-bound tokens. Use when adding or reviewing authorization on an HTTP MCP server, client, gateway or authorization server: 401 and 403 WWW-Authenticate challenges with resource_metadata, RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource, authorization server discovery through RFC 8414 or OpenID Connect Discovery, RFC 8707 resource indicators and audience validation, Client ID Metadata Documents (CIMD), pre-registration and deprecated Dynamic Client Registration (DCR), PKCE S256, insufficient_scope step-up and scope accumulation, RFC 9207 iss validation and mix-up attacks, Enterprise-Managed Authorization (ID-JAG, RFC 8693 token exchange, RFC 7523 JWT bearer), token passthrough, confused deputy, SSRF, and the MCP TypeScript SDK auth helpers (requireBearerAuth, OAuthClientProvider, CrossAppAccessProvider). Pins MCP revision 2026-07-28.

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Validate tokens (server): Check signature or introspection, expiry, audience and scopes on every request.

    line 48
  2. Very specific:

    Discover the authorization server (client): Follow the header or the well-known probe order, pick an authorization server, fetch its …

    line 51
  3. Very specific:

    Register the client: Use pre-registered credentials, then CIMD, then DCR, then ask the user, and key the result by issuer.

    line 54
  4. Distinctive:

    Map to the TypeScript SDK if it is used: Use the SDK's resource-server gate and client provider, and add the checks the SDK leaves to the …

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

MCP authorization

The Model Context Protocol (MCP) authorization specification defines how an HTTP MCP server acts as an OAuth 2.1 resource server and how an MCP client finds the authorization server, registers, and obtains a token bound to that one server. This skill pins MCP revision 2026-07-28 and produces a server, client or review that meets its MUST-level rules.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the page and heading it cites. MCP pages have no stable section numbers, so MCP rules cite the page and heading name; RFC and draft rules cite the section number. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

  • Role: MCP server (resource server), MCP client, authorization server, or an MCP server that also calls upstream APIs (a proxy or gateway).
  • Transport: Streamable HTTP or another HTTP transport (this skill applies), or STDIO (it does not; credentials come from the environment).
  • Enterprise: whether an enterprise identity provider (IdP) must control access, which brings in Enterprise-Managed Authorization.
  • Revision: MCP 2026-07-28, the revision the MCP Versioning page marks Current, unless the user names another.
  • Sources: when refreshing this skill or when a rule looks out of date, re-read the MCP Versioning page for a newer Current revision, then the changelog and Deprecated Features page of that revision, then every URL in Sources. Update the pins and bump the version.

Invariants

  1. Authorization applies to HTTP transports only. Authorization is OPTIONAL. HTTP-based implementations SHOULD conform to it, and STDIO implementations SHOULD NOT follow it and retrieve credentials from the environment instead (Authorization, Protocol Requirements).
  2. The server publishes Protected Resource Metadata. MCP servers MUST implement RFC 9728, and the document MUST list at least one authorization server in authorization_servers (Authorization, Overview; Authorization Server Discovery, Authorization Server Location).
  3. The server says where the metadata is. It MUST send resource_metadata in the WWW-Authenticate header of a 401 (RFC 9728 §5.1) or serve the metadata at a well-known URI. Clients MUST support both and use the header when present (Authorization Server Discovery, Protected Resource Metadata Discovery Requirements).
  4. Clients check the issuer of the metadata. The issuer in the authorization server metadata MUST be identical to the issuer used to build the metadata URL, or the client rejects it (Authorization Server Discovery, Authorization Server Metadata Discovery; RFC 8414 §3.3).
  5. Every token request names the MCP server. Clients MUST send resource in the authorization request and the token request, set to the canonical URI of the MCP server, whether or not the authorization server supports it (Authorization, Resource Parameter Implementation; RFC 8707 §2).
  6. The server accepts only its own tokens. Servers MUST validate access tokens per OAuth 2.1 §5.2, MUST validate that the token was issued for them as the audience (RFC 8707 §2), and MUST answer invalid or expired tokens with 401 (Authorization, Token Handling).
  7. No token passthrough. A server MUST NOT accept or transit any other token, and MUST NOT pass the client's token to an upstream API; it gets a separate token for the upstream (Authorization, Token Handling; Authorization Security Considerations, Access Token Privilege Restriction; Security Best Practices, Token Passthrough).
  8. Bearer header only. Clients MUST send Authorization: Bearer <token> on every HTTP request, and the token MUST NOT be in the query string (Authorization, Token Requirements).
  9. PKCE with S256. Clients MUST use PKCE, MUST use S256 when technically capable, and MUST refuse to proceed when the authorization server metadata has no code_challenge_methods_supported (Authorization Security Considerations, Authorization Code Protection).
  10. Validate iss before using the code. The client records the validated issuer with the PKCE verifier and applies RFC 9207 §2.4 to the authorization response before it sends the code to the token endpoint (Authorization, Authorization Response Validation).
  11. Credentials belong to one authorization server. Clients MUST key client credentials by issuer and MUST NOT reuse them with a different authorization server (Client Registration, Authorization Server Binding).
  12. HTTPS and exact redirects. Authorization server endpoints MUST use HTTPS; redirect URIs MUST be localhost or HTTPS, MUST be registered, and the authorization server MUST match them exactly (Authorization Security Considerations, Communication Security and Open Redirection).
  13. Proxies get consent per client. An MCP proxy server that uses a static client ID with a third-party authorization server MUST obtain user consent for each dynamically registered client before forwarding to the third party (Authorization Security Considerations, Confused Deputy Problem).

Workflow

  1. Scope the work. Confirm the role and transport from Inputs. For STDIO, stop: this skill does not apply. ✓ The design names the role, the HTTP transport and the canonical server URI.
  2. Publish Protected Resource Metadata and challenges (server). Serve RFC 9728 metadata, send 401 with resource_metadata and an initial scope, and send 403 insufficient_scope for per-operation scopes. -> references/resource-server.md ✓ An unauthenticated request gets a 401 whose header leads a client to the metadata, and the metadata lists an authorization server.
  3. Validate tokens (server). Check signature or introspection, expiry, audience and scopes on every request; map failures to 401 or 403. -> references/resource-server.md ✓ A token issued for another resource is rejected with 401, and no client token reaches an upstream API.
  4. Discover the authorization server (client). Follow the header or the well-known probe order, pick an authorization server, fetch its metadata in the defined order and check issuer. -> references/client-flow.md ✓ The client reaches the authorization server metadata from only the MCP server URL.
  5. Register the client. Use pre-registered credentials, then CIMD, then DCR, then ask the user, and key the result by issuer. -> references/client-flow.md ✓ The client_id in use was obtained for this issuer.
  6. Run the authorization code flow. Send PKCE S256, state, resource and the selected scopes; validate iss and state on the callback; send resource again in the token request. -> references/client-flow.md ✓ A callback with a wrong or missing iss is rejected according to the RFC 9207 table.
  7. Handle step-up. On 403 insufficient_scope, request the union of previously requested and newly challenged scopes, with a retry limit. -> references/client-flow.md ✓ A second scope challenge does not drop the scopes from the first.
  8. Add Enterprise-Managed Authorization if the IdP must control access. Exchange the IdP ID Token for an ID-JAG (RFC 8693), then the ID-JAG for an access token (RFC 7523). -> references/enterprise-managed-authorization.md ✓ The ID-JAG aud is the resource authorization server issuer and its resource is the MCP server.
  9. Review the attack surface. Go through confused deputy, token passthrough, SSRF, session handles, URL validation, mix-up, localhost redirects and scope minimization. -> references/security.md ✓ Each item in the security reference has a mitigation or a reason it does not apply.
  10. Map to the TypeScript SDK if it is used. Use the SDK's resource-server gate and client provider, and add the checks the SDK leaves to the app. -> references/typescript-sdk.md ✓ The app validates state itself and keys credentials by ctx.issuer.

Verify before done

  • GET on the metadata URL returns JSON with resource equal to the server's identifier and a non-empty authorization_servers (RFC 9728 §2, §3.3).
  • A request without a token gets 401 with WWW-Authenticate: Bearer resource_metadata="…".
  • A token whose audience is a different resource gets 401; a token without the needed scope gets 403 with error="insufficient_scope" and scope.
  • Authorization and token requests both carry resource with the canonical server URI, without a fragment or trailing slash.
  • The authorization request carries code_challenge_method=S256, and the client stops when the metadata lacks code_challenge_methods_supported.
  • The callback handler checks state and iss before the code exchange, and does not show error_description after an iss mismatch.
  • Client credentials are stored per issuer, and DCR is used only when neither pre-registration nor CIMD is available.
  • No code path forwards the incoming access token to another service.
  • Every outbound fetch of URLs taken from metadata or CIMD goes through the SSRF controls in the security reference.

Reference index

  • references/resource-server.md: Protected Resource Metadata, well-known URIs, 401 and 403 challenges, scope selection, token and audience validation, refresh token hints, error codes.
  • references/client-flow.md: discovery order, authorization server selection, CIMD, pre-registration and DCR, PKCE, resource, iss validation, step-up and scope accumulation.
  • references/enterprise-managed-authorization.md: the ext-auth Enterprise-Managed Authorization extension, ID-JAG token exchange, JWT bearer grant and discovery.
  • references/security.md: confused deputy, token passthrough, SSRF, session handles, local servers, URL validation, mix-up, localhost redirects, CIMD trust policies, scope minimization.
  • references/typescript-sdk.md: what the MCP TypeScript SDK v2 provides for servers and clients, and what it leaves to the app.

Related skills

  • oauth, for OAuth 2.1 and the RFCs this profile builds on: npx skills add ScaleDockHQ/scaledock-skills --skill oauth
  • jwt, for validating JWT access tokens and ID-JAGs: npx skills add ScaleDockHQ/scaledock-skills --skill jwt
  • problem-details, for error bodies next to 401 and 403 challenges: npx skills add ScaleDockHQ/scaledock-skills --skill problem-details

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free