A Guide to Upgrading Your MCP Server to OAuth

Upgrading your MCP server to use OAuth 2.0 is a significant improvement. It eliminates the need for users to store sensitive credentials in a configuration file and enhances security by using short-lived access tokens and refresh tokens. This guide explains the process by walking through the transformation of a Salesforce MCP server with only username/password authentication to a server that supports OAuth. The changes detailed below reflect the refactoring shown in this commit: https://github.com/xeris-ai/mcp-servers-oauth/commit/37a7c16d0dc2f36e45226c744a24be68340387bc.

The OAuth Advantage

Instead of relying on a username and password, OAuth works by:

1. Authorization: The user is redirected to the service provider's login page (e.g., Salesforce).
2. Consent: The user logs in and grants your application permission to access their data.
3. Token Exchange: The service provider sends a temporary "authorization code" back to your server. Your server then exchanges this code for an access token and a refresh token.
4. Secure Access: The server uses the access token to make API calls on the user's behalf.
5. Token Refresh: When the access token expires, the server uses the long-lived refresh token to get a new access token without requiring the user to log in again.

Step 1: Register an OAuth Application

Before you write any code, you need to set up an OAuth application with your service provider. This process is similar for most services, such as Salesforce and Atlassian.

1. Go to the service provider's developer console or admin panel. For Salesforce, this is in Setup > Apps > App Manager.
2. Create a new application. Choose a name and a description.
3. Configure the OAuth settings. This is the most crucial part.
   • Redirect URI: Specify the URL where the service provider should send the user back after they log in. For local development, this is often something like http://localhost:8080/callback.
   • Scopes: Define the permissions your server needs (e.g., api, offline access).
4. Save the application. The service will provide you with a Client ID and a Client Secret. Treat the Client Secret like a password; never share it publicly.

Step 2: Implement the OAuth Flow in Your Code

This section explains the code changes required in server.py to integrate with the existing oauth_flow.py module, as seen in the linked commit.

The New oauth_flow.py Module

This is a new file that handles the entire user-facing OAuth process. Its primary job is to open a browser window for the user, listen for the callback from the service provider, and exchange the authorization code for tokens. The full code for this module can be found here: oauth_flow.py

Here are the key components and their functions:

• A simple web server: The module uses a lightweight framework like Flask or a simple HTTP server to listen on a specified port (e.g., 8080).
• The callback() endpoint: This is the destination for the redirect_uri you configured in Step 1. It captures the authorization code or any error messages from the service provider.
• PKCE (Proof Key for Code Exchange): This is a security measure that prevents a common type of attack. The _generate_pkce() function creates a secure challenge that the server sends to the service provider and a verifier that it uses to confirm its identity when requesting the final token.
• perform_oauth_flow(): This method orchestrates the entire process:
  1. Starts the local web server in a background thread.
  2. Generates the authorization URL with the correct parameters, including the Client ID, redirect URI, and PKCE challenge

... View full README on GitHub