Custom connector
Add Customermates to Claude (web, desktop, mobile) or ChatGPT as a custom MCP connector: OAuth sign-in, no API key, plus a ChatGPT header fallback.
Customermates is a source-available, 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.
Claude offers custom connectors on every plan (Free, Pro, Max, Ultra, Team, Enterprise); Free allows one custom connector (Anthropic help, checked on 3 November 2026). In ChatGPT they are a paid feature (Plus, Pro, Business, Enterprise).
Which URL do I paste?
Every workspace has its own MCP URL:
<BASE_URL>/api/v1/mcp/w/<WORKSPACE_ID><BASE_URL> is the address you open Customermates at, in the cloud or on your own instance, and <WORKSPACE_ID> names the workspace. You do not have to put it together: Customermates shows the URL of your current workspace with a copy button under API keys & connectors when you click Add and choose Claude and then Claude account (or ChatGPT & Codex and then ChatGPT App), and in the onboarding step Connect the AI you already use. Switch workspaces to copy another one's URL.
Because each workspace has its own URL, you can add several workspaces to Claude at the same time, one connector per workspace. Claude refuses a second connector with a URL it already has ("A connector with this URL already exists in your organization"), so a second workspace needs its own URL.
<BASE_URL>/api/v1/mcp keeps working: it serves the same tools, and the consent screen asks which workspace the connection gets. Connections you added with it before stay as they are.
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:
Open the connector form
Claude → Settings → Connectors → Add custom connector.
Paste the URL
Leave authentication on the default (OAuth). No header, no key.
Sign in and approve
A Customermates window opens. Sign in, then click Approve on the consent screen.
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 API keys & connectors, click Add, choose Claude under Quick connections, then Claude account, and click Add to Claude. It opens Claude's add-connector dialog pre-filled with the current workspace's URL and a connector name that includes the workspace name (Claude web and Teams only). The onboarding step Connect the AI you already use offers the same button. Add needs Create on API & Webhooks; without it, paste the URL as above.
How do I connect ChatGPT?
To connect ChatGPT, open in ChatGPT: Settings → Connectors → Add connector → Custom connector (MCP).
- Name: Customermates
- URL: your workspace's URL,
<BASE_URL>/api/v1/mcp/w/<WORKSPACE_ID>(which URL) - Authentication: OAuth
Save. ChatGPT opens a Customermates window. Sign in, then click Approve on the consent 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:
Create a key
In Customermates, open API keys & connectors, click Add and choose Standard API key. Copy the 64-character string immediately. It is shown once. Creating a key needs Create 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.
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. Customermates checks the key on every request: with a wrong, truncated, expired or deleted key the server answers HTTP 401 with a WWW-Authenticate header and nothing is listed, so create a new key.
What does the consent screen show?
The connector opens a Customermates window:
Sign in
Or you are already signed in.
Read what is being authorized
The consent screen, titled Connect … to …, 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. With a workspace's URL, it shows that workspace with its avatar, and the connection gets exactly that workspace. With
<BASE_URL>/api/v1/mcpand several workspaces, it asks which workspace the connection gets; your current workspace is preselected.Approve
Click Approve, or Deny to refuse.
You return to your AI, connected, with the Customermates tools listed.
If you cannot connect the workspace of the URL, the screen says why and offers only Deny: you are not a member of it (sign in with the account you use there), your request to join is waiting for approval, your access is deactivated, your role has no Read access All on API & Webhooks, the workspace has no active subscription, or updated terms need to be accepted.
The connector accepts any client, so the consent 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, but your role needs Read access All on API & Webhooks, as for every MCP connection; without it the screen refuses the connection.
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 the workspace chosen on the consent screen and with that user's role permissions there. API keys work the same way: they inherit the owning user's permissions in the workspace they were created in, and there is no per-key scoping.
- A connection stays in its workspace, refreshed tokens included. To work in several workspaces, add one connector per workspace with that workspace's URL; they work side by side in the same Claude account. See Workspaces.
- 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 Edit 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 field on the Acme deal to Won and add a note that the contract was signed today."
- "Which client conversations are waiting for my reply? Draft an answer to the oldest one and save it as a draft."
The reply prompt needs a channel connected on Customermates Cloud from Pro; the draft waits in the conversation until you review and send it.
Each workspace defines its own record types, such as contacts, deals or tasks, and fields such as a deal's stage or a task's priority are configured per workspace too. Ask your AI to call discover_record_types and get_record_model to see the relevant fields and 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, and so doesmanage_team, whoseremove_memberrevokes a member's access. Among the unflagged tools aresend_email,send_chat_message,request_support,manage_social_relations,publish_social_postandcomment_on_social_post, which reach real people, andmove_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?
| Symptom | Cause | Fix |
|---|---|---|
| "Couldn't register with the sign-in service" (Claude) or "Connector verification failed" (ChatGPT) | Server URL wrong or unreachable | Copy the URL again from Customermates (which URL), or use exactly <BASE_URL>/api/v1/mcp, with the address you open Customermates at as <BASE_URL> |
| "A connector with this URL already exists in your organization" (Claude) | That URL is already connected, possibly for another workspace | Add the other workspace with its own URL, copied while that workspace is open |
A workspace's URL answers HTTP 401 with error="invalid_token" | The connection was approved for another workspace | Reconnect; the client signs in again for the workspace of the URL |
A workspace's URL answers HTTP 403 with error: workspace_mismatch (header key) | The API key belongs to another workspace | Use the URL of the key's workspace, or create a key in this workspace |
The connector lists no tools and the server answers HTTP 401 (ChatGPT with a header) | The x-api-key value is wrong, truncated, expired or deleted | Create a new key under API keys & connectors and paste the full 64 characters |
| Every call that reads or changes workspace data says "Your user account is inactive. Contact a workspace administrator." | Your Customermates user was set to Inactive | A member with Edit on Users & Roles sets you back to Active under Members |
| No "Add custom connector" option | Free plan | ChatGPT needs a paid plan; Claude Free allows one custom connector, so remove another one first. See the CLI method |
| Approved but nothing connects | You approved from a different account | Sign into the right Customermates account, then retry |
| "Tool not found" | Stale connector cache | Remove and re-add the connector |
| Server rejects a relationship update | The relationship ID or endpoint is missing or inaccessible | Ask the agent to read get_record_model, then use mutate_crm_record with link or unlink |
| Select field rejected | Value not in the field's option list | Ask the agent to call get_record_model first |
| A messaging, calendar or social tool is refused with a plan message | The workspace has no plan with messaging (Starter, self-hosted, or no active subscription or trial) | On Cloud, a member with Edit on Company chooses Pro or higher under Billing. Self-hosted instances have no messaging; use Customermates Cloud for these tools |
On a free plan or in a CLI?
ChatGPT needs a paid plan for custom connectors (Claude Free allows one), 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.