Model Context Protocol (MCP)

TL;DR — 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. Paste the setup prompt to brief your AI on how to act safely.

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

Set up your AI once it's connected

MCP exposes tools, but it doesn't tell the model what your CRM is about. Paste the setup prompt as your first message. It covers:

• What the five entity types are and how they link.
• Safety rules (never pass null on relationship arrays, prefer link_entities / unlink_entities).
• A starting routine so the model orients itself before acting.

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.

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

• Setup prompt — paste into your AI's first message.
• MCP tool catalog — every tool, grouped and flagged.
• Webhooks — the other half of the agentic loop.