To use OAuth with a remote MCP server in Claude Code, add it as an HTTP server, then open /mcp and complete the browser authorization flow when Claude Code marks it Needs authentication. In the normal case, Claude Code discovers the server’s OAuth metadata automatically; you only need an explicit metadata URL or pinned scopes when the server requires them. This guide covers the CLI setup, configuration options, callback-port and client-credential cases, and how to tell an OAuth failure from a connection problem.
How Claude Code handles OAuth for remote MCP servers
OAuth applies to remote MCP servers, which Claude Code connects to over HTTP. The current Claude Code MCP documentation recommends HTTP for remote servers and accepts streamable-http as an alias in JSON configuration. A URL without an explicit type is treated as a stdio configuration, so include "type":"http" when adding a remote server.
Authentication is normally initiated from Claude Code rather than by manually copying a token into the server configuration. When the server requires authorization, Claude Code detects the requirement from a 401 or 403 response and shows the server as needing authentication in /mcp. You select the server and finish the OAuth flow in a browser. Claude Code then stores the credentials for later MCP requests.
- Automatic discovery: the normal path. A server can advertise its authorization server through its
WWW-Authenticateresponse, allowing Claude Code to discover OAuth metadata. - Explicit metadata: use
oauth.authServerMetadataUrlwhen discovery is nonstandard or a proxy makes the advertised location unsuitable. - Scope control: use
oauth.scopesto request a specific, space-separated set of scopes instead of the discovered scopes.
Add and verify the remote MCP server
Use the CLI to add the HTTP endpoint, then confirm that Claude Code saved it. The examples use a placeholder server URL; replace it with the HTTPS endpoint supplied by the MCP server operator.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- Add the remote server: run
claude mcp add --transport http my-server https://mcp.example.com/mcp. The CLI should print anAdded ...message when it writes the configuration. - Check the configured servers: run
claude mcp list. Depending on its state, the server may show asConnected,Needs authentication, orFailed to connect. - Inspect the individual entry: run
claude mcp get my-serverto verify the name and configuration Claude Code has for that server. - Authorize if requested: in Claude Code, enter
/mcp, select the server markedNeeds authentication, and follow the browser sign-in and approval prompts.
You can also add an entry using JSON:
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp"}'For a team-shared setup, put server configuration in the project’s .mcp.json. Use user scope for a server that should be available to you personally rather than shared with the project. Keep secrets out of project configuration that may be committed to version control.
Set a metadata URL or limit requested scopes
Most servers should work with automatic OAuth metadata discovery. If the server’s discovery response is absent, nonstandard, or unsuitable behind a proxy, set the metadata URL explicitly in the server’s OAuth configuration. The URL must be the authorization server’s metadata endpoint provided by the service operator; do not guess it.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration",
"scopes": "resource.read resource.write"
}
}
}
}oauth.scopes is one space-separated string. When set, it takes precedence over scopes discovered from the server. That is useful when the server advertises more access than your tools need: request only the least-privilege scopes approved for your use. A scope mismatch can prevent a tool from working, so confirm the exact scope names with the server operator rather than inventing or broadening them.
Use a fixed callback port or preconfigured OAuth credentials
Most users can let Claude Code perform the interactive sign-in without entering a client ID or secret. A fixed callback port matters when the OAuth provider requires a pre-registered localhost callback. For that setup, the Claude Code configuration supports an OAuth object with a client ID and callback port through claude mcp add-json; the CLI can also be given a client secret through its secret option.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesRank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
The provider’s registration and Claude Code’s local callback must agree. Register the callback port required by the provider, then configure that same port for the MCP server. A redirect URI or port mismatch is an OAuth-provider configuration issue, not a reason to put a secret in a shared project file. Treat client secrets and refresh tokens as credentials; do not commit them or paste them into logs.
When authorization must happen in Claude.ai
Local Claude Code OAuth does not work with every connector. The current Claude Code documentation identifies some Anthropic-hosted services—including Microsoft 365, Gmail, and Google Calendar—whose upstream identity providers accept only the Claude.ai redirect URL, not a local Claude Code callback. For those managed connectors, authorize the connector at claude.ai/customize/connectors while signed in with the relevant subscription authentication, then let Claude Code use the managed connector.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
This is different from configuring a custom remote MCP server’s local OAuth flow. Do not try to solve a provider’s redirect-URI restriction by repeatedly changing the local callback port if the provider only accepts Claude.ai’s redirect.
Google Cloud or Google Workspace remote MCP services
Google’s guide for this scenario specifies creating an OAuth 2.0 client of type Web application, adding https://claude.ai/api/mcp/auth_callback as an authorized redirect URI, and entering the client ID and secret in the custom connector’s Advanced settings. This is the Google Cloud or Workspace remote-service path; it is not the same as registering a localhost callback port for local Claude Code OAuth.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Test the OAuth flow independently with MCP Inspector
If you need to determine whether the problem is in the MCP server’s OAuth behavior or Claude Code’s local configuration, test the server separately with MCP Inspector. Anthropic’s platform guidance describes this sequence:
- Start the Inspector with
npx @modelcontextprotocol/inspector. - Select SSE or Streamable HTTP, as appropriate for the server.
- Enter the MCP server URL and choose Open Auth Settings.
- Select Quick OAuth Flow, approve the authorization request, and continue through the progress steps.
- Copy the resulting
access_tokenif you need to test a platform connector using itsauthorization_tokenfield.
This checks the server-side authorization flow outside Claude Code’s stored credentials. If Inspector cannot complete authorization either, investigate the server’s OAuth registration, metadata, redirect URI, and scopes before changing Claude Code’s entry.
Troubleshoot common OAuth and connection failures
| What you see | Likely cause | What to do |
|---|---|---|
Failed to connect in claude mcp list |
The endpoint is unreachable, the URL is wrong, or the remote entry was not configured as HTTP. | Check the HTTPS endpoint with the server operator, inspect it using claude mcp get my-server, and ensure the entry has an explicit http type (or supported streamable-http JSON type). |
Needs authentication |
The server requires OAuth and Claude Code has not completed authorization. | Open /mcp, select the server, and finish the browser flow. A 401 or 403 from the server can trigger this state. |
| OAuth metadata is not discovered | The server does not provide a suitable discovery response, or a proxy changes the expected discovery path. | Inspect the server’s WWW-Authenticate response and, if the operator provides one, configure oauth.authServerMetadataUrl. |
| Sign-in returns a redirect or callback error | The callback URI or port in the provider registration does not match the one used by the OAuth client, or the service only accepts a Claude.ai callback. | For a local flow, align the registered localhost callback with the configured callback port. For affected Anthropic-hosted connectors, authorize through Claude.ai instead. |
| Authorization succeeds but a tool lacks access | The granted token may not include the scope the tool needs, or a pinned scope set may be incomplete. | Ask the server operator for the required least-privilege scope names, update oauth.scopes only as needed, then authorize again. |
| A previously working server returns 401 | The access token may need refreshing. | Claude Code refreshes the stored token and retries once. If the refresh token is rejected, use /mcp and choose Re-authenticate. |
Trust the MCP server before connecting it. Anthropic warns that servers handling external content can expose users to prompt-injection risk; OAuth authenticates access, but does not make the server or the content it returns trustworthy.
Or skip the browser setup
If your goal is to get website screenshots rather than connect a protected third-party MCP server, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. This one-call example saves a screenshot of Stripe as WebP:
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the API options. The screenshot service addresses a different task from OAuth configuration: it can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed; its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents; and the Free plan includes 1,000 screenshots a month without a card, with paid plans starting at $5 for 3,000 shots. Features are available on every plan. Sign up free for 1,000 screenshots a month, with no card required.
Security checklist
- Use the HTTPS URL and explicit HTTP transport type supplied for the remote MCP server.
- Request only the scopes required by its tools; pin approved scopes where appropriate.
- Keep client secrets and refresh tokens out of committed configuration and logs.
- Use the Claude.ai-managed path when an upstream provider does not accept local callback URLs.
- Use MCP Inspector to isolate server OAuth behavior from Claude Code’s local credential store.
- Connect only to MCP servers you trust, because authenticated access does not remove prompt-injection risk from external content.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
