The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →To configure OAuth for a remote MCP server in Claude Code, register the server as an explicit HTTP (or streamable-http) endpoint, then authenticate it from Claude Code’s /mcp panel. Claude Code normally discovers the authorization server automatically from the server’s response; add oauth.authServerMetadataUrl only when discovery is nonstandard, and use oauth.scopes to pin a least-privilege scope set.
This guide covers project and user configuration, callback ports, preconfigured client credentials, token refresh, hosted-connector limits, independent testing with MCP Inspector, and the errors that produce “Needs authentication” or “Failed to connect.”
What you need before configuring OAuth
- A remote MCP endpoint reachable over HTTPS.
- A current Claude Code installation with permission to add MCP servers.
- OAuth client details from the server operator if the server requires pre-registration: client ID, and sometimes a client secret and fixed localhost callback port.
- The exact scopes your tools require. Do not request broad scopes merely because they are advertised.
Remote entries must declare their transport. Claude Code treats a URL without a type as a stdio configuration, so an omitted type can make a valid remote server appear broken.
Add the remote MCP server
Command-line setup
For a server using HTTP transport, run:
claude mcp add --transport http my-server https://mcp.example.com/mcpThe command writes the configuration and reports an Added ... message. Confirm what Claude Code sees:
#1 Best Overall
claude mcp list
claude mcp get my-serverclaude mcp list can show Connected, Needs authentication, or Failed to connect. These states distinguish OAuth approval from transport or server failures.
JSON setup for a project or user scope
Use project .mcp.json when a team should share the endpoint definition. Use user scope for a personal server. The documented JSON form is:
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp"}'In a configuration file, the equivalent entry is:
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}streamable-http is accepted as an alias when you use JSON, but http is the clearest portable value. Keep the URL and transport definition in version control only when the endpoint itself is safe to share; never commit secrets.
Complete the OAuth sign-in in Claude Code
- Start Claude Code in the project containing the server configuration.
- Open the interactive MCP panel by entering
/mcp. - Select the server marked Needs authentication.
- Choose the authentication action and finish the browser authorization and consent screens.
- Return to Claude Code and wait for the server state to change to Connected.
Claude Code recognizes that authentication is required when the server responds with an HTTP 401 or 403. After the browser flow, it stores the OAuth credentials and attaches them to later MCP calls.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsWhat happens when a token expires
If a request later receives a 401, Claude Code attempts one token refresh and retries the request. If the authorization server rejects the refresh token, the /mcp panel presents Re-authenticate. Select it to run the browser flow again rather than repeatedly retrying an invalid token.
Rank #2
Control metadata discovery and scopes
Use automatic discovery first
A standards-compliant server can point Claude Code to its authorization server through the WWW-Authenticate response header. Claude Code then discovers the authorization metadata without additional configuration. This is the normal path.
Override discovery for a proxy or nonstandard server
If a reverse proxy hides or rewrites discovery information, add an explicit metadata URL:
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
}
}
}
}Use the URL published by your identity provider. Do not guess a well-known path if the provider documents a different one.
Free tools Windows power users keep installed
One-click scans. No signup required.
Pin a least-privilege scope set
Set oauth.scopes to one space-separated string:
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"scopes": "resource.read resource.write"
}
}
}
}Configured scopes take precedence over scopes discovered from the server. Request only the permissions needed by the tools you intend to use; reducing scopes limits the impact of a stolen or misused token.
Use a fixed callback port or preconfigured OAuth credentials
Most providers can use the callback handling supplied by Claude Code. A provider that pre-registers a localhost redirect may require a fixed callback port. In that case, provide the port in the OAuth object when adding JSON configuration. The CLI also accepts a client ID and can receive a client secret through its secret option.
Rank #3
- Used Book in Good Condition
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "YOUR_CLIENT_ID",
"callbackPort": 4567
}
}
}
}The exact option names accepted by your Claude Code version and server registration must match its current documentation. Keep the client secret out of committed .mcp.json files, shell history, issue reports, and logs. Prefer the CLI’s secret input or an operating-system credential store.
When a callback port cannot be made to work
- Confirm that the provider registered the same port and redirect URI Claude Code is using.
- Check whether another local process already occupies the port.
- Verify that a firewall, VPN, or corporate browser policy is not blocking the localhost return.
- If the provider accepts only a hosted redirect, use its Claude.ai-managed connector instead of forcing a local callback.
Understand local OAuth versus Claude.ai-managed connectors
| Option | Where authorization occurs | Use it when |
|---|---|---|
| Local Claude Code OAuth | Your browser returns to the local Claude Code callback | The identity provider permits the registered localhost redirect and the server supports normal discovery or an explicit metadata URL. |
| Claude.ai-managed connector | Authorization is completed in Claude.ai, then Claude Code uses the managed connection | An Anthropic-hosted connector’s upstream identity provider accepts only the Claude.ai redirect URL. |
Anthropic’s current Claude Code guidance identifies Microsoft 365, Gmail, and Google Calendar among hosted services that may not support local OAuth for this reason. Authorize those connectors at claude.ai/customize/connectors while signed in with the relevant subscription, then let Claude Code use the managed connector.
Test the server independently with MCP Inspector
MCP Inspector separates server-side OAuth problems from Claude Code’s local credential store:
- Run
npx @modelcontextprotocol/inspector. - Select SSE or Streamable HTTP, matching the server.
- Enter the MCP server URL.
- Open Auth Settings and choose Quick OAuth Flow.
- Approve the authorization request and continue through the progress steps.
- Copy the resulting
access_tokenand pass it in the platform connector’sauthorization_tokenfield for a controlled test.
If Inspector cannot complete discovery or consent, fix the server’s OAuth metadata, redirect registration, or scopes before changing Claude Code settings. If Inspector succeeds but Claude Code remains unauthenticated, inspect the Claude Code entry with claude mcp get my-server and review the /mcp state.
Google Cloud and Google Workspace remote MCP setup
For a Google Cloud or Google Workspace remote MCP service, create an OAuth 2.0 client whose application type is Web application. Add this authorized redirect URI exactly:
https://claude.ai/api/mcp/auth_callbackCopy the client secret securely. Enter the client ID and secret in the custom connector’s Advanced settings. This Google configuration uses the Claude.ai callback and is distinct from a local Claude Code callback-port registration; do not substitute one redirect for the other.
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 →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Troubleshoot common failures
“Needs authentication” never changes
- Open
/mcpand select the server; the browser flow may still be waiting for approval. - Check that the endpoint returned 401 or 403 rather than a proxy-generated HTML error.
- Run
claude mcp get my-serverand verifytypeishttporstreamable-http. - Use Inspector to determine whether the authorization server itself can complete the flow.
“Failed to connect” appears
- Confirm the URL is HTTPS, reachable from the machine running Claude Code, and points to the MCP path rather than a website landing page.
- Check for a typo in the server name or URL with
claude mcp list. - Inspect proxy and firewall rules, then retry outside the restrictive network if policy permits.
Discovery fails
- Inspect the server’s
WWW-Authenticateheader. - If it does not identify usable metadata, configure
oauth.authServerMetadataUrlwith the provider’s documented metadata endpoint. - Ensure the metadata endpoint is reachable over HTTPS and advertises an authorization endpoint, token endpoint, and compatible redirect methods.
The provider rejects the redirect URI
- Compare the registered URI character-for-character, including scheme, host, path, and port.
- Use a fixed callback port only when the provider requires one and register that same port.
- For providers that accept only
https://claude.airedirects, configure the connector in Claude.ai instead of local OAuth.
Refresh repeatedly fails
A rejected refresh token is not repaired by restarting Claude Code. Choose Re-authenticate in /mcp. If the account was revoked or scopes changed, approve the new consent request and confirm that the server accepts the resulting scopes.
Tools are missing after sign-in
Authentication proves identity but does not grant every tool permission. Compare the requested scopes with the server’s required scopes, then remove an overly restrictive oauth.scopes value or replace it with the smallest complete set.
Security, reliability, and operating guidance
- Trust an MCP server before connecting it. Anthropic warns that servers handling external content can expose users to prompt-injection risk.
- Treat access tokens, refresh tokens, client secrets, cookies, and authorization headers as credentials.
- Use project configuration for shareable endpoint metadata, but keep personal credentials in protected local storage.
- Pin scopes deliberately and review them whenever a server adds tools.
- Use Inspector for reproducible server-side diagnostics before changing multiple Claude Code settings at once.
- Expect one refresh-and-retry after a 401; a rejected refresh token requires interactive re-authentication.
No general connection-success or failure-rate benchmark is established for Claude Code OAuth, so capacity and reliability depend on the MCP server, identity provider, network path, and your organization’s policies.
Or skip the browser setup
If your separate task is producing clean screenshots of authenticated or public web pages, ScreenshotNeo is a website screenshot API and MCP server for AI clients. It is not a replacement for configuring OAuth on your MCP server; it is an optional capture service when you do not want to maintain browser automation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
One request returns PNG, JPEG, WebP, or PDF. Before capture it accepts cookie-consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation. A cURL call is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)And in Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does Claude Code support OAuth 2.0 for remote MCP servers?
Yes. Remote servers can use OAuth 2.0, with authentication completed through the Claude Code /mcp panel.
Should I use http or streamable-http in configuration?
Use explicit http in the CLI or JSON examples; Claude Code also accepts streamable-http as a JSON alias.
Where do I see the saved server definition?
Run claude mcp get <name>; use claude mcp list for the connection state.
Can I test OAuth without changing Claude Code credentials?
Yes. MCP Inspector runs the flow independently and lets you copy an access token for a controlled connector test.
Quick Recap
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.
