API vs MCP

ActuallyCare gives you two ways to integrate: a REST API and an MCP (Model Context Protocol) server. They sit in front of the same database — the difference is who's doing the talking. The REST API is for code you write. MCP is for an AI assistant like Claude.

Which one do you need?#

At a glance#

Both authentication models are covered in depth in the authentication model.

When to use the REST API#

Choose REST when a program — not a person — is the consumer. You control the exact request, you parse the exact response, and you can schedule, retry, and log however you like.

curl "https://api.actuallycare.com/v1/clients?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Every response uses the same envelope:

{
  "success": true,
  "data": {
    "clients": [],
    "meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0, "hasMore": false }
  },
  "timestamp": "2026-06-11T17:32:08.123Z"
}

Here data is an object keyed by the resource — the page of clients lives at data.clients, with pagination metadata at data.meta. See pagination and errors for the details, and the endpoint reference for every documented operation.

Good REST use cases:

• Custom applications — internal dashboards, reporting tools, mobile front ends
• Automation — scheduled scripts, Zapier-style workflows, bulk imports (see the bulk import guide)
• Syncing with other systems — push leads in from your website, push closings out to accounting
• Reacting to events — pair the API with webhooks instead of polling

When to use MCP#

Choose MCP when you want to talk to your CRM instead of program against it. Once your CRM is connected to Claude (see the MCP quickstart), you ask in plain English:

"Show me all escrows closing this month with their current status."

Claude picks the right tool — in this case escrows_list with date filters — runs it against your data, and presents the results conversationally. Tool names follow an entity_verb convention: escrows_list, clients_create, leads_convert, appointments_today.

Good MCP use cases:

• Quick lookups — "What's the status of 123 Main St?"
• Natural updates — "Mark John Smith as contacted"
• Analysis — "Which of my deals look at risk of falling through?"
• Multi-step questions — "Find clients who bought in 2024 and haven't heard from me in 90 days"

To keep conversations fast, Claude sees the most-used tools up front and finds the rest when it needs them — you don't have to do anything to enable a tool.

Two surfaces, one database#

The two surfaces are deliberately different sizes.

The documented REST surface is focused: ten resource groups covering the core CRM entities (contacts, clients, leads, escrows, listings, appointments) plus auth, API keys, webhooks, and billing. The full list lives in the endpoint reference.

The MCP surface is much larger. It covers escrows, showings, open houses, financial calculators, the vendor pipeline, property management, reporting, and more — browse the full catalog at the tool reference, where the live tool counts are rendered from the same registry the server uses.

That means some things you can ask Claude to do don't have a documented REST equivalent yet. If you need an operation that only exists as an MCP tool, MCP is the answer — including from your own code, via a custom MCP client.

Using both together#

Many teams run both, and that's the recommended setup for power users:

• MCP for daily work — quick queries, updates, and analysis while chatting with Claude
• REST for automation — webhook handlers, scheduled jobs, and integrations that run without a human in the loop

A typical pattern: a webhook fires when a lead is created, your server enriches it via the REST API, and the agent reviews and works the lead through Claude the next morning.

Data consistency#

Both interfaces read and write the same underlying records. A client Claude creates is immediately visible to your REST integration, and vice versa. There's no sync delay and no separate data store to reconcile.

Rate limits#

The two surfaces are limited independently:

• REST API — 500 requests per 15 minutes per IP across /v1 (auth endpoints are tighter: 30 failed attempts per 15 minutes, plus a 50-total-attempts cap on POST /v1/auth/login — that second cap is what the RateLimit-Limit header on login responses reports — with /v1/auth/refresh on its own 30-per-minute limit)
• MCP — 120 requests per minute and 30 tool calls per minute per user

When you hit a limit you'll get a 429 — back off and retry. Full details, including the response headers to watch, are on the rate limits page.