Add OAuth Device Code Flow Support for Headless Environments

[chodges15]

This may be covered by issue #4, but I wanted to raise it as a separate issue as it is a key workflow for my organization.

The current OAuth implementation requires localhost callbacks
(http://localhost:5173/oauth/callback), which doesn't work on headless servers or remote
development environments where opening a browser locally isn't possible.

Problem:

• Users on headless machines cannot complete OAuth authentication
• SSH port forwarding is a workaround but adds complexity
• User Auth Tokens are the only current alternative but pose security concerns for some deployments

Proposed Solution:
Implement OAuth 2.0 Device Code Flow (RFC 8628) as an alternative authentication method. This would
allow users to:

1. Run a command that generates a device code and verification URL
2. Open the URL on any device with a browser
3. Enter the device code to authorize the application
4. Complete authentication without requiring localhost callbacks

Example Flow:
sentry-mcp auth --device-code
Output: Go to https://sentry.io/device and enter code: ABC-123
User enters code in browser, auth completes automatically

Use Cases:

• Remote development servers
• Docker containers
• CI/CD environments
• Any headless deployment where browser access isn't available locally

Additional Context:
This is a standard OAuth flow supported by many platforms (GitHub, Google, Microsoft) specifically
for headless/device scenarios. It maintains security while enabling headless authentication.

[dcramer]

Very much in favor of this - I think there's an open question on complexity. I'm working on getting 2.1 upstreamed into Sentry right now which.. could take a week or a month, unclear atm, and my goal would be to actually remove our intermediate provider in that case.

I will need to learn more about how this is generally implemented as I've not dealt w/ this one on the technical side before. I just need to determine if 1) its supported in our current proxy implementation [guessing unlikely], and 2) if its supported upstream in Sentry [unlikely].

Will add it to the list tho!

[dcramer]

Going to do a simple web approach #648 - this will only work for Sentry's cloud service tho (as it requires mcp.sentry.dev)

[vrmiguel]

@dcramer is there any chance we could be able to use the Sentry MCP using the regular OAuth flow for integrations?
Instead of this new agent-focused separate OAuth flow.

Edit: it seems MCP (local, stdio) does work fine with regular OAuth tokens. The only problem I've seen is that the read_organizations tool call returns None. I feel like it should've returned the organization where the external OAuth integration was accepted. Is this a bug?

[dcramer]

@vrmiguel yep it should return the organization, tho if you're binding tenant constraints now i think we suppress that tool entirely (list_organizations)

what are you trying to accomplish? at some point we will move to sentry's oauth provider, but it doesnt yet support the required behaviors that we need

[vrmiguel]

@dcramer thanks for the response!

what are you trying to accomplish?

Use the Sentry MCP server (local or hosted, whichever works), but using tokens gotten from a regular Sentry public integration. You're saying this is not currently possible?

[dcramer]

@vrmiguel I'm not sure what you mean wrt the tokens here - like I understand the technical ask, but whats the use case over the current oauth implementation (or the proposed new alternative stdio flow)?

[vrmiguel]

@dcramer In our case, we have Sentry as an integration users can install. It predates the MCP server, and is implemented using the regular OAuth (custom public integration)

Now, we'd like to also have our system use the Sentry MCP to work on issues from Sentry. After some testing, it does seem like everything works fine with the existing OAuth tokens that we have, other than read_organizations.

[dcramer]

It turns out my plan here actually doesnt quite work anyways as I would have to proxy API requests and I dont want to do that as it creates some other headaches. Should've thought this one through more!

[gndk]

In case anybody runs into this... I run one of my projects in a local VM on mac and port forwarding didn't work because the MCP OAuth picks the port randomly and changing it manually invalidates the url.

Authenticate on the host and copy tokens to the VM:

1. Host: claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. Host: Complete the OAuth flow in the browser
3. Host: Extract tokens from keychain:

   security find-generic-password -s "Claude Code-credentials" -w | python3 -m json.tool

4. VM: Copy the mcpOAuth → sentry|... block into ~/.claude/.credentials.json
5. VM: Restart Claude Code

[awojtas]

I authenticated Sentry MCP on a host Windows machine with Claude Code, then copied details from ~/.claude/.credentials.json to my headless Ubuntu machine, this worked.

[PJUllrich]

Alternatively, a simple Bearer token might do the trick as well