CLI & editors

Customermates is the open-source, AI-native CRM. Once connected, your coding agent reads and writes contacts, deals, and notes without leaving the terminal. Every client here authenticates the same way: an API key in the x-api-key header against <BASE_URL>/api/v1/mcp, where <BASE_URL> is the address you open Customermates at, in the cloud or on your own instance. The snippets below already carry the address of the site showing this page; if you open Customermates elsewhere, replace that address as well as YOUR_KEY.

Create an API key

In Customermates, open API keys, click Add and choose Standard API key. Name it for the client (for example Claude Code); without an Expires in date it never expires. The 64-character key is shown once, so copy it immediately. Quick connections in the same dialog does this for you: it names the key after the client, sets it to expire after 365 days, and shows the setup snippet with the key filled in and its expiry below.

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. A key inherits the permissions of the user who created it; there is no per-key scoping. Create one key per client so you can revoke one without touching the others; the audit log records the user a key belongs to, not the key itself. API keys and MCP work on every plan and on self-hosted instances. Details: API keys.

Claude Code

Claude Code adds MCP servers via its CLI. One command does the setup. Run this in any terminal, replacing YOUR_KEY:

claude mcp add --transport http customermates https://customermates.com/api/v1/mcp \
  --header "x-api-key: YOUR_KEY"

There is no restart or config-file edit. Claude Code connects automatically. Run claude mcp list to confirm customermates shows up.

Scope: the command defaults to local scope. Add --scope user to make Customermates available everywhere on your machine, or --scope project to write it to a repo's .mcp.json so teammates pick it up.

Codex

Codex connects directly to Customermates over Streamable HTTP. codex mcp add customermates --url <BASE_URL>/api/v1/mcp adds the server URL, but the CLI command has no option for a custom x-api-key header. For API-key access, open ~/.codex/config.toml (create it if missing) and add the complete block below, replacing YOUR_KEY:

[mcp_servers.customermates]
enabled = true
url = "https://customermates.com/api/v1/mcp"
http_headers = { "x-api-key" = "YOUR_KEY" }

To pull the key from your environment instead of storing it in the file, replace the http_headers line of the block above with:

env_http_headers = { "x-api-key" = "CUSTOMERMATES_API_KEY" }

Then export CUSTOMERMATES_API_KEY in your shell profile. New sessions pick the server up, so end the current one and start fresh.

The same HTTP endpoint also accepts OAuth. If you prefer to sign in, add the URL with codex mcp add customermates --url <BASE_URL>/api/v1/mcp, then run codex mcp login customermates. The stdio bridge described below is for Claude Desktop clients that need one.

Cursor

For the Cursor setup, open Settings → Tools & MCP → Add new MCP server and paste this, replacing YOUR_KEY:

{
  "customermates": {
    "url": "https://customermates.com/api/v1/mcp",
    "headers": {
      "x-api-key": "YOUR_KEY"
    }
  }
}

Cursor hot-reloads, so no restart is needed. The tools appear in Composer right away. To edit the file directly, the same block goes in ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project), wrapped under mcpServers.

Gemini CLI

The Gemini CLI loads MCP servers from ~/.gemini/settings.json. Merge this in, replacing YOUR_KEY:

{
  "mcpServers": {
    "customermates": {
      "httpUrl": "https://customermates.com/api/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_KEY"
      }
    }
  }
}

If mcpServers already has entries, add customermates alongside the existing ones rather than overwriting the object.

Claude Desktop (config file)

The recommended path for Claude Desktop is the connector path: OAuth, no key, synced across your devices. On a free plan, or if you prefer a static key, the config file below works too.

Open Claude → Settings → Developer → Edit Config, or the file directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge this in, replacing YOUR_KEY:

{
  "mcpServers": {
    "customermates": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://customermates.com/api/v1/mcp",
        "--header",
        "x-api-key:YOUR_KEY"
      ]
    }
  }
}

mcp-remote is a shim that lets Claude Desktop talk to a remote HTTP MCP server over stdio. It downloads on first run via npx, so you need Node 18+ on PATH.

Then restart: fully quit (⌘Q on macOS, not just close the window) and reopen. Customermates appears in the tools panel with the CRM tools listed.

Try your first prompt

The server provides connection instructions describing its tool surface, safety rules, and how to retrieve relevant Knowledge Base pages. Clients decide whether to pass those instructions to their agent. If yours does not, add the Knowledge Base retrieval rule to that client's persistent instructions. In clients that support MCP prompts (like Claude Code), you can run the built-in get-started prompt for a guided kickoff: it reads your workspace and relevant Knowledge Base pages first, then asks only for missing information.

• "Set the Acme deal's Status field to 'Won' and add a note that the contract was signed today."
• "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."

Contacts, organizations, deals, services, and tasks are the starting record types; your workspace can add more. Attributes such as a deal's stage or a task's priority depend on the workspace configuration. Call discover_record_types and then get_record_model for the relevant type IDs before writing.

Troubleshooting

Next

• Custom connector: the OAuth path for Claude and ChatGPT apps.
• MCP tool catalog: every tool the agent can call.
• Webhooks: subscribe other systems to CRM changes.