Bob supports OAuth 2.1 for MCP servers that require user-delegated access. Bob handles the authentication flow automatically, including token refresh, so you do not need to manage tokens manually.

For general MCP configuration, see Using MCP in Bob.

Overview

Some MCP servers need to act on behalf of you as a user, for example to read your GitHub repositories or access your Google Drive files. These servers use OAuth 2.1 to request your consent before accessing any data.

Bob handles the full OAuth flow automatically. When you connect to a server that requires OAuth, the server is marked with a needs authentication warning in the MCP settings and an authentication button appears. Click the button to open the authorization flow in your browser. After you authorize, Bob manages token storage and refresh without further manual steps.

This is different from static authentication methods such as a Bearer token in headers or an API key in env, which are suited to service accounts or tokens that do not expire. Use OAuth when:

The server needs access to resources owned by your user account

The server's authorization server issues short-lived tokens that must be refreshed

You want to avoid storing long-lived secrets in your MCP configuration files

How the authentication flow works

You add an OAuth-enabled MCP server to your configuration file (no headers or env credentials required)

When Bob first connects to the server, it detects the server's OAuth authorization metadata

Bob opens a browser-based authentication prompt asking you to sign in and grant consent

After you authorize, Bob stores the access and refresh tokens securely across sessions

Bob automatically refreshes tokens before they expire. You are not prompted again unless the refresh fails.

Bob IDE                     Authorization Server              MCP Server
   |                                |                               |
   |-- connect to server ---------->|                               |
   |<-- OAuth metadata (401) -------|                               |
   |-- open auth prompt ----------->|                               |
   |   (user signs in & consents)   |                               |
   |<-- authorization code ---------|                               |
   |-- exchange for tokens -------->|                               |
   |<-- access + refresh tokens ----|                               |
   |-- authenticated requests --------------------------------->    |
   |   (auto-refresh when needed)                                   |

Configure an OAuth-enabled server

OAuth-enabled MCP servers advertise their authorization requirements automatically. In most cases you only need the server URL — OAuth fields are optional. Bob also supports the following optional OAuth properties:

oauth: Set to false to disable OAuth for a server, or true to explicitly enable it

clientId: OAuth client ID, if required by the authorization server

clientSecret: OAuth client secret, if required by the authorization server

scope: Space-separated list of OAuth scopes to request

Example configuration:

{
  "mcpServers": {
    "my-oauth-server": {
      "url": "https://your-server-url.com/mcp"
    }
  }
}

Bob detects the OAuth requirement when it connects and initiates the flow. No headers or env credentials are needed.

Warning:

Adding a static Authorization header to an OAuth-enabled server disables automatic OAuth entirely. Bob will not attempt the OAuth flow. Conversely, when OAuth is active, Bob removes any static Authorization header before sending requests. Use one method only.

Authenticate when prompted

When Bob connects to an OAuth-enabled server for the first time:

An authentication prompt appears in the IDE

Review the permissions the server is requesting

Bob stores the tokens and completes the connection automatically

The prompt may appear in a browser window or an embedded webview, depending on the authorization server.

View and manage authentication status

To check or manage authentication for an MCP server:

Click the icon in the Bob panel.

Select the MCP tab.

Locate the server in the list.

Authenticated servers show a connected status indicator. If authentication has expired or been revoked, the server shows an error status.

To re-authenticate: Click next to the server to restart the connection. Bob opens the authentication prompt again.

Troubleshooting

The authentication prompt does not appear

Confirm the server is not marked as disabled in your configuration

Restart the server from the MCP settings tab

Check that your browser or webview is not blocking the authorization page

Authentication succeeds but the server fails to connect

Verify the server URL is correct and reachable

Check that you granted all required permissions during the consent step

Review the server's documentation for any additional setup requirements

Tokens expire frequently and re-authentication is required

Confirm the authorization server supports refresh tokens. Some servers issue access-only tokens with short lifetimes.

Check that your system clock is accurate, as clock skew can cause premature token expiry

You want to sign out or switch accounts

Restarting the server does not clear OAuth credentials. To sign out or switch accounts, use Reset auth from the MCP settings tab. This clears the stored tokens and triggers a fresh authentication prompt on the next connection.

MCP OAuth authentication