Connect Bob Shell to MCP servers that require user-delegated access with OAuth 2.1. Bob Shell manages the authentication and token refresh process so you do not need to manage tokens manually.

Note:

For general MCP configuration, see Configure MCP servers.

Overview

You can connect Bob Shell to Model Context Protocol (MCP) servers that act on your behalf, such as accessing your repositories, cloud resources, or enterprise services. These servers use OAuth 2.1 so you can sign in and approve access.

Bob Shell manages the authentication flow directly. When you configure a server that requires OAuth, Bob Shell opens an authorization window in your default browser. After you sign in and approve permissions, Bob Shell stores and refreshes your access tokens without requiring you to handle credentials manually.

Use OAuth when:

You need to access resources associated with your personal or enterprise user account

The server uses short-lived tokens that require automatic token refresh

You want to keep static credentials and secrets out of your configuration files

When you already have a static API token or personal access token that does not expire, you can use a Bearer token in headers instead.

How the authentication flow works

You add the remote MCP server URL to your configuration file without headers or env credentials.

When Bob Shell connects to the server, Bob Shell detects the OAuth requirements.

Bob Shell opens a browser sign-in window where you review requested permissions and approve access.

Bob Shell receives the authorization tokens and stores them securely across your sessions.

Bob Shell automatically refreshes tokens before they expire so you can work without interruption.

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

You can configure your MCP servers in either your global configuration (~/.bob/mcp_settings.json) or your project configuration (.bob/mcp.json).

Minimal configuration (automatic discovery)

When your MCP server provides automatic OAuth metadata discovery, you only need to specify the url:

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

Bob Shell detects the OAuth requirements upon connection and guides you through the browser sign-in process.

Custom OAuth parameters

When your identity provider requires a pre-registered client ID, custom scopes, or a client secret, configure the oauth object:

{
  "mcpServers": {
    "my-oauth-server": {
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id-from-idp",
        "clientSecret": "your-client-secret-if-required",
        "scope": "mcp:connect read:data"
      }
    }
  }
}

Configuration properties

Property	Type	Description
`url`	string	Remote MCP endpoint URL (required).
`oauth.enabled`	boolean	Set to `false` to disable OAuth, or `true` to require OAuth. Enabled by default when no `Authorization` header is present.
`oauth.clientId`	string	Pre-registered OAuth client ID issued by your identity provider.
`oauth.clientSecret`	string	OAuth client secret, if your authorization server requires one for confidential clients.
`oauth.scope`	string	Space-separated list of OAuth scopes you want to request.

Warning:

Adding a static Authorization header to an MCP server configuration turns off OAuth. When an Authorization header is present, Bob Shell does not initiate the OAuth flow. When OAuth is active, Bob Shell removes static Authorization headers before sending requests. Use only one authentication method per server.

Register Bob with your identity provider

When your identity provider (IdP) requires you to register Bob as a client application before you connect, use the following application settings:

Setting	Value
Application or client type	Public, Native, or Loopback (Authorization Code with PKCE)
Redirect URI	`http://127.0.0.1:33418/callback`
Additional redirect URIs	`http://127.0.0.1:33419/callback` through `http://127.0.0.1:33427/callback` (recommended if port 33418 is in use)
Grant types	Authorization Code (`authorization_code`) and Refresh Token (`refresh_token`)
Scopes	Scopes specified in your MCP server documentation

Copy the issued client ID into oauth.clientId in your configuration file.

Authenticate when prompted

When you connect to an OAuth-enabled server for the first time:

A browser window opens with the authorization prompt.

Review the permissions that the server requests.

Bob Shell saves your credentials and connects to the server tools automatically.

Troubleshooting

The authentication prompt does not open

Verify that you did not mark the server as disabled in your configuration.

Check that your configuration file does not include a static Authorization header in headers.

Restart Bob Shell to reinitiate the connection.

Check that your browser or firewall does not block local loopback connections on 127.0.0.1.

The identity provider returns a redirect URI mismatch error

Verify that your identity provider client registration includes http://127.0.0.1:33418/callback.

If port 33418 is busy, register additional ports from 33419 through 33427.

Authentication succeeds but the server fails to connect

Verify that the server URL is correct and accessible from your network.

Check that you approved all required scopes during the sign-in step.

Review server logs or documentation for prerequisite user roles or permissions.

Tokens expire frequently and you must re-authenticate

Confirm that your authorization server issues refresh tokens.

Check that your system clock is synchronized to prevent premature token expiration.

You want to sign out or switch accounts

Remove or rename the server entry in your configuration file and add it again. Bob Shell treats it as a new server and prompts you to sign in on the next connection.

MCP OAuth authentication