OAuth Debugger

The OAuth Debugger provides a visual, step-by-step interface for testing and debugging your MCP server’s OAuth 2.1 implementation. View every step of the OAuth handshake in detail with guided explanations, inspect network messages, and validate your implementation against multiple protocol versions. The debugger is fully compliant with MCP OAuth specification.

​

Key Features

The OAuth Debugger provides comprehensive tooling for testing OAuth implementations:

• Visual Step-by-Step Guide - Interactive flow guide with detailed explanations for each OAuth step
• Multi-Protocol Support - Test against OAuth spec versions 03-26, 06-18, and 11-25
• Full Registration Methods - Support for client pre-registration, Dynamic Client Registration (DCR), and Client ID Metadata Documents (CIMD)
• Network Inspection - View all HTTP requests and responses with headers and body content
• Educational Context - Built-in teachable moments and tips for common OAuth issues
• Sequence Diagram - Visual representation of the OAuth flow synchronized with your progress
• Export Capabilities - Copy logs in guide or raw format for debugging and documentation

​

Inline OAuth tracing

When you connect a server using OAuth 2.0, Inspector automatically records a trace of every step in the flow and surfaces it in the connection UI — no separate tool required. On the connection card, if OAuth fails, a banner identifies the exact step where the failure occurred (for example, “OAuth failed during Token Request”). In the server detail panel, the Last OAuth Trace section shows:

• Each OAuth step (discovery, client registration, PKCE, authorization redirect, token exchange) with a status indicator and message
• The error text for any failed step
• An HTTP History log of every request and response, with tokens and secrets automatically redacted

The trace persists across page reloads so you can inspect it after the browser returns from the authorization redirect. It is cleared when you disconnect or reset OAuth data for the server. Use the inline trace for a quick diagnosis of real connection attempts, and switch to the OAuth Debugger when you need a guided, step-by-step walkthrough against a specific protocol version.

​

Getting Started

To begin debugging OAuth flows:

1. Navigate to the OAuth Debugger - Click the OAuth Flow tab in MCPJam Inspector
2. Configure a Target Server - Click Configure Target to open the OAuth Profile Modal
3. Enter Server Details - Provide your server’s base URL and select your protocol version
4. Choose Registration Method - Select CIMD, DCR, or pre-registered based on your implementation
5. Start Testing - Click Continue to begin the OAuth flow

The debugger will guide you through each step of the OAuth handshake, providing real-time feedback and educational context.

​

OAuth trace in server overview

When you connect a server using OAuth, Inspector records a structured trace of the entire flow. You can view this trace at any time — even after a failed connection — by opening the server’s detail panel and scrolling to the Last OAuth Trace section. The trace shows:

• Source - Which part of the flow produced the trace (interactive_connect, callback, refresh, or hosted_callback)
• Current step - The step the flow reached before completing or failing
• Step-by-step breakdown - Each OAuth step with its status (success, pending, or error), a summary message, and optional HTTP request/response details
• HTTP history - A bounded list of all HTTP calls made during the flow, with headers and bodies sanitized to redact sensitive values such as tokens and secrets
• Failure highlight - If a step failed, the error panel on the server card and the overview both identify the specific step that caused the failure

The trace persists across page reloads so you can inspect a failed OAuth flow after returning to the inspector.

​

Reading OAuth log entries

OAuth trace steps also appear as filterable entries in the traffic log. Select OAuth from the Source filter in the log panel to isolate them. See OAuth log entries for details on the status indicators.

​

Pre-registered client secrets

When you configure a pre-registered OAuth client with a client secret, the secret is stored securely and never exposed in the UI after saving. The client secret field shows the following controls:

• Reveal (hosted mode only) — Fetches and temporarily displays the stored secret so you can copy it. The value is hidden again when you close the panel or navigate away.
• Clear — Marks the secret for removal. The secret is deleted from storage when you save. Click Undo to cancel before saving.
• Replace — Type a new value into the client secret field to replace the stored secret on the next save. Entering a new value automatically cancels any pending clear.

​

Authorization header conflict warning

If you enable OAuth and also add a custom Authorization header under Advanced settings, a warning appears. OAuth automatically sets the Authorization header when exchanging tokens, which may override or conflict with your custom value. Remove the custom header or switch to a different authentication method to avoid unexpected behavior.

​

Navigating to the OAuth Debugger from the logger

When an OAuth error appears in the request log, a Continue in OAuth Debugger button is shown on hover for that log row. Clicking it switches the selected server to the one that produced the error and deep-links directly to the OAuth Debugger (#oauth-flow), so you can investigate the failure without manually locating the right server.

​

Reconnecting OAuth servers

The enable/connect toggle on a server card or detail modal reuses existing credentials only — it will not launch a new OAuth consent screen. If the existing tokens are expired or missing and a fresh consent flow is required, the toggle reports a re-authentication error instead of redirecting you to the authorization server. To start a full OAuth flow, use the explicit Reconnect button on the server card or detail modal. This is the only path that will open the OAuth consent screen when new credentials are needed.

​

Desktop app behavior

When using the OAuth Debugger in the MCPJam Desktop app, the authorization step opens in your system browser instead of inside the app. After you approve access in the browser, you will see a “Continue in MCPJam Desktop” page that automatically hands control back to the desktop app. If the handoff does not happen automatically, click the link on that page to return. Once the browser callback is received, the desktop app resumes the OAuth flow and displays the result in the OAuth Flow tab.