Connecting Harmony MCP

Harmony MCP (Model Context Protocol) lets you connect AI assistants and compatible tools directly to your Harmony workspace. Authentication is handled through a dedicated OAuth login page that guides you through a secure token exchange and lands you back in your tool - ready to work.

This article explains how to connect a supported MCP client to Harmony using the OAuth login flow.

Before You Begin

Make sure you have the following before starting the connection:

• An active Harmony account with the permissions needed for the workspace you want to connect.
• An MCP-compatible client or AI assistant (for example, a tool that supports the Model Context Protocol).
• A stable internet connection to complete the OAuth redirect flow.

Connecting Your MCP Client

Step 1 - Initiate the Connection from Your MCP Client

Open your MCP-compatible client and locate the option to add or connect a new MCP server. When prompted for the server URL or integration endpoint, enter your Harmony MCP endpoint. The exact location of this setting depends on the client you are using - refer to that tool's documentation if you are unsure where to add a new server.

Once you confirm the endpoint, the client will redirect you to the Harmony MCP OAuth login page to complete authentication.

Step 2 - Log In on the MCP OAuth Page

The Harmony MCP OAuth login page handles authentication through a Descope token exchange flow. On this page:

1. Enter your Harmony credentials if you are not already signed in.
2. Review the permissions being requested by the MCP client.
3. Click Authorize to approve the connection.

The page validates your authorization request before proceeding. If the request contains invalid or missing parameters, you will see a clear error message explaining the issue so you can correct it and try again.

Step 3 - Return to Your MCP Client

After you authorize the connection, the OAuth flow completes and you are redirected back to your MCP client. The client receives a secure access token and the connection to your Harmony workspace is established. You do not need to copy or paste any tokens manually.

Troubleshooting

Invalid Authorization Request Error

If you see an error on the OAuth login page indicating that the authorization request is invalid, check the following:

• The MCP client is using the correct Harmony MCP endpoint URL.
• The client has been configured with the right OAuth parameters (client ID, redirect URI, and scopes).
• Your Harmony account has the necessary permissions for the workspace being accessed.

If the problem persists, re-initiate the connection from your MCP client to generate a fresh authorization request.

Connection Not Completing

If you are redirected to the OAuth page but the flow does not complete:

• Check that your browser is not blocking redirects or third-party cookies.
• Ensure you are logged in to the correct Harmony account before authorizing.
• Try opening the OAuth page in a private or incognito window to rule out cached session issues.

Revoking Access

To disconnect an MCP client from your Harmony workspace, navigate to your account settings and review the list of authorized applications. Locate the MCP client entry and revoke its access. The client will no longer be able to use the issued token and will need to go through the OAuth flow again to reconnect.