> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/settings/connecting-harmony-mcp.md). # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/settings/connecting-harmony-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.