Introducing MCP: Let AI Manage Your PerfexCRM

"Create an invoice for Acme Corp, 5 hours of dev work"

Picture the scene. You are in Claude Desktop, mid-conversation about something else entirely — debugging a webhook, sketching a quote, reading an email from a client. You type one line:

> "Create an invoice for Acme Corp — 5 hours of dev work at my standard rate, due in 14 days, and email it to them."

A second later, Claude replies with the invoice number, the PDF link, and a note that the email was sent. No browser tab. No manual lookup of Acme's customer ID. No copy-pasting the hourly rate from a note somewhere. The CRM just… did the thing.

That is MCP. And as of v2.8.0, the PerfexAPI module ships with a Model Context Protocol server built in — so every operation that exists in the REST API (all 170 of them) is instantly available to any AI client that speaks MCP. This post covers what the protocol is, why it matters for self-hosted CRM owners, and how to get it running against your PerfexCRM in about five minutes.

What is MCP?

Model Context Protocol is an open specification created by Anthropic in late 2024 and now implemented by OpenAI, Google, and a growing list of developer tool vendors. The full spec is at modelcontextprotocol.io — it is short, readable, and worth bookmarking if you are doing any kind of LLM integration work.

The simplest way to describe MCP is this: it is a standardized way for AI clients (Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code Copilot, n8n AI Agent, and dozens of others) to discover and invoke tools exposed by external systems. Before MCP, every vendor solved this differently. OpenAI had function calling. Anthropic had tool use. Each IDE plugin shipped its own integration layer. If you wanted your software to be reachable from an AI agent, you had to build one adapter per client.

MCP collapses that into a single, language-agnostic contract:

1. The AI client connects to your MCP server (HTTP, stdio, or Server-Sent Events).

2. The server advertises a list of tools — each one a named operation with a JSON Schema describing its arguments.

3. When the user asks the AI to do something, the model picks the right tool, fills in the arguments, and the server executes it.

4. The response comes back as structured data the model can reason about.

If you have used the OpenAPI spec, think of MCP as "OpenAPI for AI agents" — but with tool discovery, session state, and authentication baked in. The PerfexAPI MCP server exposes every endpoint from the REST API as an MCP tool, wired to the same authentication layer and the same permission model you already know.

Why PerfexCRM + MCP?

PerfexCRM is a workhorse. Freelancers, agencies, MSPs, and small consulting firms run their whole back office on it — customers, quotes, invoices, projects, tickets, contracts, leads. The data is rich. The problem has always been the interface: a multi-level admin panel, designed for deliberate browser work, not for the "I need this number in ten seconds" flow that happens twenty times a day.

That is the gap MCP fills. Some concrete use cases the first batch of v2.8.0 users have actually built:

The end-of-day billing run. A freelance developer who used to spend 30 minutes on Friday evenings creating invoices for the week's work now asks Claude: "Summarize this week's timesheet entries and draft invoices for each client. Don't send yet — let me review." The model reads the timesheets via MCP, groups them by customer, drafts the invoices, and shows a summary. One look, one confirm, done.

The support triage sweep. A small agency owner starts each morning with: "List open tickets older than 24 hours, grouped by customer, with last activity timestamp. Flag anything from a customer with an overdue invoice." The AI pulls both data sets via MCP and composes a prioritized list. That is two API calls and a join — trivial in code, but tedious to build as a dashboard.

The "wait, who was that?" lookup. Mid-meeting, someone mentions a prospect. You type: "Find the lead for ContosoHealth and summarize the last three notes on the account." Back in seven seconds, inside the same tool you already had open. No context switch.

The contract renewal nudge. Cursor is open, you are writing code. You ask: "Which contracts expire in the next 30 days, and have we invoiced those clients this quarter?" The model pulls /contracts and /invoices, cross-references them, and gives you a list. You draft outreach emails without leaving the editor.

These are not dramatic workflows — they are the boring, daily work of running a services business, with the friction removed. That is what MCP is for: reducing the distance between an intent and a CRM operation from "open a tab, log in, navigate three menus, click four times" to "type a sentence."

How it works

The request flow is straightforward. When you type a prompt into Claude Desktop, the following happens:

1. Claude Desktop sends the prompt to Anthropic's servers with a list of available MCP tools from your configured servers.

2. The model decides which tool to call (if any), constructs the arguments, and returns a tool_use block.

3. Claude Desktop receives the tool call and forwards it to your PerfexCRM MCP server over HTTPS, with your API key in the header.

4. The PerfexAPI module authenticates the key, checks permissions, and executes the corresponding REST endpoint against your CRM database.

5. The response flows back up: MCP server → Claude Desktop → Anthropic → model → final user-facing message.

The full round-trip usually takes 2–4 seconds end to end — most of that is the LLM, not the CRM. We intend to publish a mermaid diagram of this flow in the public /mcp docs; if you are reading this before that lands, picture five boxes in a line and you have the idea.

Here is what the Claude Desktop configuration looks like. The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "perfexcrm": {
      "url": "https://your-crm.com/api/v1/mcp",
      "headers": {
        "X-API-KEY": "pk_your_api_key_here"
      }
    }
  }
}

That is the entire integration. One server block, a URL, an API key. Restart Claude Desktop and the 170 tools show up in the tool picker automatically — no further configuration, no schema definitions on your side, no webhooks to register.

An example round-trip, end to end. User prompt:

> "Create a lead: TechStart Inc, contact Sarah sarah@techstart.com, estimated value $25,000, source Website."

Claude picks the leads.create tool and calls it with structured arguments. The MCP server translates that into POST /api/v1/leads with the JSON body:

{
  "name": "TechStart Inc",
  "email": "sarah@techstart.com",
  "lead_value": 25000,
  "source": "Website"
}

PerfexCRM returns the created lead record. The MCP server passes it back. Claude formats it:

> "Created lead #247 — TechStart Inc, contact sarah@techstart.com, value $25,000. Want me to assign it to a sales rep or set a follow-up task?"

That follow-up question is the AI noticing the shape of the data and offering the obvious next step. You do not have to ask for it; the model just does it because it has the full tool catalog in context.

5 things you can do on day 1

These work the moment you finish the setup below. No fine-tuning, no custom skills, no prompt engineering tricks — the tool catalog is self-describing, so the model just figures it out.

1. Invoice creation from natural language. "Invoice Acme Corp for 12 hours of consulting at my standard rate, include the Q2 retainer line item, due net-15." The model pulls Acme's customer ID, your saved rate, and the retainer item code from recent context or by asking.

2. Overdue sweep with suggested actions. "Which invoices are more than 14 days overdue, sorted by amount, and draft a polite reminder email for each one." Uses /invoices with filter params, then generates email drafts — no sending unless you approve.

3. Lead pipeline digest. "Summarize this week's new leads: source breakdown, total pipeline value, top 3 by estimated value, and flag any that have not been contacted yet." Combines /leads with activity filtering.

4. Ticket triage across customers. "Show me all open tickets from customers whose contracts are expiring in the next 60 days." This is a join the admin panel cannot do in one screen; the AI does it by calling two endpoints and correlating.

5. Project status rollup. "For each active project, give me: completion percentage, open tasks, last milestone hit, total billed so far." Pulls /projects and its sub-resources (tasks, milestones, invoices) and formats a single table.

The pattern across all five: read-heavy workflows that used to require a custom report, reduced to one sentence. Write operations (create, update, delete) work the same way, but we recommend you review suggested changes before approving them until you are comfortable with how the model interprets your prompts.

Setup in under 5 minutes

Prerequisites. PerfexCRM 2.3.0 or later, the PerfexAPI module v2.8.0 or later, and one API key created in Admin → Setup → API & Webhooks → API Keys. For Claude Desktop specifically, download it from claude.ai/download — it is available on macOS and Windows.

Step 1 — Enable the MCP server. Go to Setup → API & Webhooks → Settings → Advanced in your PerfexCRM admin and toggle MCP Server to enabled. MCP is off by default; you have to opt in. See the /mcp page for the full admin walkthrough.

Step 2 — Add the config block. Open your Claude Desktop config file (path above), paste the mcpServers block, replace the URL and key with yours, save.

Step 3 — Restart and test. Quit Claude Desktop fully (not just close the window — on macOS that means Claude → Quit, on Windows that means right-click the tray icon → Exit). Reopen it, start a new conversation, and type: "What can you do with my PerfexCRM?" The model will list the tool categories it discovered — customers, invoices, leads, tickets, projects, contracts, and the rest — and you are live.

If you hit issues, the /mcp page has a troubleshooting section, and the /integrations hub covers the other ways to connect AI to your CRM — Hermes Agent for scheduled jobs, OpenClaw for WhatsApp and Telegram, and n8n for visual workflow automation. For webhook-driven event flows (invoice paid, ticket created, lead converted), see the /webhooks page — 100+ events covering the full CRM event model.

Included in every PerfexAPI license

MCP is not a separate add-on. Every PerfexAPI license from the $49 launch tier upward includes the full MCP server, all 170 tools, and the security features (per-key permissions, rate limiting, audit logging) we built for the REST API. No per-seat fees, no per-call charges, no vendor lock-in — the protocol is open, your data stays on your server, and you can swap AI clients any time without reconfiguring the CRM side.

We have spent 18 months building this module, shipped it to 7 paying customers so far, and written 526+ end-to-end tests to keep it honest. MCP is the feature we are most excited about because it closes the loop: the API was the foundation, the n8n node made it automatable, and MCP makes it conversational.

Get your license → · See the MCP page → · Browse all integrations →

*Last updated: April 2026*