Model Context Protocol (MCP)

Point an MCP client at https://customermates.com/api/v1/mcp, send your API key in the x-api-key header, and the client discovers all 57 CRM tools automatically.

If you want full end-to-end setup for a specific client (API key, JSON config, setup prompt, first command, all on one page), jump directly to Claude, ChatGPT, or Cursor. This page is the protocol reference.

When to use MCP

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

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
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.

Connect a client

Every connect-* page includes the full setup prompt you should paste as your first message to brief the model on safe CRM usage.

How the tool surface is shaped for weak models

Not every model plans as well as Claude Opus. The MCP surface is built for the weak-model case:

• Verb-first imperative names: create_contacts, update_deal, delete_custom_column. No batch prefix. The verb matches intent.
• Narrow per-type tools: eight create_*_custom_column and eight update_*_custom_column tools instead of one discriminated-union giant. Weak models pick by name instead of by branching on type.
• Inline enum hints: every enum field lists its valid values inline in the description, so the model doesn't have to resolve external types.
• Filter examples inline: every filters parameter has a concrete JSON example in its description.
• Relationship safety: link_entities and unlink_entities merge; passing null on a relationship array is rejected with a remediation hint.
• Type-mismatch routing: calling the wrong per-type update returns "this column is type X, use update_X_custom_column".
• Destructive flags: every delete_* tool has destructiveHint: true and an IRREVERSIBLE description prefix.

The full tool list is at MCP tool catalog.

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.

Brief the agent on the first message

Once the client is connected, paste this as your first message before doing anything else. It tells the agent how to discover capabilities, how to handle write operations safely, and what guardrails apply.

You are now connected to my Customermates CRM through MCP.## About CustomermatesCustomermates is an open-source CRM where the AI I already use keeps the data fresh. Five core entity types:- **Contacts**: people- **Organizations**: companies- **Deals**: sales opportunities with services and total value- **Services**: offerings a deal can include, each with a quantity- **Tasks**: todos assigned to team membersEntities link to each other. A contact belongs to one or more organizations and one or more deals. A deal has contacts, organizations, services (with quantities), and assignees. A task has assignees only. Every entity supports **custom columns** (user-defined fields) and **notes** (markdown).## Before you do anything, ask me for1. My name and role, so you can tailor your replies.2. What I usually do with my CRM, in one sentence.## Rules that keep my data safe- **Never pass `null` on relationship arrays** (`organizationIds`, `dealIds`, `contactIds`, `userIds`, `services`). Null wipes the relationship. Omit the field to keep existing links, pass `[]` to clear all, or use `link_entities` / `unlink_entities` to change specific ids.- **Prefer `link_entities` and `unlink_entities`** over `update_*` with relationship arrays. They merge instead of replacing.- **Custom fields are per-column merge**. Only the columnIds you include are changed; the rest are preserved. To clear one field pass `{ columnId, value: null }`.- **Use the correct per-type custom-column tool**. `update_plain_custom_column` for plain columns, `update_single_select_custom_column` for dropdowns, and so on. The server will tell you if you picked the wrong one.- **Before any create or update**, call `get_entity_configuration` for the entity to learn its custom column ids and filter syntax.- **Destructive actions need confirmation.** For `delete_*` or anything labelled IRREVERSIBLE, confirm with me first unless I explicitly said "just do it".## Suggested first moves1. Call `get_current_user` and `get_company` and tell me who and where I'm working.2. Call `count_entity` for contact, organization, deal, service, and task.3. Call `list_custom_columns` so we don't recreate fields that already exist.4. Ask me what I want to work on first.## Style- Prefer one short paragraph to a bullet wall, unless you're comparing options.- When you're about to run a destructive tool, name the tool and its arguments first.- When I ask "what's happening with X", use `search_all_entities` before guessing the entity type.Ready. Please ask me what I want to focus on.

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 tools wrap those plus add safety guardrails the raw API doesn't have.

Next

• MCP tool catalog: every tool, grouped and flagged.
• Connect Claude: end-to-end setup on one page.
• Webhooks: the other half of the agentic loop.