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, apikeyheader, 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

Common Failure Modes