# API vs MCP

> Two ways to integrate - when to use which, and how to combine them.

<!-- Source: https://docs.actuallycare.com/concepts/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?

| If you're building... | Reach for |
|---|---|
| A custom UI, dashboard, or internal tool | REST API |
| A data sync with another system (MLS feed, accounting, email marketing) | REST API |
| An event-driven integration that reacts to changes | REST API plus [webhooks](/concepts/webhooks) |
| An AI assistant that can actually work your CRM | MCP |
| A daily "ask Claude about my pipeline" workflow | MCP |
| All of the above | Both — this is common |

## At a glance

| Aspect | REST API | MCP |
|---|---|---|
| Interface | HTTP requests you write | Natural language via Claude |
| Best for | Apps, scripts, syncs | Conversational work and AI analysis |
| Authentication | API key (`X-API-Key`) or JWT | OAuth 2.1, handled by Claude |
| Response format | JSON envelope | Claude reads tool results and answers in plain English |
| Surface | Small and focused | Much larger |

Both authentication models are covered in depth in [the authentication model](/concepts/authentication).

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

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

Every response uses the same envelope:

```json
{
  "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](/api/pagination) and [errors](/api/errors) for the details, and the [endpoint reference](/api/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](/guides/bulk-import))
- **Syncing with other systems** — push leads in from your website, push closings out to accounting
- **Reacting to events** — pair the API with [webhooks](/concepts/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](/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`](/tools/escrows/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](/api/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](/tools), 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](/mcp/custom-apps).

## 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](/api/rate-limits).