Summary

Fixes #173

Native desktop OAuth clients (Cursor IDE, VS Code, Claude Desktop) use private-use URI schemes (RFC 8252) like cursor:// for redirect callbacks. The current url validation rule in OAuthRegisterController rejects these because PHP's filter_var(FILTER_VALIDATE_URL) only accepts http(s):// schemes. Additionally, validation errors return HTML redirects instead of JSON when the client sends Accept: */*.

Changes

• config/mcp.php — Add allowed_custom_schemes config array (empty by default, opt-in). Developers explicitly whitelist the schemes they need, preserving strict MCP spec compliance by default.
• OAuthRegisterController — Replace the url rule with a custom closure that accepts URIs whose scheme is in allowed_custom_schemes (validating that a host component is present), and falls back to standard filter_var URL validation otherwise. Replace $request->validate() with Validator::make() to guarantee a JSON 422 response regardless of the Accept header.
• RegistrarTest — 7 new Pest test cases covering custom scheme acceptance/rejection, edge cases, and the JSON error format fix.

Design decisions

• Opt-in by default: Empty allowed_custom_schemes preserves strict MCP spec compliance. No behavioral change for existing users.
• Explicit JSON responses: Validator::make() + manual response()->json() guarantees 422 JSON regardless of Accept header, fixing the HTML redirect bug.
• No domain checks on custom schemes: Custom scheme URIs bypass redirect_domains validation since domain semantics don't apply to private-use URI schemes.

Test plan

• Custom schemes accepted when configured (cursor://, vscode://, claude://)
• Custom schemes rejected when not configured
• Custom schemes rejected when a different scheme is configured
• Custom schemes with missing host component rejected
• Standard HTTP URLs still work alongside custom schemes
• JSON error response returned even with Accept: */* header
• All existing tests pass unchanged

Made with Cursor