Allow dynamic ports for localhost redirect domains

[dylanbr]

CLI agents like Claude Code, Codex CLI, and so on, will authenticate using the OAuth 2 /register endpoint if given a laravel/mcp URL. By default, however, they do not use a static port for their redirect URL, and will instead use a randomly allocated port with a URL like http://localhost:60000/callback or http://127.0.0.1:50000/callback.

Currently it is only possible to allow * any redirect domain, or a list of allowed domains with static hostnames, ports and paths. No dynamic parts are supported.

While it would be possible for a bad actor to use localhost redirect domains with dynamic ports to their advantage, it is less of a problem than allowing * any redirect domain. The person / project integrating laravel/mcp should be able to make this decision for themselves.

After some consideration, I have identified a few different potential solutions, all with their own pros and cons:

1. Allow * wildcards within each redirect_domains entry. This would allow any part of the redirect URL to be dynamic. However, it is likely the most difficult to implement securely, because it would require a custom URL parser that supports wildcards.
2. Allow structured entries in redirect_domains which specify different parts of the URL and whether they should be static, dynamic or allow wildcards. To implement this, parse_url or Uri would be used on the requested URL, and then compared component by component with the structured entry. eg. ['scheme' => 'http', 'host' => 'localhost', 'port' => '*']. This avoids needing to parse the redirect_domans URLs, and allows for wildcards in any component.
3. Instead of changing the processing of redirect_domains, instead add a new configuration entry for allow_local_with_any_port. When this is true, any URL with host localhost, 127.0.0.1, or [::1] would be allowed, regardless of the port. This is probably the easiest to implement, but is also the least versatile.
4. Allow closure entries in redirect_domains which are given either the raw redirect URL, or an already parsed Uri, and the closure code can determine if the given URL should be allowed.

The existing string based redirect_domains entries can be kept for backwards compatibility. It would also be possible to implement more than one of these, say 2 and 4, for the most flexibility.

I am more than happy to put together a PR implementing this change, but I first wanted to get feedback from the maintainers and community on what they think would be the best approach.

Let me know your thoughts.

[pushpak1300]

Hey @dylanbr, thanks for the detailed write-up!

Just want to understand the use case better. For most setups:

• Local dev → * works fine, CLI tools work out of the box
• Production → explicit domains like https://myapp.com/callback for web app clients

So the scenario you're describing is a production MCP server where CLI tools are the primary clients — where you want to allow localhost redirects (for the CLI) but not open it up to arbitrary domains?

Just want to make sure we're solving a real problem before adding complexity.

[dylanbr]

So the scenario you're describing is a production MCP server where CLI tools are the primary clients — where you want to allow localhost redirects (for the CLI) but not open it up to arbitrary domains?

Correct. Although there is the possibility, in the future, that I'd want both the localhost redirects and some explicitly defined domains as well. This would be to support both users running agents on their local machines, and agents running in the cloud on specific domains.

I don't like using * and allowing everything, because of how easy that would make it for a malicious user to write a script to steal user tokens on their own domain.

[pushpak1300]

My understanding is that for local testing this isn’t usually a blocker unless you’re using /oauth/register for dynamic client registration. In a local environment we can keep redirect_domains as * . Stricter domain restrictions are mainly important for production where we should only allow trusted redirect domains. You can just add env variable for this so on different envs you can set the value you like ? am i correct ?

[bilfeldt]

My understanding is that for local testing this isn’t usually a blocker unless you’re using /oauth/register for dynamic client registration.

Maybe I am missing something, but when would you not use Dynamic Client Registration when using Passport as auth for an online MCP? 🤔

Btw it seems from Anthropic's Remote MCP Server Submission Guide that the local host port might be a fixed port now, since only port 6274 is listed as a required redirect:

OAuth implementation requirements:

• Must use OAuth 2.0 authorization code flow
• Certificates from recognized authorities
• Allowlist local MCP client (e.g. Claude Code, MCP Inspector) callback URLs:
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug
• Allowlist Claude callback URLs:
  • https://claude.ai/api/mcp/auth_callback
  • https://claude.com/api/mcp/auth_callback

[pushpak1300]

Okay, it makes sense now.

The most practical first step is to implement a minimal non-breaking option. This involves adding an opt-in configuration flag like allow_localhost_dynamic_port (defaulting to true) while retaining the existing redirect_domains behaviour.

When enabled, this option would allow only loopback redirect URIs with dynamic ports, such as localhost, 127.0.0.1 or ::1. However, all other traffic would still need to pass the current allowlist checks. This approach solves the CLI random-port issue without exposing the system to potential vulnerabilities like *.

This solution appears safer and simpler than full wildcard URL matching and avoids the complexity of custom rule closures in the configuration. If there’s interest, we can always develop a more structured matching system as a follow-up.

[dylanbr]

When enabled, this option would allow only loopback redirect URIs with dynamic ports, such as localhost, 127.0.0.1 or ::1. However, all other traffic would still need to pass the current allowlist checks. This approach solves the CLI random-port issue without exposing the system to potential vulnerabilities like *.

Sounds great. This works for me, and will cover the most common use cases.

[pushpak1300]

After looking into this in more detail. an OAuth open redirect is not a passive exploit. It requires the victim to both click a crafted link from an untrusted source and then actively authenticate on the login page. Given that, using * in local development isn't a real security concern.

I don't think this warrants a new config option at this point. Happy to revisit if the threat model changes or if there's a stronger case for it.

[dylanbr]

@pushpak1300 please consider reopening this issue.

Let's say you have a production MCP server and your users are using the following clients:

1. ChatGPT on the web
2. Claude Code CLI
3. Codex CLI

That means you need to allow 3 different types of redirect URL:

1. ChatGPT URLs always start with https://chatgpt.com, so this is easy, it can be added to the allowlist.
2. Claude uses a URL starting with http://localhost:<port>/callback, where <port> is a randomly assigned port number. This is not possible to add to the allowlist. ¹
3. Codex uses a URL starting with http://127.0.0.1:<port>/callback, where <port> is a randomly assigned port number. Again, it is not possible to add this to the allowlist. ¹

This is a very common production requirement, with these being the most popular MCP-supporting tools.

If I've missed something, please let me know how I can support this?

Footnotes

1. I have checked, with the latest versions of Claude and Codex, and as of today they both use randomly assigned ports for the redirect URL. I have seen some mention of them using static ports, but this is definitely not the case. ↩ ↩²

[pushpak1300]

Hey @dylanbr, Can we not use all the port on localhost ? whats harm in that ? how's that insecure ?

[dylanbr]

Hey @dylanbr, Can we not use all the port on localhost ? whats harm in that ? how's that insecure ?

I don't want to allow * in production, and but I do want to allow localhost redirects in production.

This is not related to my local development environment at all, purely to production.

[dylanbr]

Maybe another example would help.

Say I have a Laravel app with laravel/mcp in it, and it's running on https://myapp.com/mcp.

A user then wants to add this MCP to their Codex CLI, so they run codex mcp add mymcp --url https://myapp.com/mcp to connect to the production instance.

This opens a browser window to https://myapp.com/oauth/authorize (my production server), and they authorize.

Now, because they initiated this from the CLI, the redirect URL is something like http://127.0.0.1:55443/callback, but that port number will change each time.

If I have the allowlist set to anything other than *, this will be rejected, because it doesn't support dynamic ports.

(apologies for all the edits, I submitted too soon 😄)

[pushpak1300]

@dylanbr so you are saying the following config is not working as expected ?

'redirect_domains' => [
        'https://chatgpt.com',
        'localhost',
        '127.0.0.1',
    ],

[dylanbr]

@dylanbr so you are saying the following config is not working as expected ?

'redirect_domains' => [
        'https://chatgpt.com',
        'localhost',
        '127.0.0.1',
    ],

Correct, this does not work, nor does the following:

    'redirect_domains' => [
        'http://127.0.0.1',
        'http://[::1]',
        'http://localhost',
    ],

The OAuthRegisterController::allowedDomains() method checks the beginning of the URL matches, and adds trailing slash if to allowlist entries that don't have one.

That means that bare domains like localhost won't work, it has to be http://localhost, but then this won't work either, due to the trailing slash being added. It has to match http://localhost/ (without a port).

Checking from the beginning of the URL, and the trailing slash are both good for security in general, to avoid any manipulation of what domain is allowed. For this use case however, where dynamic ports are required, it does not work.