MCP Server Authentication & OAuth Dynamic Client Registration

Implement flexible authentication for MCP (Model Context Protocol) server connections. For OAuth providers, auto-discover endpoints and dynamically register as a client — the user just provides the MCP server URL and clicks "Connect." For bearer/API key providers, support both admin-shared and per-agent credentials so different agents can authenticate with different accounts.

When to Use

Building an admin UI for managing MCP server connections
Integrating with third-party MCP providers (Linear, Sentry, Granola, Render, etc.)
Implementing the MCP Streamable HTTP transport with authenticated tool sync
Adding per-agent credential support so each agent can use its own account
Adding OAuth to an existing MCP connector/server management system

Core Standards

The OAuth implementation relies on three RFCs:

RFC 8414 - OAuth Authorization Server Metadata Discovery via .well-known/oauth-authorization-server
RFC 7591 - Dynamic Client Registration at the provider's registration endpoint
RFC 7636 - PKCE (S256) for authorization code security

Not all MCP servers use OAuth. Some (e.g., Render) use bearer tokens with API keys and handle account/workspace selection at the MCP protocol level. The credential system must be auth-type-agnostic.

Architecture Overview

Credential Mode (Orthogonal to Auth Type)

credential_mode applies to all auth types (bearer, api_key_header, oauth), not just OAuth. Different agents may need their own credentials for the same MCP server.

credential_mode = "shared"     → Admin provides one credential, all agents use it
credential_mode = "per_agent"  → Each agent has its own credential

OAuth Flow

Admin clicks "Connect"
    |
    v
Discover OAuth metadata (RFC 8414)
    |  GET /.well-known/oauth-authorization-server
    v
Register as OAuth client (RFC 7591)
    |  POST /oauth/register
    v
Redirect to provider consent screen
    |  GET /oauth/authorize?client_id=...&code_challenge=...
    v
Provider redirects back with code
    |  GET /callback?code=...&state=...
    v
Exchange code for tokens
    |  POST /oauth/token
    v
Store tokens, sync tools

Implementation Steps

1. Database Schema

Two tables: MCP server configuration (OAuth metadata + shared tokens) and per-agent credentials (any auth type).

See: references/schema.md

Key decisions:

Encrypt all secrets at rest (encrypts :oauth_client_id, etc.)
Store both shared tokens and per-agent tokens (join table)
credential_mode ("shared" or "per_agent") applies to ALL auth types
Store discovered_tools as JSON array
AgentMcpConnection.access_token stores OAuth tokens, bearer tokens, or API keys

2. OAuth Discovery and Registration

Three model methods on the MCP server record.

See: references/oauth_flow.md

Discovery (discover_oauth_metadata!): Derive .well-known/oauth-authorization-server URL, parse JSON response, skip if already configured, handle 404 gracefully (not all servers support RFC 8414)
Registration (register_oauth_client!): POST to registration endpoint, store client_id and client_secret, skip if already present
Combined (discover_and_register_oauth!): Run discovery then registration in sequence

3. Authorization Controller

Create an OAuth controller with authorize and callback actions.

See: references/oauth_flow.md

Critical pitfalls:

Turbo Drive cross-origin redirects: redirect_to with an external URL is silently swallowed by Turbo Drive — browser stays on current page. Use HTML with <meta http-equiv="refresh" content="0;url=..."> for the external redirect instead.

State parameter: Use a signed, expiring message (Rails message_verifier) with connector ID, PKCE code verifier, optional agent ID, and timestamp. Set 10-minute expiry.

String keys from message verifier: After verifying the state token, payload uses string keys not symbol keys. Use payload["connector_id"], not payload[:connector_id].

PKCE (S256): Generate a random code_verifier, compute code_challenge as URL-safe Base64 of SHA-256 digest with no padding.

Error redirects: When agent_id is present in state, redirect errors to the agent edit page, not the connectors index.

Auto-sync on first agent connection: For per-agent OAuth, when the callback stores the first per-agent token, auto-sync tools using that agent's token if tools haven't been discovered yet.

4. Routes

resources :connectors do
  member do
    get "oauth/authorize", to: "mcp_oauth#authorize", as: :mcp_oauth_authorize
  end
end
get "mcp_oauth/callback", to: "mcp_oauth#callback", as: :mcp_oauth_callback

Route helper naming: A member route mcp_oauth_authorize on resources :connectors generates mcp_oauth_authorize_connector_path(connector) — resource name comes last. Common source of NoMethodError.

5. Token Management

See: references/oauth_flow.md (ensure_token_fresh! pattern)

Check expiry with 5-minute buffer (token_expires_at < 5.minutes.from_now)
Use with_lock for thread-safe updates on shared tokens
Return appropriate token based on credential mode
Bearer/API key per-agent tokens are static (no refresh needed)

6. MCP Tool Sync (Streamable HTTP Protocol)

See: references/tool_sync.md

Two-step handshake:

Send initialize JSON-RPC request → get Mcp-Session-Id header
Send tools/list with session ID header

Critical details:

Set Accept: application/json, text/event-stream — some servers return 406 without this
Some servers return SSE format — parse both formats
sync_tools! must accept agent: parameter for per-agent auth
Some servers (e.g., Render) allow unauthenticated tool listing

7. UI Considerations

See: references/ui_patterns.md

Connector form:

credential_mode radio applies to ALL auth types
Hide admin token input when per-agent is selected for bearer/API key
Show OAuth fields only for OAuth auth type
Use Stimulus controller to toggle visibility based on both auth_type AND credential_mode

Agent edit form — three states for per-agent connectors:

Per-agent OAuth, not connected → grayed card, "Connect" button
Per-agent bearer/API key, not connected → inline password input
Connected (any type) → tool checkboxes + "Token configured" badge

Verified MCP Providers

Provider	URL	Tools	Auth	Notes
Linear	`https://mcp.linear.app/mcp`	45	OAuth	SSE response format
Sentry	`https://mcp.sentry.dev/mcp`	14	OAuth	Standard JSON
Granola	`https://mcp.granola.ai/mcp`	4	OAuth	Standard JSON
Render	`https://mcp.render.com/mcp`	24	Bearer token	No OAuth, per-agent API keys

Common Failure Modes

Symptom	Root Cause	Fix
Page stays on form, no redirect	Turbo Drive swallows cross-origin 302	Use HTML meta refresh instead of `redirect_to`
`NoMethodError` on route helper	Wrong helper name ordering	Member route generates `mcp_oauth_authorize_connector_path`
`payload[:connector_id]` returns nil	Message verifier returns string keys	Use `payload["connector_id"]`
406 from MCP server	Missing Accept header	Add `Accept: application/json, text/event-stream`
400 "Mcp-Session-Id required"	Skipped initialize handshake	Send `initialize` first, use returned session ID
JSON parse error on tool sync	Server returns SSE format	Detect and parse both formats
Token exchange fails silently	Missing `code_verifier`	Include PKCE verifier from signed state
OAuth discovery 404	Server doesn't use OAuth	Use bearer or API key auth instead
Per-agent connector shows no tools	Admin can't sync without token	Tools auto-sync on first agent connection
Error redirect goes to wrong page	`agent_id` not checked in rescue	Redirect to agent edit when `agent_id` present

mcp-oauth-setup