mcp-oauth-setup

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:

1. RFC 8414 - OAuth Authorization Server Metadata Discovery via .well-known/oauth-authorization-server
2. RFC 7591 - Dynamic Client Registration at the provider's registration endpoint
3. 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:

1. Send initialize JSON-RPC request → get Mcp-Session-Id header
2. 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:

1. Per-agent OAuth, not connected → grayed card, "Connect" button
2. Per-agent bearer/API key, not connected → inline password input
3. 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