Skip to main content
hc
Submit
guidesSource-backedReview first Safety ✓ Privacy ✓

OAuth Patterns For MCP Server Authentication

Implement OAuth patterns for MCP servers in Claude Code: Dynamic Client Registration, pre-configured client IDs, oauth.scopes pins, authServerMetadataUrl overrides, and keychain token storage from official MCP documentation.

by kiannidev·added 2026-06-16·
Claude Code
HarnessClaude Code
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • Pin oauth.scopes to least privilege; widen only when tools return insufficient_scope.
  • Client secrets belong in keychain/credentials storage—not committed .mcp.json.
  • Static Authorization headers bypass OAuth discovery—verify tokens separately.

Privacy notes

  • OAuth tokens in keychain still grant server access—revoke via /mcp Clear authentication.
  • Redirect URIs must match registered localhost callback ports exactly.

Prerequisites

  • Remote HTTP MCP server requiring OAuth per server documentation.
  • Developer portal access to register OAuth apps when DCR is unsupported.
  • Team policy for scope pins and credential storage.

Schema details

Install type
copy
Reading time
9 min
Difficulty score
58
Troubleshooting
Yes
Breaking changes
No
Full copyable content
Choose OAuth pattern per server: dynamic registration, pre-configured client with --callback-port, oauth.scopes pins in .mcp.json, then authenticate via /mcp.

About this resource

TL;DR

Claude Code supports OAuth for remote MCP servers via /mcp, with optional scope pins, fixed callback ports, and pre-configured client credentials when dynamic registration is unavailable.

OAuth Pattern Selection

Pattern When to use
Dynamic registration Server supports DCR
--client-id + --client-secret Portal-registered app
oauth.scopes in JSON Limit advertised scopes
authServerMetadataUrl Discovery chain fails
--callback-port Server requires fixed redirect URI

Step-by-Step Guide

  1. Add HTTP server to .mcp.json or CLI.
  2. Choose registration path from server docs.
  3. Pin scopes in JSON when security team requires subset.
  4. Run /mcp to complete browser auth.
  5. Verify with claude mcp get <server>.
  6. Document revocation steps (Clear authentication).

Troubleshooting

Issue: incompatible auth server / no DCR Fix: Register app manually; use --client-id and --client-secret.

Issue: insufficient_scope on tool call Fix: Widen oauth.scopes; re-authenticate via /mcp.

Duplicate Check

Complements mcp-server-auth-least-privilege (server builder focus).

References

#mcp#oauth#authentication#claude-code#security

Source citations

Add this badge to your README

Show that OAuth Patterns For MCP Server Authentication is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/guides/oauth-patterns-for-mcp-server-authentication.svg)](https://heyclau.de/entry/guides/oauth-patterns-for-mcp-server-authentication)

How it compares

OAuth Patterns For MCP Server Authentication side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldOAuth Patterns For MCP Server Authentication

Implement OAuth patterns for MCP servers in Claude Code: Dynamic Client Registration, pre-configured client IDs, oauth.scopes pins, authServerMetadataUrl overrides, and keychain token storage from official MCP documentation.

Open dossier 		Remote MCP Server Security Review Checklist

Checklist for reviewing remote MCP servers before team rollout: OAuth scopes, transport security, tool surface, registry provenance, and rollback.

Open dossier 		Secret Handling For MCP Servers And Agent Tools

A practical guide for handling secrets when connecting MCP servers and authoring Agent SDK tools in Claude Code: env expansion in .mcp.json, OAuth scope pins, keychain storage, local scope, and redaction before tool arguments reach the model.

Open dossier 		Auditing MCP Client Configuration Before Team Rollout

Source-backed checklist for reviewing Claude Code MCP client configuration before a team rollout, covering scopes, transports, commands, secrets, allowlists, denylists, approvals, and rollback.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categoryguidesguidesguidesguides
Sourcesource-backedsource-backedsource-backedsource-backed
AuthorkiannidevkiannidevkiannidevYB0y
Added2026-06-162026-06-142026-06-162026-06-10
Platforms
Claude Code
Claude Code
Claude Code
Claude Code
Source repo————
Safety notes✓Pin oauth.scopes to least privilege; widen only when tools return insufficient_scope. Client secrets belong in keychain/credentials storage—not committed .mcp.json. Static Authorization headers bypass OAuth discovery—verify tokens separately.✓Remote MCP servers expose model-callable tools over the network; treat write tools, shell proxies, and broad API scopes as production-risk actions until explicitly approved. Verify transport uses HTTPS with valid certificates and that OAuth tokens are scoped to the minimum tenant, project, or account needed for the workflow. Do not approve registry entries or remote URLs that cannot be tied to an identifiable maintainer, version history, and update channel.✓Stdio MCP servers inherit environment variables you pass via --env or .mcp.json env blocks; treat that as handing the server your credentials. HTTP MCP headers and OAuth tokens authenticate outbound calls; a compromised server or overly broad scope can exfiltrate data through tool results. Agent SDK tool descriptions, inputs, and outputs enter model context each turn—never embed live secrets in schemas or sample responses. Project-scoped .mcp.json is designed for version control; use ${VAR} expansion and local scope for machine-specific secrets instead of committing raw keys.✓Local stdio MCP servers execute commands with the user's privileges, so review the exact command, arguments, package runner, file paths, and network behavior before sharing a config. Remote MCP servers can expose model-controlled tools for production systems; require least-privilege scopes, explicit approval for write tools, and a rollback path before team rollout. Do not rely on server names alone for enforcement because names are user-assigned labels; use command or URL allowlist entries when policy must control what actually runs.
Privacy notes✓OAuth tokens in keychain still grant server access—revoke via /mcp Clear authentication. Redirect URIs must match registered localhost callback ports exactly.✓Remote MCP traffic can include prompts, tool arguments, tool outputs, OAuth metadata, tenant IDs, and resource identifiers visible to the server operator. Review whether the remote server logs, caches, or forwards tool inputs to third-party observability or analytics systems. Revoke OAuth grants and delete local MCP configuration when uninstalling a remote server that accessed private repositories, tickets, or customer data.✓MCP tool arguments, resource contents, and error messages can contain API keys, JWTs, customer IDs, and internal URLs that flow into session transcripts. OAuth access tokens for remote MCP servers are stored in the macOS Keychain or a credentials file; revoke with Clear authentication in /mcp when offboarding. Agent SDK handlers that call external APIs may log request metadata; redact at the handler boundary before traces or support exports leave your environment. Shared .mcp.json templates should name required variables (for example API_KEY) without example values that look like real credentials.✓MCP client configuration can reveal server URLs, internal hostnames, command paths, environment-variable names, header names, OAuth client IDs, and tool availability. Do not store API keys, bearer tokens, client secrets, tenant IDs, or personal credentials in shared `.mcp.json`, managed-mcp.json, PR bodies, issue comments, logs, or screenshots. Tool arguments, tool results, resources, prompts, logs, traces, and OAuth metadata can expose private repositories, tickets, databases, user identities, and workspace data.
Prerequisites
  • Remote HTTP MCP server requiring OAuth per server documentation.
  • Developer portal access to register OAuth apps when DCR is unsupported.
  • Team policy for scope pins and credential storage.
  • The remote MCP server URL, registry listing or package source, documentation, and declared tool list.
  • The OAuth client configuration, redirect URIs, requested scopes, token storage behavior, and identity provider policy.
  • A test Claude Code profile where the remote server can be connected with non-production credentials.
  • A named approver who can block the server, revoke tokens, and publish managed MCP policy if the review fails.
  • Inventory of MCP servers (stdio, HTTP, or plugin) and any Agent SDK custom tools in your project.
  • Access to .mcp.json, user settings, and environment variables on developer machines.
  • Team policy for secret stores, rotation, and what may appear in version control.
  • Ability to test MCP connections in a non-production profile before granting production credentials.
  • A draft `.mcp.json`, `~/.claude.json` entry, plugin-provided MCP server, claude.ai connector plan, or managed-mcp.json deployment to review.
  • The server documentation, package or repository source, expected transport, command or URL, environment variables, headers, OAuth behavior, and tool list.
  • A test machine or disposable Claude Code profile where the configuration can be loaded with non-production data.
  • A named owner who can approve the rollout, publish the final configuration, and revoke credentials or block servers if the rollout fails.
Install————
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.