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.

---