Skip to main content

​
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:
    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:
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

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.