> 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

Connect Claude, ChatGPT, Cursor, Notion and other MCP clients to Harmony: the server URL for your region and the setup steps for each client.

Harmony MCP (Model Context Protocol) lets you connect AI assistants and compatible tools directly to your Harmony workspace. You sign in with your Harmony account through a secure OAuth login, and the client then works in Harmony on your behalf.

This article gives the Harmony MCP server URL for your region and explains how to connect each supported client. In your client, the server appears as **Harmony Copilot** (or `harmony-copilot`). That is Harmony MCP.

### Before You Begin

* **A Harmony account.** Anyone who can sign in to Harmony can connect. The client can only see and do what your own Harmony permissions allow.
* **An MCP client** that supports remote MCP servers with OAuth sign-in, such as Claude, ChatGPT, Cursor or Notion. Some clients need a specific plan; each section below says which.
* **Your region.** Harmony runs in the United States and in Europe, and each region has its own server URL. If you are not sure which region your workspace is in, ask your Harmony administrator.

### Server URL

**United States**

```
https://api.harmony.io/copilot/mcp
```

**Europe**

```
https://api.harmony.io/_c/eu/copilot/mcp
```

Use the URL for your workspace's region. The other region's URL cannot sign you in.

You sign in and authorize Harmony the first time a client connects. You do not need a client ID, a client secret or a token: clients register with Harmony automatically.

### Setting Up Your Client

Pick your client:

{% tabs %}
{% tab title="Claude Code" %}
Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account, or access through a supported cloud provider.

1. **Add the Harmony MCP server.** In a terminal (not inside a running Claude Code session), run the command for your region. `--scope user` makes the server available in all your projects.

   United States:

   ```bash
   claude mcp add --scope user --transport http harmony-copilot https://api.harmony.io/copilot/mcp
   ```

   Europe:

   ```bash
   claude mcp add --scope user --transport http harmony-copilot https://api.harmony.io/_c/eu/copilot/mcp
   ```

   If you added harmony-copilot before without `--scope`, remove that entry first with `claude mcp remove harmony-copilot`.
2. **Open the MCP servers list.** Start Claude Code (`claude`) and run the `/mcp` slash command. Until you sign in, harmony-copilot shows that it needs authentication.
3. **Authenticate.** Select **harmony-copilot**, press Enter and choose **Authenticate**. Your browser opens the Harmony sign-in page. Sign in with your Harmony account and approve access. If the browser does not open, copy the URL shown in the terminal and open it yourself.
4. **Use it.** Ask in plain language, for example "Using Harmony, list my open tickets". If Claude Code asks for permission the first time it calls Harmony, approve it.

You can also sign in from your shell with `claude mcp login harmony-copilot`. See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for more.
{% endtab %}

{% tab title="Claude & Cowork" %}
Custom connectors work in Claude on the web, in Claude Desktop and in Cowork, on the Free (one custom connector), Pro, Max, Ultra, Team and Enterprise plans. Cowork needs a paid plan. On mobile, add and connect the connector on the web or in Claude Desktop first; it is then available on your phone.

**Team and Enterprise: an Owner adds the connector once for the organization.** On Team plans, Owners and Primary Owners can do this; on Enterprise plans, also people with a custom role that includes "Manage access to Libraries".

1. Go to **Organization settings** → **Connectors**.
2. Click **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**.
3. Enter `Harmony Copilot` as the name and your region's server URL as the remote MCP server URL, then click **Continue** if the dialog shows it.
4. Review the authentication settings. Under authentication, choose **Sign in now** or **Sign in when needed**, never the no-sign-in option. For the OAuth client, choose **Register automatically**. Leave **Request headers** empty if that section is shown. Click **Continue** if shown.
5. Click **Add**.

Then each member connects once:

1. Go to **Customize** → **Connectors**. In Claude Desktop, select **Customize** in the sidebar, then **Connectors**.
2. Find **Harmony Copilot** and click **Connect**. Sign in with your Harmony account and approve access.

**Free, Pro, Max and Ultra: add the connector yourself.**

1. Go to **Customize** → **Connectors**.
2. Click **Add**, then **Add custom connector**.
3. Enter `Harmony Copilot` and your region's server URL and click **Continue**. Choose the authentication settings as in step 4 above, then click **Add**.
4. If the connector shows **Connect**, click it, sign in with your Harmony account and approve access.

**Use it in a chat or a Cowork task.** Click the **+** button at the lower left of the message box, choose **Connectors** and turn on **Harmony Copilot**. This is set per conversation. When Claude asks to use a Harmony tool, approve it.

See [Get started with custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for more.
{% endtab %}

{% tab title="ChatGPT" %}
Full support for custom MCP servers (read and write tools) is available on ChatGPT Business, Enterprise and Edu, in ChatGPT on the web. On Business, workspace owners and admins can add custom MCP servers. On Enterprise and Edu, an admin gives members the **Create plugins with MCPs** permission under **Workspace settings** → **Permissions & roles**.

1. **Add the server.** In ChatGPT on the web, open **Plugins** (chatgpt.com/plugins). Select the **+** button, then **Add custom MCP server**.
2. **Enter the details.** Name it `Harmony Copilot`. Under **Connection**, enter your region's server URL as the **Server URL**.
3. **Set authentication.** Choose **OAuth** and leave any client ID and client secret fields empty: ChatGPT registers with Harmony automatically.
4. **Create it.** Review the risk warning, select **I understand and want to continue**, then **Create as a plugin**.
5. **Install it.** Open **Plugins** → **Personal** (or the workspace where you created it), open **Harmony Copilot** and select the **+** button to install it.
6. **Connect.** When ChatGPT asks, during installation or the first time you use it, sign in with your Harmony account and approve access.
7. **Use it.** In a new chat, type `@` and select **Harmony Copilot**, or describe what you need and let ChatGPT choose. ChatGPT asks you to confirm actions that change data.

If you can't add custom MCP servers, ask a workspace admin to create Harmony Copilot and share or publish it to the workspace. You then install it from your workspace's tab in **Plugins** and connect with your own Harmony account.

See [Add custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server) for more.
{% endtab %}

{% tab title="Cursor" %}

1. **Add the Harmony MCP server.** Open `~/.cursor/mcp.json` (create it if it does not exist) and add the `harmony-copilot` entry for your region inside `mcpServers`. Keep any servers already in the file. Save the file and restart Cursor.

   United States:

   ```json
   {
     "mcpServers": {
       "harmony-copilot": {
         "url": "https://api.harmony.io/copilot/mcp"
       }
     }
   }
   ```

   Europe:

   ```json
   {
     "mcpServers": {
       "harmony-copilot": {
         "url": "https://api.harmony.io/_c/eu/copilot/mcp"
       }
     }
   }
   ```

   The file in your home folder makes the server available in every project. A `.cursor/mcp.json` file inside a project adds it to that project only.
2. **Find the server.** Open **Customize** in the sidebar and choose **MCPs**. Some Cursor versions list MCP servers under **Cursor Settings** → **Tools & MCP** instead.
3. **Authenticate.** On the harmony-copilot row, click **Authenticate** (**Connect** in some versions). Your browser opens the Harmony sign-in page. Sign in with your Harmony account and approve access. harmony-copilot then shows as connected.

If the harmony-copilot row shows an error and no way to sign in, check the URL for your region, restart Cursor, and if it persists contact Harmony support. See the [Cursor MCP documentation](https://cursor.com/docs/mcp) for more.
{% endtab %}

{% tab title="Notion" %}
Available on Notion Business and Enterprise plans. The connection belongs to a Custom Agent.

1. **Turn on custom MCP servers (workspace admin, once).** Go to **Settings** → **Connections**, open the **Manage** tab and turn on **Enable custom MCP servers**.
2. **Approve the Harmony URL (Enterprise, only if installs are limited).** If **Manage permissions** → **Limit which connections members can install** is set to **Approved & recommended** or **Approved only**, select **Approved connections** → **Add approved connection** → **Custom MCP server**, enter your region's server URL and click **Save**.
3. **Open the agent's tools.** Open your Custom Agent's **Settings** and go to **Tools & Access**. You need Full Access or Can Edit on the agent.
4. **Add the connection.** Click **Add connection** → **Custom MCP server**. Enter your region's server URL and, optionally, the display name `Harmony Copilot`. Harmony uses OAuth sign-in, so you do not need an API key or token.
5. **Connect.** Click **Connect**, then sign in with your Harmony account and approve access.
6. **Choose the tools.** Under **Tools & Access**, expand the Harmony Copilot connection and turn each tool on or off, and choose which can run automatically.

The connection uses the Harmony account you signed in with. Anyone who can use the agent can use its Harmony tools through it, so share the agent only with people who should have that access.

See [MCP connections for Custom Agents](https://www.notion.com/help/mcp-connections-for-custom-agents) for more.
{% endtab %}

{% tab title="Other clients" %}

1. **Add the server.** In your MCP client, find the option to add a remote MCP server and enter your region's server URL. If the client asks for an authentication type, choose OAuth, and leave any client ID and secret empty: Harmony supports dynamic client registration.
2. **Sign in.** The client opens the Harmony sign-in page. Sign in with your Harmony account and approve access.
3. **Return to your client.** After you approve, you are sent back to your client and the connection to your Harmony workspace is ready.
   {% endtab %}
   {% endtabs %}

### Troubleshooting

#### Sign-in fails or the client gets "Unauthorized"

* **Check the server URL first.** The other region's URL cannot sign you in. Compare the URL in your client with the server URLs above, fix it if needed and connect again.
* **Sign in again.** If the client worked before, its sign-in may have expired. Clear the client's authentication for Harmony (or remove and add the server again) and sign in.
* **Check the account.** Sign in with the Harmony account for the workspace you want to connect.

If it still fails, contact Harmony support and tell them which client you use and your region.

#### "Uh-oh, something went wrong" on the sign-in page

The sign-in page shows this, with an error code below it, when it cannot accept the client's sign-in request: for example a request that is incomplete or out of date, or one sent to the other region's server. Check the server URL for your region, then start the connection again from your client: remove the Harmony server or clear its sign-in, then add it again or choose authenticate again.

If you land on the same page again, note the error text shown on it and send it to Harmony support.

#### Sign-in does not complete

If you reach the sign-in page but never get back to your client:

* Check that your browser is not blocking pop-ups, redirects or third-party cookies.
* Make sure you are signed in to the right Harmony account before approving.
* Try the sign-in in a private or incognito window to rule out a cached session.

### Disconnecting

To stop a client from using Harmony, remove the connection in the client:

* **Claude Code:** run `claude mcp logout harmony-copilot`, then `claude mcp remove harmony-copilot --scope user`. If you added the server without `--scope`, run `claude mcp remove harmony-copilot` instead. To sign out but keep the server, run `/mcp`, select harmony-copilot and choose **Clear authentication**.
* **Claude & Cowork:** go to **Customize** → **Connectors**, select Harmony Copilot and click **Disconnect**. Owners remove it for the whole organization in **Organization settings** → **Connectors**.
* **ChatGPT:** open Harmony Copilot in **Plugins** and uninstall it, if that option is shown. OpenAI notes that uninstalling a plugin does not always disconnect its MCP connection: if Harmony Copilot still shows as connected, disconnect it there too. For a plugin your workspace published, ask your workspace admin.
* **Cursor:** remove the server in **Customize** → **MCPs**, or delete its entry from `mcp.json` and restart Cursor.
* **Notion:** open the agent's **Settings** → **Tools & Access**, find the Harmony Copilot connection and click **Disconnect**.

Disconnecting removes the client's sign-in, and the client has to sign in again to reconnect. Harmony does not show a list of connected clients. If you need a client blocked on Harmony's side, for example after losing a device, contact Harmony support: they can stop its sign-in from renewing, and its access ends when its current sign-in expires.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/settings/connecting-harmony-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
