Skip to main content
The MCP Inspector provides extensive configuration options for connecting to MCP servers, including connection mode, transport protocols, timeouts, OAuth authentication, and custom headers.

​
Connection Mode

By default, the Inspector uses Auto mode: it tries to connect directly to the MCP server first, then automatically falls back to the configured Inspector proxy if the direct connection fails for cases such as CORS or proxy-only routing. You normally do not need to change this setting. Open Configuration from the connection form if you need to force a specific mode.

​
Auto

Try a direct connection first, then fall back to the Inspector proxy when direct connection fails. This is the default and recommended option for most use cases.

​
Direct

Connect directly to the MCP server without proxy fallback. When to use:
  • Local development servers that are same-origin with the Inspector
  • Servers that require direct browser access
  • Debugging direct-only behavior

​
Proxy

Connect through the configured Inspector proxy immediately. When to use:
  • Corporate networks with proxy requirements
  • CORS restrictions
  • Testing proxy configurations
  • Development environments with proxy setup

​
Server display names

Each saved connection can have a display name (alias) shown in the dashboard, server list, header, command palette, and server picker. Edit it from the connection settings form. Changing only the display name updates labels in the UI without disconnecting or clearing tokens. Use this when you want clearer names for multiple servers that share similar URLs. Connection-affecting fields (URL, headers, OAuth, transport) still trigger a reconnect when you save.

​
URL and tabs

The inspector keeps the active tab in the page URL (?tab=…). Switching tabs updates the query string so a refresh or shared link restores the same view.

​
Advanced Configuration

​
Request Timeout

Maximum time (in milliseconds) to wait for a single request to complete. Default: 10000 (10 seconds)

​
Maximum Total Timeout

Maximum total time (in milliseconds) for the entire operation, including retries and progress updates. Default: 60000 (60 seconds)

​
Proxy Endpoint

The proxy endpoint URL used by Auto fallback and by forced Proxy mode. Default: ${window.location.origin}/inspector/api/proxy

​
OAuth Configuration

The inspector supports OAuth 2.0 authentication for MCP servers that require it.

​
Setting Up OAuth

By default the inspector relies on Dynamic Client Registration (DCR), so no credentials are needed. Use the Authentication dialog when the upstream auth server doesn’t expose registration_endpoint (common for proxy-mode servers fronting Slack, WorkOS, or GitHub) or when the provider requires a confidential client without PKCE.
  1. Click the Authentication button in the connection form
  2. Enter your OAuth credentials:
    • Client ID: Pre-registered OAuth client ID. Setting this skips DCR.
    • Client Secret: Pre-registered OAuth client secret (optional). Required for confidential clients without PKCE; when set alongside Client ID, the SDK switches token-endpoint auth from none to client_secret_basic/client_secret_post.
    • Scope: Space-separated list of OAuth scopes
  3. Click Save to store the configuration

​
OAuth Flow

When connecting to a server that requires OAuth:
  1. Initial Connection: Inspector attempts to connect
  2. Authorization Request: Server responds with authorization URL
  3. User Approval: You’re redirected to the OAuth provider
  4. Callback Handling: Inspector handles the OAuth callback automatically
  5. Token Storage: Access tokens are stored securely in browser localStorage
  6. Connection Established: Server appears in Connected Servers list

​
Authentication States

The inspector shows different states during OAuth:
  • Connecting: Initial connection attempt
  • Pending Auth: Waiting for OAuth approval
  • Authenticating: OAuth flow in progress
  • Ready: Successfully authenticated and connected
  • Failed: Authentication or connection failed

​
OAuth Authentication

When a server requires OAuth authentication:
  1. The connection will enter pending_auth state
  2. Click the Authenticate button in the server card
  3. Complete the authorization in the popup or new tab
  4. Return to the inspector - it will automatically detect the completed auth
If the popup is blocked, use the “open auth page” link as a fallback.

​
Custom Headers

Add custom HTTP headers to all requests sent to the MCP server.

​
Adding Headers

  1. Click Custom Headers in the connection form
  2. Click Add to create a new header
  3. Enter the header name and value
  4. Click Save

​
Common Use Cases

  • API Keys: Authorization: Bearer <token>
  • Custom Authentication: X-API-Key: <key>
  • Version Headers: X-API-Version: v2
  • Request IDs: X-Request-ID: <uuid>

​
Security Considerations

Custom headers are stored in browser localStorage. Never include sensitive credentials that shouldn’t be stored locally. Use OAuth for secure authentication instead.

​
Header Visibility

Header values are masked by default for security. Click the eye icon to reveal the value when needed.

​
Configuration Import/Export

​
Copy Configuration

Export your connection configuration as JSON:
  1. Fill in your connection settings
  2. Click Copy Config button
  3. The configuration is copied to your clipboard as JSON
Example configuration: 
{
  "url": "https://mcp.example.com/mcp",
  "transportType": "http",
  "connectionMode": "auto",
  "headers": {
    "Authorization": "Bearer token123"
  },
  "requestTimeout": 10000,
  "resetTimeoutOnProgress": true,
  "maxTotalTimeout": 60000,
  "oauth": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scope": "read write"
  }
}

​
Paste Configuration

Import a connection configuration from JSON:
  1. Copy a configuration JSON (from another inspector instance or saved file)
  2. Paste it into the URL field
  3. The form automatically populates with all settings
The paste detection only works when pasting into the URL field. The inspector recognizes valid JSON configuration and populates the form automatically.

​
Sharing Configurations

You can share connection configurations with team members:
  1. Export your configuration (Copy Config)
  2. Share the JSON via secure channel
  3. Recipients paste into their inspector
  4. All settings are automatically applied
Never share configurations containing sensitive credentials. Remove OAuth tokens, API keys, and other secrets before sharing.

​
Connection Status Indicators

The inspector shows visual indicators for connection status:
  • 🟢 Green: Connected and ready
  • 🟡 Yellow: Connecting or authenticating
  • 🔴 Red: Connection failed
  • ⚪ Gray: Disconnected
Hover over the indicator to see detailed status information.