Bob Shell 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.

Note:

For general MCP configuration, see Configure MCP servers.

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, Bob opens 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 Shell                   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 in ~/.bob/mcp_settings.json (global) or .bob/mcp.json (project):

{
  "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 does 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:

A browser window opens with the authorization prompt

Review the permissions the server is requesting

Bob stores the tokens and completes the connection automatically

The prompt opens in your default browser. After you complete authorization, Bob Shell resumes the connection automatically.

Troubleshooting

The authentication prompt does not appear

Confirm the server is not marked as disabled in your configuration

Restart Bob Shell to reinitiate the server connection

Check that your browser 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 expiration

You want to sign out or switch accounts

Remove or rename the server entry in your configuration file and re-add it. This causes Bob to treat it as a new server and trigger a fresh authentication prompt on the next connection.

MCP OAuth authentication

Overview

How the authentication flow works

Configure an OAuth-enabled server

Authenticate when prompted

Troubleshooting

On this page