MCP

Customermates exposes one MCP endpoint at https://customermates.com/api/v1/mcp. A connected client discovers all 48 CRM tools automatically. There are two ways to connect:

• Custom connector (OAuth): for Claude (web, desktop, mobile) and ChatGPT. Paste the URL, sign in, approve. No key to manage. Start on Connect with a custom connector.
• API key: for CLI and editor clients (Claude Code, Codex, Cursor, Gemini CLI) and raw HTTP. Send the 64-character key in the x-api-key header or a config file.

For end-to-end setup on one page, jump to your client: Claude Desktop, ChatGPT, Claude Code, Codex, Cursor, or Gemini. This page is the protocol reference.

When to use MCP

• You want your AI to read and write the CRM without copying IDs around.
• You want the AI to discover capabilities rather than hand-writing API calls.
• You want one endpoint that works across Claude, ChatGPT, Cursor, Codex, and other clients.

Use OpenAPI instead when an engineer or integration service already knows which endpoint it needs. OpenAPI is the canonical HTTP reference. MCP is the agent-native interface built on top.

The endpoint

POST https://customermates.com/api/v1/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: <your-64-character-key>

The endpoint speaks the Model Context Protocol (streamable HTTP variant). tools/list returns every tool with its JSON Schema. tools/call invokes a tool by name.

Because it is the streamable HTTP variant, every request must send Accept: application/json, text/event-stream. Without it the endpoint returns 406 Not Acceptable. The documented client guides configure the supported connection path; raw HTTP callers such as curl or scripts must add the header explicitly.

The x-api-key header is the API-key method. The key is 64 characters, base62 (a-z, A-Z, 0-9), and inherits the permissions of the user who created it. There is no per-key scoping. Custom-connector clients (Claude, ChatGPT) authenticate over OAuth instead and send a bearer token they obtain and refresh for you. See Connect with a custom connector.

Connect a client

Getting an AI client onto your workspace is the same three moves every time:

1. Create an API key

   Profile → API Keys → New key. Choose the guided setup for Claude, ChatGPT, Cursor, or Gemini, or a standard key for your own integration. The key is shown once, so copy it before closing the dialog.

2. Point the client at the endpoint

   Give the client POST https://customermates.com/api/v1/mcp with the x-api-key header from the step above, or connect through OAuth where the client supports it. The per-client guides in the table below carry the exact configuration.

3. Confirm the tools arrived

   Ask the client to list its tools. All 48 should appear, and get_workspace_context is the natural first call: it returns your user, company, roles, and connected accounts in one go.

The server exposes instructions when a client connects. Whether a client presents them to the model and how the model follows them depends on the exact client. Clients that support MCP prompts can also run the built-in get-started prompt for a personalized start.

Server instructions, prompts, and toolsets

The server sends workflow guidance when a client connects: read the schema first, find ids before writing, change relations only through manage_record_links, and ask before deleting or sending. That guidance is not a server-enforced confirmation gate. Verify how the chosen client passes instructions to the model and handles approval before granting write, delete or messaging access. In clients that support MCP prompts, a built-in get-started prompt can summarize the workspace to personalize the start.

The full 48-tool surface is the default. Append ?toolsets= to the endpoint URL to narrow it, for example /api/v1/mcp?toolsets=records,messaging. Keys and details are in Narrowing with ?toolsets=.

How the tool surface is shaped

The MCP surface is built so that models with weaker planning can use it reliably:

• Verb-first imperative names: create_contacts, update_deals, delete_records. No batch prefix. The verb matches intent.
• Merged periphery: custom columns, widgets, and webhooks each live behind one tool (manage_custom_columns, manage_widgets, manage_webhooks) with an action switch, so the model picks an action instead of choosing among many near-identical tools.
• Inline enum hints: every enum field lists its valid values inline in the description, so the model does not have to resolve external types.
• Filter examples inline: every filters parameter has a concrete JSON example in its description.
• Relationship safety: relations change only through manage_record_links (add or remove); passing null on a relationship array is rejected with a remediation hint.
• Immutable column type: manage_custom_columns keeps type and entityType fixed on update (taken from the existing column); changing a type means delete and recreate.
• Destructive flags: every destructive tool or action has destructiveHint: true and an IRREVERSIBLE description prefix.

CLI use

If you prefer a local client over a GUI, tools like mcporter can connect to the same endpoint. Store the API key once in the client config and call tools from the shell.

OpenAPI alongside MCP

Both live at the same base URL. MCP is /api/v1/mcp; the OpenAPI spec is at /api/v1/openapi. The OpenAPI operations map 1:1 to REST endpoints. MCP wraps supported operations as typed tools with instructions, annotations and the same product authorization. Those instructions do not add a second server-side confirmation step.

Tool catalog

Customermates exposes 48 MCP tools, all enabled by default. They cover records, workspace, messaging, social posts, documentation and deep research, custom columns, widgets, webhooks, admin, and support. Every destructive tool is flagged and starts its description with IRREVERSIBLE. Relations change only through manage_record_links; the update tools never touch them.

Two flags per tool:

• Read: no mutation.
• Destructive: deletes data or cannot be undone. For merged tools the flag applies to their delete-capable actions.

Full JSON Schema for every tool is available live at POST /api/v1/mcp with method: "tools/list".

Records

Seventeen tools work against the five record types (contact, organization, deal, service, task). Records carry custom columns defined per workspace, so get_record_schema is the anchor: it returns the custom-column ids and option values that writes need. Fields such as a deal or task status are configurable singleSelect custom columns, not fixed native fields; get_record_schema returns whatever columns the workspace actually has.

All create and update tools take custom-column values via customFieldValues; call get_record_schema first for the column ids.

Workspace

Messaging

Messaging-backed tools are available from the Pro tier in cloud mode. get_activities can still return audit-log changes without the messaging entitlement when the caller has Audit Log permission. Its messaging, connected-account, and calendar sources require Inbox permission plus the messaging entitlement.

Social posts

Typical social read flow

Choose a LinkedIn or Instagram entry whose status is ok from get_workspace_context.connectedAccounts, and use its id as connectedAccountId. When the person comes from an inbox thread, resolve get_messaging_threads.items[].participants[].identifier from list mode or get_messaging_threads.thread.participants[].identifier from detail mode first:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "identifier": "<get_messaging_threads.items[].participants[].identifier>",
  "profileType": "person"
}

Call get_social_profile with that request, then pass get_social_profile.id to get_social_posts.authorIdentifier for the first page:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "authorIdentifier": "<get_social_profile.id>",
  "limit": 10
}

If next_cursor is non-null, repeat the same connectedAccountId, authorIdentifier, and limit, set cursor to that value, and omit offset:

{
  "connectedAccountId": "00000000-0000-4000-8000-000000000001",
  "authorIdentifier": "<same get_social_profile.id>",
  "cursor": "<next_cursor>",
  "limit": 10
}

For a company, call get_social_profile with profileType=company and an identifier from linkedin_search_sales_companies.items[].id, linkedin_search_sales_leads.items[].current_positions[].company_id, linkedin_manage_sales_lists.items[].current_positions[].company_id, or get_social_profile.current_positions[].company_id.

Documentation and deep research

Custom columns

Widgets

Routines

Webhooks

Admin and team

Support

Narrowing with ?toolsets=

All 48 tools are on by default. To expose only part of the surface, append ?toolsets= with comma-separated group keys to the endpoint URL:

https://customermates.com/api/v1/mcp?toolsets=records,messaging

Keys: records, workspace, messaging, social, docs, custom-columns, widgets, routines, webhooks, admin, support. No parameter means everything; unknown keys are ignored. search and fetch are always on so deep-research connectors keep working on any narrowed surface.

When a call is refused

A refusal is data, not a crash. The result carries isError: true, a human-readable message in content, and a machine-readable envelope in _meta.failure with a kind and the offending issues, each naming the field path it belongs to:

{
  "isError": true,
  "content": [{ "type": "text", "text": "Webhook ID not found or not accessible." }],
  "_meta": {
    "failure": {
      "kind": "not_found",
      "issues": [{ "code": "custom", "path": [], "message": "Webhook ID not found or not accessible.", "customCode": "webhookNotFound" }]
    }
  }
}

kind is one of validation, authentication, authorization, not_found, conflict, rate_limit, or unavailable. Branch on it instead of matching message text:

• validation: the arguments were wrong. Read issues[].path, fix that field, and call again. get_record_schema resolves most of these.
• authorization: the caller's role does not permit it. Retrying never helps; say what was refused and which permission it needs. Roles are workspace-defined, so read get_workspace_context.roles rather than assuming a fixed set.
• not_found: the id does not exist, or belongs to another workspace. Every call is tenant-scoped, so an id from elsewhere reads as missing rather than forbidden.
• conflict: something already holds the resource. Read current state before retrying.
• rate_limit and unavailable: transient or capacity-bound. Back off, and surface unavailable as a provider problem rather than a user mistake.
• authentication: the key is missing, expired, or revoked. The user must issue a new one.

Entitlements refuse the same way. Messaging-backed tools need the Pro tier, Sales Navigator tools need that LinkedIn subscription, and connecting an account stops when the plan's channel limit is reached. Permission and entitlement are independent: a caller can have Inbox permission and still be refused for the plan, and the reverse.

Tool metadata and server-side constraints

• Client confirmation guidance. The server instructions tell the model to confirm before delete_records and every send tool. The MCP route executes an authorized tool call once the client makes it, so verify confirmation behavior in the client.
• Relations change only via manage_record_links. The update tools never touch relations, and null on a relationship array is rejected server-side with a remediation hint.
• Draft, then send. send_email and send_chat_message deliver immediately. When asked to prepare a message, the agent uses save_message_draft and the user sends from the inbox. A draft needs no existing conversation: pass connectedAccountId and recipients and the thread is created locally, appears in the inbox, and reaches the provider only when it is sent.
• Destructive flags everywhere. Every destructive tool or action has destructiveHint: true and an IRREVERSIBLE description prefix.
• Every enum field lists its valid values inline in the description, and every filters field includes a concrete JSON example.

Frequently asked questions

Next

• Custom connector: end-to-end setup on one page.
• Filter syntax: every operator, with examples.
• Webhooks: the other half of the agentic loop.