> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP client

> Connect a supported AI client once for all of your Overlap organizations.

## Before you connect

You need:

* an active Overlap account
* membership in at least one organization shown by Overlap's OAuth picker
* any organization selected as the initial default during OAuth

Your connection follows your current organization memberships. The selected organization is only the default, and you do not reconnect for every organization. Your role in each organization still controls what you can do there; publishing is organization-admin only by default.

## Connect Codex desktop

**Desktop app setup** is recommended and is the fastest way to connect:

1. In Overlap, open **Settings → AI Agents & MCP** and click **Copy MCP URL** beside **Codex desktop**.

2. Open the Codex desktop app, click **Settings**, and turn on **Developer mode**.

3. Open **Plugins**, select **MCP**, then click **Add MCP server**.

4. Enter exactly these values:

   ```text theme={null}
   Name: Overlap
   Server type: Streamable HTTP
   MCP URL: https://mcp.overlap.ai/mcp
   OAuth Client ID: leave empty
   OAuth Client Secret: leave empty
   ```

   No API key or other value is required.

5. Click **Add** or **Save**. If Codex offers **Restart**, click it. Then click **Authenticate** beside Overlap and finish signing in.

6. Start a new conversation and enter `/mcp` to confirm that Overlap is connected.

### Codex CLI fallback

Use Terminal only if **Developer mode** or **Plugins → MCP** is unavailable, or if you need to reset an existing saved connection. In Overlap **Settings → AI Agents & MCP**, click **Copy commands**, then run all four commands:

```bash theme={null}
codex mcp logout overlap
codex mcp remove overlap
codex mcp add overlap --url https://mcp.overlap.ai/mcp --oauth-resource https://mcp.overlap.ai/mcp
codex mcp login overlap --scopes openid,offline_access,user:org:read
```

The first two commands clear only the saved Overlap MCP credentials and configuration. A “not found” message is harmless on first setup; the following commands still run. Keep Terminal open until browser authentication finishes, then restart the desktop app.

For ordinary reauthentication, run `codex mcp login overlap --scopes openid,offline_access,user:org:read`. If the command fails immediately without opening a browser, run the complete four-command reset above instead.

## Connect Claude Desktop

Claude cannot add account-level connectors from inside a conversation. Add Overlap from Claude Desktop's connector settings first.

### Free, Pro, or Max

1. In Overlap **Settings → AI Agents & MCP**, click **Copy MCP URL** beside **Claude Desktop**.
2. Open Claude Desktop and click **Customize → Connectors**.
3. Click **+**, then click **Add custom connector**.
4. Enter `Overlap` as the name and paste `https://mcp.overlap.ai/mcp` as the URL.
5. Leave **Advanced settings** empty. No OAuth Client ID or Client Secret is needed.
6. Click **Add**, then click **Connect** and complete OAuth.
7. In each conversation, click **+** beside the composer, click **Connectors**, and enable **Overlap**.

### Team or Enterprise

An Owner or Primary Owner must first:

1. Open **Organization settings → Connectors**.
2. Click **Add**.
3. Hover over **Custom**, then click **Web**.
4. Paste `https://mcp.overlap.ai/mcp`, leave the advanced OAuth fields empty, and click **Add**.

Members can then open **Customize → Connectors**, find Overlap, and click **Connect**. They still enable Overlap per conversation with **+ → Connectors** beside the composer.

## Verify the connection

Only after installation, open Overlap **Settings → AI Agents & MCP** and click **Copy test prompt**. Start a new conversation and paste it:

Try:

> Use the Overlap MCP connection that is already installed. Call overlap.organizations.list, show every organization available to me, then call overlap.context.get for my default organization and summarize my capabilities. Do not add or reconfigure the MCP server, and do not make any changes.

To inspect and use another membership without reconnecting, ask:

> Call overlap.organizations.list, find Casey 3, then use its organization ID to show that organization's Social Calendar for the next 30 days. Do not make changes.

## Permission groups

| Permission               | Allows                                                         |
| ------------------------ | -------------------------------------------------------------- |
| `overlap:read`           | Workflows, clips, documentation, calendar, and analytics reads |
| `overlap:workflows:run`  | Starting and cancelling workflow runs                          |
| `overlap:clips:write`    | Updating allowed clip metadata or transcripts                  |
| `overlap:renders:create` | Creating asynchronous render jobs                              |
| `overlap:calendar:write` | Creating and editing unapproved calendar drafts                |
| `overlap:social:publish` | Publishing immediate drafts and cancelling authorized posts    |

Publishing permission is restricted to organization admins by default.

## Disconnect

Revoke the OAuth connection from your MCP client. This disconnects that client from all of your Overlap organizations. It does not change your memberships or existing REST API keys.

## Troubleshooting

* **No organization appears:** confirm that you are a current Clerk organization member.
* **The selected organization is rejected:** confirm that your membership is still active. A global organization allowlist is used only as an emergency incident-control setting.
* **Codex does not show MCP:** confirm that **Developer mode** is enabled, then reopen **Plugins → MCP**.
* **Codex does not show Overlap:** confirm that you clicked **Add** or **Save**, restarted if prompted, and then clicked **Authenticate** beside Overlap.
* **Codex OAuth times out:** use the CLI fallback, run `codex mcp login overlap --scopes openid,offline_access,user:org:read`, and keep Terminal open until browser approval finishes.
* **Claude says it cannot add a connector:** use **Customize → Connectors**; connector installation is not available from chat.
* **A token is rejected after OAuth:** confirm that the MCP resource is exactly `https://mcp.overlap.ai/mcp` and reconnect.
* **The server reports `DecodeError`:** the deployed MCP revision is JWT-only. Deploy a revision that supports Clerk's revocable opaque OAuth tokens, then reconnect.
* **A tool is missing:** your OAuth scopes, current organization role, or an MCP safety kill switch may not permit it.
* **Publishing is blocked:** switch to an organization where you are an admin, or ask an organization admin to perform the publish action.
* **A confirmation expired:** retry the original action. Confirmation requests expire after ten minutes and cannot be replayed.