Add registry authorization specification

[domdomegg]

Add a standardized OAuth 2.1-based authentication specification for MCP sub-registries, aligned with the MCP Authorization Specification.

This enables:

• Private registry entries with access control
• Permission-based server visibility
• Client code reuse (clients can use their existing MCP auth implementation)

The spec is intended for downstream sub-registries. The official registry remains public for reading.

Fixes #751

[domdomegg]

@claude please review

[claude]

Claude finished @domdomegg's task —— View job

---

Review: Registry Authorization Specification

Overall this is a well-designed specification that aligns closely with OAuth 2.1 standards and provides a clear path for private registry implementations. The approach of reusing the MCP Authorization Specification pattern is smart and maintains consistency across the ecosystem.

✅ Strengths

• Excellent reuse of existing standards: Leveraging the MCP Authorization Specification means clients can reuse existing auth code without modification
• Proper OAuth 2.1 compliance: Correctly specifies PKCE with S256, resource parameter (RFC 8707), and security best practices
• Clear scope hierarchy: Well-defined precedence for scope selection (WWW-Authenticate → Protected Resource Metadata → omit)
• Step-up authorization: Properly handles insufficient scope scenarios with 403 responses and retry mechanisms
• Good separation of concerns: Clearly distinguishes this is for sub-registries, not the official registry
• Security-first approach: Mandates bearer tokens in headers only, no query string tokens

🔍 Technical Issues Found

Line 153: Typo

Reading servers remaings public and does not require authentication.

Should be: Reading servers remains public

Lines 26-33: WWW-Authenticate Header Format

The multiline header format may not be standard. Consider:

WWW-Authenticate: Bearer realm="MCP Registry", scope="registry:read", resource_metadata="https://registry.example.com/.well-known/oauth-protected-resource"

Lines 137-141: Step-up Response Format

Same formatting concern for the step-up response. Single line may be more compliant.

💡 Suggestions for Improvement

1. Error Handling Detail

Consider adding guidance on handling network failures, token refresh, and authorization server unavailability.

2. Token Lifecycle Management

The spec could benefit from guidance on:

• Token expiration handling
• Refresh token usage (if supported)
• Token revocation scenarios

3. Registry Discovery Enhancement

Consider specifying how clients discover if a registry supports this auth spec vs. other auth methods, especially for migration scenarios.

4. Example Expansion

The permission-based server visibility example (lines 120-131) could show the complete flow including the filtered response.

5. Security Considerations

Consider adding explicit mention of:

• Rate limiting on auth endpoints
• Protection against authorization code interception
• Recommended token lifetime limits

📋 Minor Items

1. Line 35: Consider clarifying "for compatibility with the MCP spec" - which specific compatibility concern?
2. Lines 108-113: The scope naming follows a good pattern, but consider mentioning if custom scopes should follow any naming convention
3. Line 163: The issue reference is helpful for context

Todo List

• Read and analyze all changed files
• Review the authorization specification for technical accuracy
• Check OAuth 2.1 compliance and MCP alignment
• Provide comprehensive review feedback

Summary

This is a solid specification that successfully addresses issue #751's requirements. The technical approach is sound, properly leveraging OAuth 2.1 standards while maintaining consistency with existing MCP patterns. The main issues are minor (one typo, header formatting) and could be addressed in follow-up commits.

The design properly enables private registry entries with permission-based visibility, exactly as requested. The reuse of existing MCP auth patterns is particularly smart for client adoption.

---

[rdimitrov]

Looks good to me 🚀 I think we are all in favour of keeping it as close to the existing MCP spec as possible but let's wait a few more days so others can chime in if needed 👍

[domdomegg]

Just wanting to also get the opinions of a few security professionals in Anthropic as well, will merge pending their review.

[henrythe9th]

OAuth 2.0+ or 2.1 as it's 2.1 everywhere else

[domdomegg]

Fixed! And simplified this in general to avoid discrepancies like these.

[henrythe9th]

is there a benefit (or con) for not keeping the official registry in sync with this spec?

[domdomegg]

Main benefit is that people only need to implement one auth spec consistently across servers and registries. Most MCP clients will already have all the code for handling the MCP auth spec, so if we reuse that they get registry auth for free.

There's no particular con from keeping them synced, except for potentially that the MCP auth spec is a little more complex than say a username/password or fixed API key (although roughly equivalent things can be achieved with the client credentials grant OAuth flow).

[cjellick]

What's the function of this field? Does this need to map to a scope in the token?

[domdomegg]

Have removed this - not actually necessary.

[domdomegg]

Okay, after security review basically everyone seems happy with this, except with the recommendation to slim this spec down to just pointing at the main MCP spec. This avoids duplication and reduces the change of inconsistencies between the specs.

Have enabled auto-merge so this goes in once someone GitHub stamps :)