Custom connector

Customermates is an open-source, AI-native CRM that your AI operates directly over MCP. The custom connector is the simplest way to connect: paste one URL, sign in to Customermates, and approve access. There is no API key to copy, no config file to edit, and no shim to install. You authorize once and the connection persists.

This is the recommended path for Claude (web, desktop, and mobile) and ChatGPT. On a CLI or editor (Claude Code, Codex, Cursor, Gemini CLI), use the API key method instead.

Which URL do I paste?

<BASE_URL>/api/v1/mcp

<BASE_URL> is the address you open Customermates at, in the cloud or on your own instance. The connector works on every Customermates plan and on self-hosted instances; only the messaging, calendar and social tools need a plan with messaging, Pro or higher in the cloud.

How do I connect Claude to the Customermates CRM?

To connect Claude to your CRM, add Customermates as a custom connector in Claude:

1. Open the connector form

   Claude → Settings → Connectors → Add custom connector.

2. Paste the URL

   Leave authentication on the default (OAuth). No header, no key.

3. Sign in and approve

   A Customermates window opens. Sign in, then click Approve on the Authorize access screen.

4. Confirm the tools arrived

   Back in Claude, Customermates appears with its tools listed.

Add it once and it syncs to Claude on web, desktop, and mobile. The connection is tied to your Claude account, not one device, and refreshes in the background.

One click instead: in Customermates, open My Profile → API & Connectors, press Add, choose Claude under Quick connections, then Claude account, and click Add to Claude. It opens Claude's add-connector dialog pre-filled with your <BASE_URL>/api/v1/mcp (Claude web and Teams only). The onboarding step Connect your AI offers the same button. Add needs Manage on API & Webhooks; without it, paste the URL as above.

Link: the API & Connectors page, /profile/api-keys. Mate: navigate and highlight_element with nav-profile-api-keys; highlight_element also takes profile-api-keys-generate for Add (roles with API & Webhooks Manage). The Quick connections tiles and Add to Claude are not highlight targets, so Mate names them.

How do I connect ChatGPT?

To connect ChatGPT, open in ChatGPT: Settings → Connectors → Add connector → Custom connector (MCP).

• Name: Customermates
• URL: <BASE_URL>/api/v1/mcp
• Authentication: OAuth

Save. ChatGPT opens a Customermates window. Sign in, then click Approve on the Authorize access screen. Every Customermates tool is listed, with no key to store or rotate.

Can ChatGPT use an API key instead of OAuth?

Yes. Add the connector the same way, but authenticate with a header:

1. Create a key

   In Customermates, open My Profile → API & Connectors, press Add and choose Standard API key. Copy the 64-character string immediately. It is shown once. Creating a key needs Manage set to Yes on the API & Webhooks row of your role, and the page itself needs Read access All on that row; the built-in Admin role has both. See API keys.

2. Authenticate with a header

   In the connector form set Authentication: Header, Header name: x-api-key, Header value: your key.

Save. ChatGPT reaches the server and lists every tool. It lists them even when the key is wrong, because Customermates checks the key only when a tool reads or changes workspace data; if every such call then says "Sign in to use this action.", the key is wrong, truncated, expired or deleted, so create a new one. A documentation lookup such as search_docs answers even with a wrong key, so it does not prove that the key works.

Link: the API & Connectors page, /profile/api-keys. Mate: navigate and highlight_element with nav-profile-api-keys; highlight_element also takes profile-api-keys-generate for Add (roles with API & Webhooks Manage), then api-key-option-standard for Standard API key (prerequisite profile-api-keys-generate) and api-key-name, api-key-expires and api-key-save for Name, Expires in and Save (prerequisite api-key-option-standard). The Quick connections tiles are not highlight targets, so Mate names them.

What does the Authorize access screen show?

The connector opens a Customermates window:

1. Sign in

   Or you are already signed in.

2. Read what is being authorized

   The Authorize access screen names the app that is connecting, lists what it asks for (such as Confirm your identity, Read your basic profile, Read your email address and Stay connected while you are away), and shows Connection destination with the host it will send access to.

3. Approve

   Click Approve, or Deny to refuse.

You return to your AI, connected, with all 50 tools listed.

The connector accepts any client, so the Authorize access screen is the gate. Approve only a connection you started yourself, and click Deny for anything you did not start. Connecting over OAuth needs no API key and no extra role permission.

How long does the connection stay valid?

• Add it once on Claude web and it appears on desktop and mobile too. The connection is tied to your Claude account, not one device.
• It refreshes in the background. Use it within any 30-day window and you never re-authorize; go idle longer and you approve once more.
• Every call runs as the Customermates user who approved, inside that account's data and with that user's role permissions. API keys work the same way: they inherit the owning user's permissions, and there is no per-key scoping.
• If that user is set to Inactive, every call that reads or changes workspace data fails with "Your user account is inactive. Contact a workspace administrator." until a member with Manage on Users & Roles sets them back to Active.

What should I try first?

The server sends its instructions to your AI when it connects, so the client already has the workflow and safety rules. In clients that support MCP prompts (like Claude), you can also run the built-in get-started prompt for a personalized start: your name, your role, and a first summary of your workspace.

• "Pull the last ten contacts I created. Any without an email address?"
• "Create a contact for Jane Doe at Initech, link it to the Initech organization, and start a deal for 12 hours of consulting."
• "Set the Status column on the Acme deal to Won and add a note that the contract was signed today."

The record types are contact, organization, deal, service, and task. Fields such as a deal's status or a task's priority are configurable custom columns per workspace, not fixed product fields. Ask your AI to call get_record_schema to see the columns and their allowed values before writing.

Confirming tool calls: which ones can I always allow?

Customermates never stops a tool call to ask for confirmation; your client does, and you control it there. In Claude: Settings → Connectors → Customermates, then set each tool (or the read-only group) to Always allow or Ask.

• Reads (get_*, list_*, search_*) carry the read-only flag, so they are safe to allow.
• Tools that can delete carry the destructive flag and say IRREVERSIBLE.
• Tools that only create, change or send carry neither flag; merged tools with a delete action, such as manage_webhooks, carry the destructive flag. Among the unflagged tools are send_email, send_chat_message, request_support, manage_team invites and manage_social_relations, which reach real people, and move_email_thread, which moves mail in the real mailbox.

Leave every tool that is not read-only on Ask. The full list is in the MCP tool catalog.

What if the connection fails?

Link: the API & Connectors page, /profile/api-keys, the Members page, /company/members, and the Subscription page, /company/subscription (cloud only). Mate: navigate and highlight_element with nav-profile-api-keys, nav-company-members or nav-company-subscription. profile-api-keys-generate highlights Add on the API page (roles with Manage on API & Webhooks); the member rows are not highlight targets, so Mate names them; once a member row is open, member-modal-status highlights Status and member-modal-save highlights Save in the User dialog (roles with Manage on Users & Roles), and company-subscription-plan-picker outlines the plan cards while the picker is shown.

On a free plan or in a CLI?

Custom connectors need a paid plan, and CLI and editor clients do not use the connector flow at all. Both authenticate with an API key instead: see CLI & editors. Claude Desktop on a free plan can use the config-file fallback.

Next

• MCP tool catalog: every tool your AI can call.
• Webhooks: the other half of the agentic loop.
• CLI & editors: API-key setup for Claude Code, Codex, Cursor, and Gemini CLI.

Grok Bot

Grok Bot can work in Customermates through its browser. Ask it to open your Customermates URL, take over the sign-in when prompted, and then describe the task. Review drafts before sending. This browser workflow does not require a new Customermates API key.

Grok Bot and Grok's chat connectors have different setup flows. For Grok chat, add a custom MCP connector using <BASE_URL>/api/v1/mcp and complete authentication. See the official Grok Bot app guide and Grok connector guide.