# ActuallyCare Docs — MCP & agent setup # For real estate agents > Connect Claude to your ActuallyCare CRM and talk to it like a colleague — no code, no terminal, no IT department. You can connect Claude — the AI assistant at claude.ai — directly to your ActuallyCare CRM. No code. No downloads beyond what you already use. If you can paste a link, you can do this. ## What "connecting Claude to your CRM" actually means Once connected, you stop clicking through screens and start asking questions, the way you'd ask a sharp colleague who has read every file in your office: > "What's closing this month?" > "Who haven't I talked to lately?" > "Draft a check-in email to the Hendersons." Claude looks things up in *your* ActuallyCare account and answers with your real data — your escrows, your clients, your leads, your calendar. It can also do work for you, like adding a new lead or updating an escrow. Emails and texts it writes are drafts — Claude can't send anything — and you can see exactly what it's allowed to do on the [permissions and safety](/agents/permissions-and-safety) page. ## What you need - **An ActuallyCare account.** The one you already log into at app.actuallycare.com. - **A Claude account** at [claude.ai](https://claude.ai). Any Claude plan works, including the free one, which allows one custom connector. On a Team or Enterprise plan, an owner adds ActuallyCare for your organization first. That's the whole list. ## What it costs For what's included with your ActuallyCare plan, see the [pricing page on our main site](https://www.actuallycare.com/pricing). Your Claude account is separate and billed by Anthropic, the company that makes Claude. Claude's free plan works too; it allows one custom connector. There's no per-question charge from ActuallyCare — ask as much as you like. Questions count toward your Claude plan's normal usage limits, like any other Claude conversation. ## Start here Setup takes about five minutes: paste one link into Claude, log into ActuallyCare, and approve the connection. **[Follow the quickstart →](/mcp/quickstart)** ## Then keep going - [What can I ask?](/agents/what-can-i-ask) — real examples, organized by the moments of your day - [Permissions and safety](/agents/permissions-and-safety) — exactly what Claude can and can't do - [Troubleshooting](/agents/troubleshooting) — quick fixes when something looks off - [Glossary](/agents/glossary) — plain-English definitions for any term you bump into --- # Glossary > Plain-English definitions of the technical terms you'll meet in these docs, with real-estate analogies. Every technical word you'll bump into across these docs, defined in plain English. You don't need to memorize any of this — it's here for the moment a term makes you pause. ## Connecting Claude ### MCP Short for Model Context Protocol — a shared standard that lets AI assistants like Claude plug into other software, the way a universal lockbox standard lets any agent open any listing. You never have to touch MCP directly; it's the plumbing behind the connection. ### Connector The link you add in Claude's settings that joins Claude to ActuallyCare. Think of it as saving a trusted contact in your phone: once it's added, Claude knows how to reach your CRM. ### URL A web address, like www.actuallycare.com. When a form asks for a URL, paste the full address exactly — every letter, dot, and slash matters. ### OAuth The secure handshake used when you connect: you log into ActuallyCare yourself and approve access, so Claude never sees or stores your password. It's like giving a showing service a lockbox code you can change anytime, instead of handing over your personal house key. ### Consent screen The approval page — titled "Connect with ActuallyCare" — that appears when you connect. It lists exactly what Claude will be allowed to do, and nothing is shared until you say yes. Details on the [permissions and safety](/agents/permissions-and-safety) page. ### Token A temporary digital pass Claude uses to prove it's allowed into your account. Like a day pass at a gated community, it expires (after 24 hours) and renews itself automatically, so you're not asked to re-approve. ## Working with your data ### CRM Customer relationship management software — the system that holds your clients, leads, escrows, listings, and appointments. ActuallyCare is your CRM. ### Tool One specific action Claude can take in your CRM, like "look up a client" or "list my escrows." There are tools covering every part of the CRM — the full list is in the [tools reference](/tools). ### Prompt (built-in) A ready-made conversation starter you can pick from a menu in Claude (behind the **+** button by the message box) instead of typing from scratch — like a daily summary or a closing checklist. Browse them all at [prompts](/prompts). ### Draft Words Claude writes for you — an email, a text, a call script — that go nowhere until you approve them. Claude holds the pen; you hold the send button. ### Archive vs delete Archiving tucks a record out of sight but keeps it, like moving a closed file to the storage room — you can restore it later. Deleting actually removes it. Both happen in the ActuallyCare app — Claude can't archive or delete records. ## Developer words you might bump into ### API A doorway that lets one piece of software talk to another. Developers use ActuallyCare's API to build custom integrations — as an agent using Claude, you'll never need it. ### API key A long secret code that lets a program through that doorway — an API key is like a gate code for software. Your Claude connection doesn't use one; you log in with your normal account instead. ### Webhook A way for ActuallyCare to notify other software the instant something happens — like an automatic text alert when a showing is requested, except the "text" goes to another program. ### Machine-readable Formatted for software to read rather than people — tidy and structured instead of pretty. Some pages on this site have machine-readable versions so other programs (and AIs) can use them. ### Raw Markdown The plain-text version of a page, with simple symbols standing in for formatting (like `**asterisks**` for bold). It's handy when you want to copy a whole docs page into a chat with Claude without the styling getting in the way. --- # Permissions and safety > Exactly what Claude can and can't do in your ActuallyCare CRM, what you approved on the consent screen, and how to disconnect at any time. Handing an AI the keys to your client database is a fair thing to be nervous about. This page spells out, in plain English, what Claude is allowed to do, what it can never do, and how to shut the connection off in seconds. ## The consent screen — what you actually approved When you connect Claude to ActuallyCare, a page titled **"Connect with ActuallyCare"** appears before anything is shared. It names the app asking for access (Claude), and warns you if ActuallyCare doesn't recognize that app. (If you weren't logged into ActuallyCare, you log in first, the normal way.) It states the access in four bullets: 1. **Read your CRM data — escrows, listings, clients, leads, and calendar** 2. **Create and update records when you ask** 3. **Draft emails and texts for your approval — nothing sends without your okay** 4. **Archive or delete records, with confirmation** That's the real grant, stated plainly: approving connects Claude to your CRM **as you** — it can read your records and create or update the ones you ask for, like opening an escrow or rescheduling an appointment. The bullets are one half of the safety story; the other half is how the tools themselves are built: - **Claude can't send anything.** Emails, texts, and call scripts come back as drafts for you to copy and send yourself. - **Claude can't delete or archive.** Those buttons stay in the ActuallyCare app. Claude can change a status — mark a lead lost, cancel an appointment — and you can change it back. - **One change can't be undone.** Claude can turn a lead into a client. That tool is marked as irreversible, which tells Claude to check with you before using it. If you'd rather Claude never converted leads, set that tool to **Blocked** on Claude's connector page and do it in the app instead (see [choosing which tools need your OK](/mcp/claude-web#choose-which-tools-need-your-ok)). The consent screen describes everything the connection allows. Claude itself uses a smaller set of everyday tools, so in practice it does less than the screen lists. Nothing is shared until you click **Continue** on this screen, and you can take the access back at any time (see [how to disconnect](#how-to-disconnect) below). ## What Claude can do — and what it can't | Claude CAN | Claude CANNOT | |---|---| | Read your escrows, listings, clients, leads, contacts, and today's calendar | Send anything — everything starts as a **draft** | | Create and update records you ask for — leads, clients, escrows, contacts, listings, appointments | Delete or archive records | | Draft emails, texts, and call scripts for you to review | Touch your billing, subscription, or payment details | | Run quick numbers — dashboard stats, commission splits, net sheets, and closing costs | See other agents' private data — it works inside your account, with your permissions | Some features aren't available in Claude yet, including production reports, open-house lists, leases, and goals. Use the app for those. The pattern to remember: **Claude looks things up and writes things down, but the send button and the delete button stay with you.** ## Your data stays in your CRM Connecting Claude doesn't copy your database anywhere. Your clients, escrows, and leads stay right where they've always been — in your ActuallyCare account. When you ask a question, Claude reads the answer through a secured connection, the same kind of protected channel your bank's app uses, and only the pieces relevant to your question pass through. ## How to disconnect The off switch lives in Claude's own settings. 1. Open [claude.ai](https://claude.ai), click **Customize** in the left sidebar, then **Connectors**. **What you should see:** the Connectors page. Click **Yours** to see ActuallyCare among your connectors. 2. Remove the ActuallyCare connector (it may be behind the three-dot menu next to it). **What you should see:** ActuallyCare disappears from the list. That's it — once it's removed, Claude stops using the connection. There's no separate page inside ActuallyCare you need to visit; removing the connector in Claude is the whole job. Changing your ActuallyCare password does **not** disconnect Claude, so remove the connector if you want it gone. Your CRM data is untouched, and you can reconnect any time by running the [quickstart](/mcp/quickstart) again. ## You won't be nagged to re-approve The connection keeps itself fresh, securely. Behind the scenes, Claude uses a temporary digital pass that expires every 24 hours and renews itself automatically. You approve the consent screen once, and the connection just keeps working — no weekly "please log in again" interruptions. The one exception: if you don't use ActuallyCare in Claude for 30 days, the connection lapses and you'll be asked to reconnect. The [troubleshooting page](/agents/troubleshooting) covers it. --- # Troubleshooting > Plain-English fixes for the most common Claude-to-ActuallyCare connection problems, with what you should see when each fix works. Most connection problems have a two-minute fix. Find the line below that sounds like what you're seeing, follow the steps, and check the "What you should see" line under each step to confirm it worked before moving on. If none of these match, [contact support](https://www.actuallycare.com/contact) and include what you asked Claude and what it said back. ## It says Reconnect When the connection lapses, Claude shows it in two places: on the Connectors page, ActuallyCare has a ⚠ warning sign and a **Reconnect** button; in a chat, under **+** → **Connectors**, ActuallyCare has a ⚠ and no on/off switch. Claude can't reach your CRM until you reconnect. 1. In Claude, click **Customize** in the left sidebar, then **Connectors**, then the **Yours** tab. **What you should see:** ActuallyCare with a ⚠ warning sign and a **Reconnect** button. ![ActuallyCare in Claude's connectors list with a warning sign and a Reconnect button](/screens/claude-connector-reconnect.webp "A lapsed connection: click Reconnect") 2. Click **Reconnect**. Sign in to ActuallyCare in the window that opens, then click **Continue** on the screen titled "Connect with ActuallyCare". **What you should see:** the window closes, the ⚠ and the **Reconnect** button are gone, and in a chat ActuallyCare has its switch back. If **Reconnect** doesn't fix it, remove the connector and add it again: see [It says I'm unauthorized or my session expired](#it-says-im-unauthorized-or-my-session-expired). ## It says I'm unauthorized or my session expired Normally the connection renews itself in the background. It does lapse if you haven't used ActuallyCare in Claude for 30 days, and occasionally it just loses its footing. Either way, a fresh connection fixes it. 1. Go to [app.actuallycare.com](https://app.actuallycare.com) in your browser and log in. **What you should see:** your normal ActuallyCare dashboard. If you can't log in here, fix that first — reset your password or [contact support](https://www.actuallycare.com/contact) — because the connection can't work without a healthy account. 2. In Claude, click **Customize** in the left sidebar, then **Connectors**, then the **Yours** tab. If ActuallyCare shows a **Reconnect** button, click it, sign in to ActuallyCare, and click **Continue** on the screen titled "Connect with ActuallyCare". **What you should see:** the **Reconnect** button is gone and ActuallyCare shows as connected. If so, skip to step 5. 3. If there was no **Reconnect** button, or reconnecting didn't help, remove the ActuallyCare connector (it may be behind the three-dot menu next to it). **What you should see:** ActuallyCare disappears from your connector list. 4. Add it back: click **+ Add**, then **Add custom connector**, name it ActuallyCare, paste `https://mcp.actuallycare.com/mcp`, and click **Continue**. Leave the settings Claude shows as they are, click **Continue**, then **Add**. Log in to ActuallyCare in the window that opens, then click **Continue** on the screen titled "Connect with ActuallyCare". **What you should see:** the window closes and ActuallyCare is back in your connector list. 5. Start a new chat and ask: "Using ActuallyCare, give me my daily summary." **What you should see:** Claude checks ActuallyCare and answers with your real appointments, deals, and leads — no more "unauthorized" message. ## Claude can't see my escrows This is almost always one of three things: the connector is switched off for that chat, Claude wasn't told to use it, or you're connected under a different ActuallyCare account than you think. 1. In the chat, click the **+** button by the message box, then **Connectors**, and make sure ActuallyCare is switched **on** for this conversation. **What you should see:** ActuallyCare in the Connectors list with its switch turned on. 2. Ask again, explicitly: "Using ActuallyCare, list my escrows." **What you should see:** Claude lists your actual escrows by address — the same ones you see in the app. 3. If it still comes back empty, log into [app.actuallycare.com](https://app.actuallycare.com) and check that the escrows are visible there. **What you should see:** your escrows in the app. If they aren't there either, they may be archived or under a different account — that's the real problem, not the connection. 4. If you suspect you approved the connection while logged into the wrong account, [disconnect and reconnect](#how-do-i-disconnect-or-reconnect) and log in with the right one this time. **What you should see:** after reconnecting, Claude's answers match what you see in the app. ## I can't find the Connectors option in Claude Claude has moved connectors: they're under **Customize** now, not **Settings**. 1. Go to [claude.ai](https://claude.ai) in a web browser (not just the phone app) and log in. **What you should see:** your normal Claude chat screen, with a sidebar on the left. 2. In the left sidebar, click **Customize**. **What you should see:** Claude's Customize page, open on its **Skills** tab, with **Connectors** and **Plugins** as tabs beside it. If a pop-up covers it the first time, close it. 3. Click **Connectors**. **What you should see:** the Connectors page. It opens on the **Discover** tab; click **Yours** to see the connectors you've added. **+ Add** → **Add custom connector** is where ActuallyCare goes. If there's no **+ Add** button or no **Add custom connector** option: - **On a Claude Team or Enterprise plan,** only an owner can add a custom connector. Ask your owner to add it under **Organization settings → Connectors** (**Add** → **Custom** → **Web**, with the address `https://mcp.actuallycare.com/mcp`). Then find ActuallyCare on your **Customize → Connectors** page and click **Connect** to sign in with your own ActuallyCare account. - **On Claude's free plan,** you can have one custom connector. If you already use a different one, remove it or upgrade your Claude plan. These are Claude settings, not something ActuallyCare can switch on for you. Once you can add a custom connector, come back to the [quickstart](/mcp/quickstart). ## The ActuallyCare sign-in window never opened You pasted the connector address, confirmed, and… nothing. Nine times out of ten, a pop-up blocker quietly stopped the sign-in window from opening. 1. Look for a blocked pop-up message. Most browsers show a small icon or note near the address bar when they block a window — if you see one, choose to allow pop-ups for claude.ai. **What you should see:** the ActuallyCare sign-in window opens as soon as the pop-up is allowed. 2. On an iPhone or iPad using Safari, open the **Settings** app, scroll down to **Safari**, and turn off **Block Pop-ups**. (You can turn it back on after setup.) **What you should see:** the Block Pop-ups switch turned off — gray instead of green. 3. Go back to Claude and try the add-connector step again. **What you should see:** a new window opens asking you to sign in to ActuallyCare. 4. If it still won't open, double-check the address you pasted. It must be exactly `https://mcp.actuallycare.com/mcp` — no spaces before or after, nothing missing from the end. **What you should see:** after re-pasting the exact address and confirming, the ActuallyCare sign-in window opens. ## Claude says it doesn't have a tool for that It may be right. Claude has ActuallyCare's everyday tools: escrows, clients, leads, contacts, listings, today's calendar, drafts, checklists, deadlines, and calculators. Some features aren't available in Claude yet — like production reports, lead-source reports, open-house lists, leases, and goals. Use the ActuallyCare app for those. If what you asked for is an everyday task, try this: 1. Say it with the magic words: "Using ActuallyCare, …". **What you should see:** Claude checks ActuallyCare before it answers. 2. Rephrase your ask in plain words, describing the *outcome* you want — "show me my clients who are buyers" rather than naming a feature. **What you should see:** Claude comes back with your data instead of an apology. ## It connected but answers seem generic If Claude answers your CRM questions with general real-estate advice instead of your actual numbers, it's answering from memory instead of checking your CRM. 1. Start your request with "Using ActuallyCare, …" — for example, "Using ActuallyCare, how many active escrows do I have?" **What you should see:** Claude visibly checks ActuallyCare before it answers. 2. Ask something only your CRM could answer, like a specific client's phone number, and see if the answer matches the app. **What you should see:** your real names, addresses, and numbers — not ranges, guesses, or "typically, agents…". 3. In the chat, click **+**, then **Connectors**, and make sure ActuallyCare is switched on for this conversation. **What you should see:** ActuallyCare in the Connectors list with its switch turned on. ## How do I disconnect or reconnect? **To disconnect:** 1. In Claude, click **Customize** in the left sidebar, then **Connectors**. **What you should see:** the Connectors page. Click **Yours** to see ActuallyCare among your connectors. 2. Remove the ActuallyCare connector (it may be behind the three-dot menu next to it). **What you should see:** ActuallyCare disappears from the connector list. Claude stops using the connection, and your CRM data is untouched. There's nothing to undo on the ActuallyCare side. **To reconnect:** 1. In **Customize → Connectors**, click **+ Add**, then **Add custom connector**. **What you should see:** a form asking for a name and the connector's web address. 2. Type ActuallyCare in the **Name** box, paste `https://mcp.actuallycare.com/mcp` into the **MCP server URL** box, and click **Continue**. Leave the settings Claude shows as they are, then click **Continue** and **Add**. **What you should see:** a window opens asking you to log into ActuallyCare. 3. Log into ActuallyCare in the window that opens, then click **Continue** on the screen titled "Connect with ActuallyCare". **What you should see:** the window closes and ActuallyCare is back in your connector list. The full walkthrough is in the [quickstart](/mcp/quickstart). ## It says ActuallyCare does not recognize this application The connect screen shows this yellow notice when the app asking for access isn't one ActuallyCare already knows. 1. If you connected from Claude on the web, Desktop, or your phone, you should **not** see it. Click **Cancel**, then start again from Claude's **Customize → Connectors**. 2. If you connected from Claude Code, the notice can appear because Claude Code signs in through your own computer. If you started it yourself, click **Continue**. 3. If you didn't start a connection just now, click **Cancel**. Something else is asking for your data. **What you should see:** After **Continue**, the window closes and ActuallyCare shows as connected in the app you started from. ## Still stuck? [Contact support](https://www.actuallycare.com/contact) and include three things: what you asked Claude, what Claude said back, and a screenshot if you can grab one. That's usually everything we need to spot the problem on the first reply. --- # What can I ask? > Real examples of what to ask Claude once it's connected to your ActuallyCare CRM, organized by the moments of an agent's day. Once Claude is connected to ActuallyCare, you talk to it in plain English — no special commands, no exact wording to memorize. Below are examples organized by the moments of a working day. Say them your way; Claude figures out the rest. Two more places to look: the [built-in prompt menu](/prompts) gives you ready-made starters like a daily summary and a closing checklist, and the [tools reference](/tools) lists everything ActuallyCare can do, if you want the full picture. Claude uses a set of everyday tools from that list. ## Start your morning Get oriented before your first coffee is gone. > "Give me my daily summary." > "What's on my calendar today?" > "Any deadlines coming up this week I should worry about?" > "Anything urgent I should handle before my 10 a.m.?" ## Stay on top of people Leads, follow-ups, and the clients you haven't thought about in a while. > "Who are my hot leads right now?" > "Did any new leads come in this week?" > "Which clients haven't I talked to in 60 days?" > "Who's due for a follow-up call?" > "Pull up everything we have on Maria Lopez." ## Run your transactions Escrow status, deadlines, and what's left before closing. > "What's the status on the Hendersons' escrow?" > "Which of my escrows close this month?" > "Run the closing checklist for 412 Maple Street." > "Any contingency deadlines in the next ten days?" > "When does the inspection contingency expire on the Carter deal?" ## Know your numbers Quick numbers on your pipeline and your deals. > "Give me my dashboard stats." > "What's my split on a $650,000 sale at 2.5%?" > "Run a seller net sheet for 412 Maple Street at $725,000." > "Estimate closing costs for a buyer at $500,000 with 10% down." Production reports, lead-source reports, goals, habits, and farm areas aren't available in Claude yet. You'll find them in the ActuallyCare app. ## Get words written for you Claude can draft emails, texts, and call scripts using what's already in your CRM — names, addresses, where each deal stands. **Everything it writes starts as a draft.** Nothing goes to a client until you've read it and given a clear okay. > "Draft a friendly check-in email to the Kims." > "Write a text inviting my past clients to Saturday's open house." > "Draft a review request for the Garcias now that we've closed." > "Write me a call script for following up with cold leads." ## Ask for more than one thing at once You don't have to break a task into pieces. Claude can chain steps together — look something up, think about it, then act on what it found. > "Find clients I haven't talked to in 60 days and draft check-in texts for each of them." > "Look at my hot leads, tell me who I should call first, and write me a script for that call." If Claude ever answers without using your CRM data, nudge it: start your ask with "Using ActuallyCare, …". More fixes like that live in [troubleshooting](/agents/troubleshooting). --- # For AI agents > Machine-readable docs: llms.txt, raw Markdown mirrors, tools.json, and the OpenAPI spec. This site is built to be read by machines as well as people. If you're an LLM, an agent, or a scraper — or the human configuring one — this page tells you where the machine-readable versions of everything live, and how to connect to ActuallyCare programmatically. ## Machine-readable formats | Resource | URL | What it is | |---|---|---| | Docs index | `/llms.txt` | One-page index of every docs page, per the [llmstxt.org](https://llmstxt.org) convention | | Full docs | `/llms-full.txt` | The entire docs site concatenated into a single Markdown file | | Sectioned docs | `/llms-mcp.txt`, `/llms-api.txt`, `/llms-tools.txt` | Smaller slices of the full file: connecting Claude and MCP clients, the REST API, and the tool reference | | Surface pointer | `/.well-known/ai.json` | A small JSON file pointing to every machine-readable surface on this site | | Any page as Markdown | append `.md` to the page URL, or send `Accept: text/markdown` | Raw Markdown source of that page | | MCP tool catalog | `/tools.json` | Every MCP tool: names, descriptions, JSON Schemas, safety annotations, aliases | | Sitemap | `/sitemap.xml` | Standard XML sitemap of all pages | | REST API spec | `https://docs.actuallycare.com/openapi.json` | OpenAPI spec the API reference is built from (live copy: `https://api.actuallycare.com/v1/openapi.json`) | | Docs MCP server | `https://docs.actuallycare.com/docs-mcp` | Read-only MCP server with `search_docs` and `get_page` over these docs — see [Search these docs from an MCP client](#search-these-docs-from-an-mcp-client) | | MCP discovery metadata | `https://mcp.actuallycare.com/.well-known/mcp` | Live server metadata — tool count, categories, capabilities, limits (derived from the running registry) | ### Raw Markdown for every page Every docs page (everything except the home page) is available as raw Markdown by appending `.md` to its URL. Example pair: ```text HTML: https://docs.actuallycare.com/mcp/quickstart Markdown: https://docs.actuallycare.com/mcp/quickstart.md ``` If you're feeding a single page into a model's context, fetch the `.md` version — it's smaller and has no navigation chrome. You can also request the normal URL with an `Accept: text/markdown` header and get the same Markdown back. ### llms.txt and llms-full.txt [/llms.txt](/llms.txt) follows the [llmstxt.org](https://llmstxt.org) convention: a short description of the site plus a linked index of every page with one-line summaries. Use it to decide which pages to fetch. [/llms-full.txt](/llms-full.txt) is the whole site in one file. Use it when you want all of the documentation in context at once and don't want to crawl. It's large, so if you only need one area, use a sectioned file instead: [/llms-mcp.txt](/llms-mcp.txt), [/llms-api.txt](/llms-api.txt), or [/llms-tools.txt](/llms-tools.txt). ### tools.json [/tools.json](/tools.json) is the canonical machine-readable answer to "what can this MCP server do." For every tool it includes: - the tool name (mostly entity first, like `escrows_list` and `leads_convert`; workflow tools are verb first, like `draft_email`) - a description - the full JSON Schema for its input - safety annotations (whether the tool reads, writes, or destroys data) - an `aliasOf` field recording the tool's previous published name (for example, `escrows_list` was once published as `search_escrows`). This is historical metadata only — legacy names are **not** callable; `tools/call` matches canonical names, and the old name's only afterlife is that its old docs URL redirects here The human-browsable version of the same catalog is at [/tools](/tools). ### OpenAPI spec The REST API is described by an OpenAPI spec. `https://docs.actuallycare.com/openapi.json` is the snapshot these docs are generated from, so it always matches the reference pages; the live copy is at `https://api.actuallycare.com/v1/openapi.json`. Note that the REST surface is intentionally smaller than the MCP surface — see [API vs MCP](/concepts/api-vs-mcp) for which to use when. The human-readable endpoint reference is at [/api/reference](/api/reference). ## Stable structure for parsers Pages on this site keep a predictable shape so anchors and extraction stay reliable: - Exactly one `h1` per page (the title), followed by `h2` and `h3` sections in order, never skipping levels. - Heading anchors are stable and lowercase-hyphenated (for example, `#stable-structure-for-parsers` on this page). We avoid renaming headings on published pages. - `/sitemap.xml` lists every page and is regenerated on each deploy. ## Connecting as an agent The MCP server is at: ```text https://mcp.actuallycare.com/mcp ``` Transport is Streamable HTTP (POST for JSON-RPC, GET for the SSE stream), MCP protocol version 2025-03-26. A legacy HTTP+SSE transport is available at `/sse` for older clients. Three auth options for programmatic clients: 1. **OAuth 2.1** — the standard path. Dynamic client registration is supported: `POST /register` on `mcp.actuallycare.com`, then the usual authorization-code flow with PKCE. Access tokens last 24 hours and refresh tokens rotate automatically. 2. **API key** — send an `X-API-Key` header. Simplest option for headless agents. Keys are created in the ActuallyCare app or via the REST API; see [Authentication](/api/authentication). 3. **JWT Bearer token** — the same token a normal REST login (`POST /v1/auth/login`) returns also works against the MCP server. Useful for custom apps that already sign users in; see [Authentication](/api/authentication). Full setup details, including a working TypeScript client, are on the [custom apps page](/mcp/custom-apps). ### Don't assume tools/list is exhaustive The server uses progressive disclosure: a standard `tools/list` call advertises only a set of everyday tools plus discovery meta-tools. A custom MCP client can still call any tool in the catalog by name with `tools/call`. Claude's own apps can only call advertised tools, so in a Claude chat the advertised set is the whole surface. If you need the complete catalog, consult [/tools.json](/tools.json) rather than treating the advertised list as the full surface. ## Search these docs from an MCP client These docs have their own small MCP server, separate from the CRM server above. It's read-only, needs no sign-in, and has two tools: `search_docs` (ranked pages with a snippet) and `get_page` (one page as Markdown). Add it to Claude Code with: ```bash claude mcp add --transport http actuallycare-docs https://docs.actuallycare.com/docs-mcp ``` Any MCP client that speaks Streamable HTTP can use it: POST JSON-RPC to `https://docs.actuallycare.com/docs-mcp`, and the server replies with JSON (there's no server-to-client stream). It only reads public docs; for your CRM data, connect to `https://mcp.actuallycare.com/mcp`. ## Citing these docs If you're an AI assistant answering a question from this site's content, please cite the page URL you used (for example, `https://docs.actuallycare.com/mcp/quickstart`) so the person you're helping can verify the answer and find updates. Every page here has a stable URL and a raw `.md` mirror. --- # Integration cheat sheet > Everything an agent needs to start calling ActuallyCare, in one page: base URL, auth, one working request, and the MCP connect URL. The minimum viable context for integrating with ActuallyCare. Everything here is expanded elsewhere — this page is sized for an agent's context window. ## REST API - **Base URL:** `https://api.actuallycare.com/v1` - **Auth:** send your API key in the `X-API-Key` header. Create one under **Settings → API Keys** in the web app (or `POST /v1/api-keys` with a JWT) and **pick its scopes** — `read`, `write` and `delete` are separate grants, and a request outside them gets `403`. JWT bearer auth also works: `POST /v1/auth/login` → `Authorization: Bearer `. These endpoints are JWT-only (API keys get `401`): the `/auth` session and profile endpoints, `/api-keys`, `/webhooks`, and authenticated `/billing`. - **First request:** ```bash curl -s https://api.actuallycare.com/v1/escrows \ -H "X-API-Key: $ACTUALLYCARE_API_KEY" ``` - **Envelope:** every response is `{ "success": true|false, "data": ..., "error": { "code", "message" } }`. Branch on `error.code`, never the message. - **Pagination:** `?page=1&limit=50` on most list endpoints; the response `meta` carries totals. `/v1/contacts` ignores `page` — use `offset` there. Details: [Pagination](/api/pagination). - **Spec:** [openapi.json](https://api.actuallycare.com/v1/openapi.json) · [Errors](/api/errors) · [Rate limits](/api/rate-limits) ## MCP server - **Endpoint:** `https://mcp.actuallycare.com/mcp` (Streamable HTTP) - **Auth:** OAuth 2.1 with PKCE and dynamic client registration — clients discover everything from the 401 `WWW-Authenticate` header. An ActuallyCare login is required at the consent screen. Custom clients can also send an API key in `X-API-Key` or a JWT as a bearer token. - **Tool surface:** `tools/list` advertises a set of everyday tools. Claude's apps can call only those; a custom client can call any catalog tool by name. - **Connect from Claude:** Customize → Connectors → + Add → Add custom connector → paste the endpoint URL → Continue → Add. Walkthrough: [Connect Claude in 5 minutes](/mcp/quickstart). - **Tool index:** [tools.json](https://docs.actuallycare.com/tools.json) — names, descriptions, input schemas, safety annotations for every tool. ## Webhooks Register via `POST /v1/webhooks` (JWT bearer auth, broker or system-admin role); deliveries are HMAC-signed. Setup and verification: [Set up webhooks](/guides/webhook-setup). ## Machine-readable docs [llms.txt](https://docs.actuallycare.com/llms.txt) · [llms-full.txt](https://docs.actuallycare.com/llms-full.txt) · append `.md` to any page URL · [.well-known/ai.json](https://docs.actuallycare.com/.well-known/ai.json) --- # Concepts > How ActuallyCare's integration surface fits together: API vs MCP, authentication, the data model, and webhooks. The thinking-clearly pages. Read these when you want to understand how the pieces fit together, before (or instead of) memorizing endpoints. ## [API vs MCP](/concepts/api-vs-mcp) Two ways to integrate — when to use the REST API, when to use the MCP server, and how to combine them. ## [Authentication model](/concepts/authentication) The three credential types — OAuth for Claude users, API keys for servers, JWTs for user sessions — and when each applies. ## [Data model](/concepts/data-model) The entities behind your CRM — contacts vs clients vs leads, transactions, the vendor pipeline, property management, ID formats, and how visibility follows the team/brokerage hierarchy. ## [Webhooks](/concepts/webhooks) Event-driven integration: the self-documenting event catalog, which events fire today, payload signatures, and delivery semantics. --- # API vs MCP > Two ways to integrate - when to use which, and how to combine them. 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), or an API key or JWT for custom clients | | 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 successful response has `success: true` and the result in `data`: ```json { "success": true, "data": { "clients": [], "meta": { "page": 1, "limit": 25, "total": 0, "totalPages": 0, "hasMore": false } } } ``` 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) — runs it against your data, narrows the results to this month's closing dates, and presents them conversationally. Most tool names are entity first (`escrows_list`, `clients_create`, `leads_convert`); workflow tools are verb first (`get_dashboard_stats`, `draft_email`). 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 gets a set of everyday tools — you don't have to do anything to enable them. Claude can only call those tools; the rest of the catalog is available to custom apps, which can call any tool by name. ## Two surfaces, one database The two surfaces are deliberately different sizes. The documented REST surface is focused: 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, call it from your own code via a [custom MCP client](/mcp/custom-apps). Claude's apps can only use the everyday tools, so not every catalog tool is available in a Claude chat. ## 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). --- # Authentication model > How OAuth, API keys, and JWTs fit together across the platform. ActuallyCare has one backend and three credential types. Which one you need depends entirely on who — or what — is making the call. This page explains the model; for copy-paste REST details see [API authentication](/api/authentication), and for the plain-English version written for agents see [permissions and safety](/agents/permissions-and-safety). ## Who uses what | You are... | You use... | Why | |---|---|---| | An agent connecting Claude to your CRM | OAuth 2.1 | Claude handles the whole flow — you just log in and approve once | | A developer writing a server-side integration or script | API key | One long-lived secret, no login flow, no token refresh logic | | A developer building an app where your users sign in | JWT | Short-lived tokens tied to a real user session, with refresh rotation | ## OAuth 2.1 — for Claude users When you add ActuallyCare as a connector in Claude, Claude starts an OAuth 2.1 flow with PKCE (Proof Key for Code Exchange — a standard protection against intercepted authorization codes). You never see a token. What you do see is the consent page at `app.actuallycare.com/mcp/authorize`, titled "Connect with ActuallyCare". It names the app asking for access, warns if ActuallyCare does not recognize that app, and lists exactly what you're approving: 1. Read your CRM data — escrows, listings, clients, leads, and calendar 2. Create and update records when you ask 3. Draft emails and texts for your approval — nothing sends without your okay 4. Archive or delete records, with confirmation If you're not already logged in to ActuallyCare, you go through the normal login first. After approval: - **Access tokens last 24 hours.** - **Refresh tokens rotate automatically**, so you stay connected without re-approving. To disconnect, remove the connector in Claude's own settings (Settings, then Connectors). That's the revocation path — there is no separate ActuallyCare page for revoking Claude's access. Custom MCP clients can also use OAuth 2.1 via dynamic client registration — see [building custom apps](/mcp/custom-apps). ## API keys — for servers and scripts API keys are the simplest credential for code that runs unattended. Send the key in the `X-API-Key` header (the header `API-Key` also works): ```bash curl "https://api.actuallycare.com/v1/listings" \ -H "X-API-Key: YOUR_API_KEY" ``` Key facts: - Keys are **64-character hex strings** — there's no prefix to look for. - The full key is shown **once**, at creation. It's stored hashed; afterwards the UI only shows the first 8 and last 4 characters. If you lose a key, create a new one. - A key acts as the user who created it, so requests inherit that user's role and visibility. - Scopes **grant** a key its access — they don't narrow it. Every key must be created with at least one grant. The actions are `read`, `write` and `delete`: grant `{"all":["read","write","delete"]}` for full access, or per-resource grants like `{"clients":["read","write"]}`, and adjust later with `PATCH /v1/api-keys/:id/scopes`. (Scopes are an API-key concept — JWT users aren't scope-checked.) Create keys in the app under Settings, in the API Keys tab (`app.actuallycare.com/settings?tab=api`). Every user can create their own keys — each key acts as you, with your role's visibility. You can also create keys via the API itself: `POST /v1/api-keys` with a `name`, a `scopes` object, and an optional `expiresInDays` between 1 and 365. If you omit `expiresInDays`, the key never expires — there's no implicit default, so set an expiry explicitly. Standard hygiene applies: keep keys in environment variables, never commit them to source control, never ship them in client-side code, and rotate them periodically. ## JWTs — for user-session apps If you're building an app where each user logs in with their own ActuallyCare account, use JWT auth. Log in: ```bash curl -X POST "https://api.actuallycare.com/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com", "password": "YOUR_PASSWORD"}' ``` The response follows the standard envelope: ```json { "success": true, "data": { "user": {}, "accessToken": "...", "refreshToken": "...", "expiresIn": "15m", "tokenType": "Bearer" }, "message": "Login successful" } ``` If the user has two-factor sign-in turned on, or the account is still on the waitlist, login returns `200` without these tokens. See [API authentication](/api/authentication#other-login-outcomes) for those cases. Then send the access token on every request: ```text Authorization: Bearer YOUR_ACCESS_TOKEN ``` What to know: - **Access-token lifetime is role-based**, ranging from 15 minutes to 8 hours. The `expiresIn` field is a **duration string** like `"15m"` or `"8h"` — not seconds — so parse the string or decode the JWT's `exp` claim rather than assuming a number. - **Refresh with `POST /v1/auth/refresh`.** The refresh token rotates on every use, and the new one comes back only in the `Set-Cookie` header. Sessions have a 30-day sliding window and a 90-day absolute cap; after that, the user logs in again. Details are in [API authentication](/api/authentication#token-lifetimes-and-refresh). - **The same JWT also works against the MCP server**, so a user-session app can call MCP tools on the user's behalf. ## One backend, three front doors The credentials map onto the two surfaces like this: | Surface | Accepts | |---|---| | REST API (`api.actuallycare.com/v1`) | API key, JWT | | MCP server (`mcp.actuallycare.com/mcp`) | OAuth 2.1, API key, JWT | Whichever door you come through, you're acting as a specific user with a specific role — authentication decides who you are, and the role decides what you can see and change. How roles shape data visibility is covered in [the data model](/concepts/data-model). --- # Data model > The entities behind your CRM and how they relate. ActuallyCare's data model follows the shape of a real estate business: people you know, deals in flight, properties you market, and the calendar that ties it together — plus newer verticals for vendor relationships and property management. This page is the conceptual map. For the exact fields and parameters of any operation, see the [tool reference](/tools) and the [endpoint reference](/api/reference). ## The core six The six entities you'll touch every day: | Entity | What it is | |---|---| | Contacts | Every person in your database | | Clients | People you represent | | Leads | Potential business in your pipeline | | Escrows | Active transactions, open to close | | Listings | Properties you're marketing | | Appointments | Your calendar | ### Contacts vs clients vs leads This distinction confuses almost everyone at first, so here it is plainly: - A **contact** is a *person*. Everyone in your database — past clients, leads, other agents, your lender, your mom — is a contact. It's the universal address book. - A **lead** is *potential business*. A lead represents someone moving through your pipeline who might transact with you. Leads get qualified, nurtured, and eventually [converted](/tools/leads/leads_convert) — or archived. - A **client** is an *active representation relationship*. When someone actually works with you — buying, selling, or both — they're a client. The key insight: lead and client aren't different people, they're different *relationships with the same person*. A client is always backed by a contact record. A lead holds its own name and contact details, and you can link it to existing contacts. Converting a lead creates the client and, if needed, its contact. ### Escrows, listings, and appointments - **Escrows** are transactions. An escrow opens when a deal goes under contract and tracks everything through closing. - **Listings** are inventory — properties you're marketing. A listing and an escrow often describe the same property at different stages: you list it, then it goes into escrow. - **Appointments** are calendar entries — showings you're driving to, listing presentations, closings, anything with a time attached. ## Around the transaction An escrow at the center of a deal accumulates satellite records: - **Documents** — files attached to the transaction (documents can attach to other records too). Documents can be run through AI risk analysis to surface red flags (see [`documents_get_risks`](/tools/documents/documents_get_risks)). - **Deadlines and checklists** — contingency deadlines, the escrow checklist, and deadline alerts so nothing slips during the contract period. Listings have their own satellites: - **Showings** — individual property showings, including buyer feedback. - **Open houses** — events with their own schedule and visitor logging. ## The vendor pipeline "Vendor" here means the service businesses around a transaction — lenders, escrow officers, inspectors, contractors, insurance agents, and other professionals you exchange business with. The vendor pipeline tracks those relationships the way the core pipeline tracks buyers and sellers: - **Prospects** — vendors you're evaluating but don't work with yet - **Partners** — vendors you actively work with - **Referrals** — business passed between you and a partner, in either direction - **Deals** — revenue opportunities that come out of those relationships - **Engagements** — logged interactions with partners, so the relationship history is on the record ## Property management For agents and brokerages doing property management, a dedicated set of entities covers the rental side: - **Rental applications** — applicants for a rental; an approved application can convert directly into a lease - **Leases** — the agreements themselves, with expiration tracking - **Tenancies** — the ongoing tenant relationship: rent collection, inspections, delinquency - **PM consultations** — intake conversations with property owners considering your management services; a consultation can convert into a tenancy ## Care status Care status is ActuallyCare's measure of follow-up health: is this relationship being actively cared for, or is it going cold? It changes as you log activity, and it gives "who needs attention?" a concrete answer instead of a gut feeling. Care status changes also fire `care_status.*` [webhook events](/concepts/webhooks), so you can build follow-up automation on top of it. ## Custom pipelines Beyond the built-in pipelines, ActuallyCare supports config-driven pipelines: pipeline types and stages are configuration, not code. Records move through stages, activity gets logged along the way, and you get pipeline-level reporting — which lets a team model a workflow the built-ins don't cover. See the [pipeline tools](/tools/pipelines). ## Entity links Sometimes two records are related in a way no built-in relationship captures — a lead who's interested in a specific listing, or a deal that depends on an escrow. **Entity links** are lightweight cross-references between escrows, deals, leads, clients, contacts, appointments, and listings. See the [entity link tools](/tools/entity-links). ## How your org shapes what you see Most users belong to a team inside a brokerage. Solo agents may have no team, and then they just see their own records: ```text Brokerage └─ Team └─ Agent (user) ├─ Contacts ── the person record ├─ Leads ──(convert)──► Clients (backed by a contact) ├─ Appointments ├─ Listings ◄─┐ │ ├─ Showings │ └─ Open houses ├─ Escrows ───┘ often the same property, two stages │ ├─ Documents (with AI risk analysis) │ └─ Deadlines and checklists ├─ Vendor pipeline: Prospects ► Partners ► Referrals · Deals · Engagements └─ Property mgmt: Applications ► Leases ► Tenancies · PM consultations ``` Data visibility follows four **visibility scopes** that map onto the hierarchy: **standard** (your own records), **team** (across your team), **brokerage** (across the brokerage), and **admin** (platform administration). Roles are how users land in a scope — the classic real estate roles map directly (agent → standard, team_lead → team, broker → brokerage, system_admin → admin), and other verticals add their own roles (lender, property_manager, escrow_officer, and more) that slot into the same four scopes. Whatever credential you connect with (Claude, an API key, a JWT), you act as a specific user, so this hierarchy applies everywhere — see [the authentication model](/concepts/authentication). ## IDs and lifecycle Treat IDs as opaque strings. Most are UUIDs, but not all: document IDs look like `doc_1a2b3c4d5e6f`, and webhook IDs like `wh_1a2b3c4d5e6f`. Escrows also have a human-readable display ID like `ESC-2026-0042`. Core entities share a soft-delete lifecycle: 1. **Archive** — the record leaves normal lists but nothing is lost. Reversible. 2. **Restore** — bring an archived record back. A restored lead's status goes back to `new`. 3. **Delete** — removes the record from the app. Deletes are role-gated, and a lead must be archived before it can be deleted (otherwise `422`). Deleting a client also removes its linked contact. Bulk versions of archive, restore, and delete exist for the core entities — see the [bulk operations tools](/tools/bulk-operations). When in doubt, archive: it's the safe default, and you can always restore. --- # Webhooks > Event-driven integration: catalog, signatures, retries. Webhooks turn your integration from pull to push. Instead of polling the API on a schedule and diffing results, you register a URL once and ActuallyCare sends an HTTP POST to it the moment something happens. This page covers the concepts — event catalog, payload, signatures, delivery. For a step-by-step walkthrough, see the [webhook setup guide](/guides/webhook-setup). ## Webhooks or polling? | Situation | Better fit | |---|---| | React to changes as they happen (new lead, escrow update) | Webhooks | | Periodic full sync or reporting snapshot | Polling the REST API | | You can't host a public HTTPS endpoint | Polling | | Low latency matters (lead routing, notifications) | Webhooks | The usual pattern is both: webhooks for the real-time signal, with an occasional polled reconciliation pass as a safety net. ## The event catalog The catalog is self-documenting. Ask the API what events exist (all `/v1/webhooks` endpoints take a JWT bearer token — not an API key — and need a broker or system-admin role, see [Managing webhooks](#managing-webhooks)): ```bash curl "https://api.actuallycare.com/v1/webhooks/events" \ -H "Authorization: Bearer YOUR_JWT" ``` The response uses the standard envelope: `data` lists every event type with its category, description, and a list of key fields, and `meta` totals it up. The delivered record usually has more fields than that list, and some events use different field names, so read fields defensively. Add `?category=` to get one category. Trimmed to two entries: ```json { "success": true, "data": [ { "event": "escrow.created", "category": "escrow", "description": "An escrow/transaction was created", "payload": ["id", "status", "property_address", "escrow_number"] }, { "event": "lead.created", "category": "lead", "description": "A new lead was created", "payload": ["id", "name", "email", "phone", "source", "status"] } ], "meta": { "total": 150, "categories": ["appointment", "care_status", "client", "..."] } } ``` The catalog covers every event name you can subscribe to — `escrow.*`, `lead.*`, `client.*`, `listing.*`, `appointment.*`, `care_status.*`, and more. Today, deliveries are sent for escrow, lead, client, listing, appointment, showing feedback, inventory, and care status events; other catalog events don't fire yet. A few representative examples: | Event | Fires when | |---|---| | `escrow.created` | A new escrow is opened | | `escrow.updated` | An escrow's details change | | `lead.created` | A new lead enters the pipeline | | `lead.status_changed` | A lead's status changes | | `client.created` | A new client relationship is created | | `listing.updated` | A listing's details change | | `appointment.status_changed` | An appointment's status changes (including cancellations) | | `care_status.changed` | A relationship's follow-up health changes | This table is illustrative — **the catalog endpoint is the source of truth.** `GET /v1/webhooks/events/categories` returns the category list if you want to browse by group. When you create a webhook you subscribe it to specific events, or to all of them. Event names aren't checked when you register, so a misspelled name is accepted and simply never fires — copy names from the catalog. ## The payload envelope Every delivery is a POST with a JSON body in the same envelope: ```json { "event": "escrow.created", "team_id": "3f8a1c2e-9d4b-4f6a-8e2d-1b7c5a9e0f3d", "timestamp": "2026-06-11T17:32:08.123Z", "data": { "id": "9c4e7b1a-2f8d-4e3c-a6b5-0d1f2e3a4b5c" } } ``` | Field | Meaning | |---|---| | `event` | The event type that fired | | `team_id` | The team the event belongs to, or `null` when the record has no team | | `timestamp` | When the event occurred | | `data` | The affected record — its shape depends on the event type | ## Verifying signatures Every delivery is signed so you can confirm it really came from ActuallyCare. Three headers arrive with each request: | Header | Contents | |---|---| | `X-Webhook-Signature` | `sha256=` followed by the HMAC-SHA256 hex digest of the JSON body, computed with your webhook secret (e.g. `sha256=3f5a…`). | | `X-Webhook-Event` | The event type, same as `event` in the body | | `X-Webhook-Timestamp` | The same value as `timestamp` in the body. It's set when the event is first sent and stays the same on retries | Compute the same HMAC over the raw request body and compare with a timing-safe comparison — never a plain string equality: ```javascript const crypto = require('crypto'); const express = require('express'); const app = express(); function verifySignature(rawBody, signatureHeader, secret) { const expectedHex = crypto .createHmac('sha256', secret) .update(rawBody) .digest('hex'); // Header format: "sha256=" const receivedHex = (signatureHeader || '').replace(/^sha256=/, ''); const expected = Buffer.from(expectedHex, 'hex'); const received = Buffer.from(receivedHex, 'hex'); return ( expected.length === received.length && crypto.timingSafeEqual(expected, received) ); } app.post( '/webhooks/actuallycare', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.get('X-Webhook-Signature'); if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) { return res.status(401).send('invalid signature'); } // Acknowledge fast, process async res.status(200).send('ok'); const payload = JSON.parse(req.body.toString('utf8')); // handle payload.event, payload.data ... } ); ``` Two details that bite people: verify against the **raw** body (a re-serialized JSON object may not match byte-for-byte), and remember to strip the `sha256=` prefix from the header before comparing digests. Your webhook secret is set when you create the webhook (minimum 10 characters). The API never returns it afterward — webhook responses show `"has_secret": true` instead — so store it when you create it. To change it, send a new `secret` with `PUT /v1/webhooks/:id`. ## Delivery and retries - ActuallyCare waits up to **30 seconds** for your endpoint to respond. Return a 2xx quickly and do real work asynchronously. - **Failed deliveries are retried** at 1 minute, 5 minutes, and 15 minutes after the initial attempt (up to 4 attempts total), then given up. A delivery counts as failed on a network error or on a `5xx`, `408`, or `429` response; other `4xx` responses are treated as your endpoint rejecting the event and are **not** retried. - Retries survive server restarts, and deactivating a webhook cancels its pending retries. - Retries currently apply to webhooks created by someone on a team. A brokerage-wide webhook (created by a broker with no team) gets each delivery once, without retries, so check its delivery logs if you rely on it. - Delivery is **at-least-once**: your endpoint can see the same event more than once, so process idempotently. The delivery logs — visible in the app, and available via `GET /v1/webhooks/:id/logs` — show every attempt. Deduplicate on the signature header value — a retried delivery carries the same signature as the original, and unlike `event` + `timestamp` it can't collide when two records fire the same event in the same instant. ## Managing webhooks A webhook belongs to the brokerage of the person who created it. If that person is on a team, it receives that team's events; if not, it receives every event in the brokerage. Webhooks are managed by **broker** and **system-admin** roles, and you see only your own brokerage's webhooks: any other webhook ID returns `404`. Two ways to manage them: - **In the app** — Settings, Webhooks tab (`app.actuallycare.com/settings?tab=webhooks`): create endpoints, choose events, and review delivery logs. - **Via REST** — `GET`/`POST /v1/webhooks` to list and create, `PUT`/`DELETE /v1/webhooks/:id` to update and deactivate, `GET /v1/webhooks/:id/logs` for delivery history. A deactivated webhook stops receiving deliveries; `PUT` with `"active": true` turns it back on. Your endpoint must be reachable on the public internet. Deliveries to private, loopback, and link-local addresses (like `localhost`) are blocked, so use a tunnel when testing locally. Ready to wire one up end to end? Follow the [webhook setup guide](/guides/webhook-setup). --- # MCP overview > What the ActuallyCare MCP server exposes, how Claude connects to it, and where to start. MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude work safely with outside systems. ActuallyCare runs an MCP server, which means Claude can look up your escrows, check today's appointments, or draft a follow-up for a hot lead — using your real CRM data, with your permission, under your account. If you just want to connect Claude, you only need one thing — the connector URL: ```text https://mcp.actuallycare.com/mcp ``` Paste it into Claude following the [quickstart](/mcp/quickstart) and you'll be connected in a few minutes. The rest of this page is the map of what's behind that URL. ## What the server exposes **Tools.** Actions covering every part of the CRM. Most are named entity first (`escrows_list`, `clients_create`, `leads_convert`); workflow tools are verb first (`get_dashboard_stats`, `draft_email`). The [tool reference](/tools) is generated straight from the server's registry, so the live counts and parameters there are always current. **Prompts.** 13 built-in prompts — ready-made workflows like `create_escrow`, `daily_summary`, `hot_leads_followup`, and `closing_checklist` that package a multi-step task into one request. Each has a generated reference page under [Prompts](/prompts). ## Which tools Claude can use To keep conversations fast, the server doesn't push the full catalog into every chat. It advertises a set of everyday tools — lists and lookups for your main records, creating and updating escrows, clients, leads, contacts, listings, and appointments, today's calendar, drafts, checklists, deadlines, and calculators — plus three discovery tools. Claude can only call the tools it's been given, so the advertised set is what Claude can do. The discovery tools can *describe* the rest of the catalog, but Claude can't run those tools yet. Custom apps and scripts are different: they can call any tool by name. See [Build a custom app](/mcp/custom-apps). ## Connection details | | | | --- | --- | | Server URL | `https://mcp.actuallycare.com/mcp` | | Transport | Streamable HTTP (JSON-RPC over POST, with an SSE stream on the same endpoint) | | Legacy transport | HTTP+SSE at `https://mcp.actuallycare.com/sse`, for older clients | | Protocol version | 2025-03-26 | ## Authentication - **OAuth 2.1** — the normal path for Claude users. Adding the connector opens an ActuallyCare login and a consent screen listing exactly what Claude may do. Access tokens last 24 hours and refresh tokens rotate automatically, so you stay connected without re-approving. To disconnect, remove the connector in Claude's own settings. - **API key** — custom clients can send the same 64-character keys the REST API uses, in the `X-API-Key` header. See [Authentication](/api/authentication). - **JWT** — a Bearer token from `POST /v1/auth/login` also works, which is handy when your app already manages ActuallyCare user sessions. ## Supported clients | Client | Status | Guide | | --- | --- | --- | | Claude.ai (web) | Supported | [Connect Claude on the web](/mcp/claude-web) | | Claude Desktop | Supported | [Connect Claude Desktop](/mcp/claude-desktop) | | Claude mobile (iOS and Android) | Supported — connectors added on the web appear in the app automatically | [Use ActuallyCare on mobile](/mcp/claude-mobile) | | Claude Code | Supported | [Connect Claude Code](/mcp/claude-code) | | Any standards-compliant MCP client | Supported | [Build a custom MCP app](/mcp/custom-apps) | | ChatGPT | Not yet | — | | Gemini | Not yet | — | ## Where to go next - **Agents and non-technical users:** the [quickstart](/mcp/quickstart) walks you through connecting Claude step by step, and [What can I ask?](/agents/what-can-i-ask) shows what to do once you're connected. - **Copying records into any AI:** every record in the CRM has a [Copy for AI](/mcp/copy-for-ai) action that pastes a compliant snapshot plus a live MCP reference — useful even before you connect. - **Developers:** [Build a custom MCP app](/mcp/custom-apps) covers connecting from your own code, and [API vs MCP](/concepts/api-vs-mcp) explains when to use the REST API instead. --- # Connect Claude Code > Add the ActuallyCare MCP server to Claude Code. > > **Skill:** Terminal · **Needs:** Claude Code Claude Code is Anthropic's terminal-based coding agent. Pointing it at the ActuallyCare MCP server gives you a CRM you can query from the command line, script against, and wire into automations. This page is for developers — if you want the no-terminal setup, start at the [quickstart](/mcp/quickstart) instead. ## Add the server One command, run anywhere: ```bash claude mcp add --transport http actuallycare https://mcp.actuallycare.com/mcp ``` This registers the server under the name `actuallycare` using the Streamable HTTP transport. By default the entry is scoped to the current project for you only; see [Project-scoped config](#project-scoped-config) for sharing it with a team. ## Authenticate The server uses OAuth, and Claude Code handles the browser dance for you. 1. Start Claude Code and run the `/mcp` command, then select **actuallycare**. **What you should see:** The MCP server list with `actuallycare` showing as needing authentication, and an option to authenticate. 2. Choose authenticate. Your browser opens an ActuallyCare page — sign in with your ActuallyCare credentials if asked, then click **Continue** on the **Connect with ActuallyCare** screen. It may show a yellow notice that ActuallyCare does not recognize this application, because Claude Code signs in through a local address on your computer. If you started the connection from Claude Code yourself, it's safe to continue. **What you should see:** A success page in the browser, and back in the terminal, `actuallycare` showing as connected. The OAuth callback runs on a temporary localhost port that Claude Code opens for you, and the server accepts localhost redirect URIs — no redirect-URI setup needed. Tokens refresh automatically, so this is a one-time step per machine. ## Verify ```bash claude mcp list ``` **What you should see:** output similar to: ```text actuallycare: https://mcp.actuallycare.com/mcp (HTTP) - ✓ Connected ``` Then prove it end to end inside a session: ```text > Using ActuallyCare, list my escrows closing in the next 14 days. ``` Claude calls `escrows_list` and returns live data. Note there is no `--mcp-list` flag — manage servers with the `claude mcp` commands shown above. ## Project-scoped config To check the server into a repo so every collaborator gets it, use project scope: ```bash claude mcp add --transport http --scope project actuallycare https://mcp.actuallycare.com/mcp ``` This writes `.mcp.json` at the project root: ```json { "mcpServers": { "actuallycare": { "type": "http", "url": "https://mcp.actuallycare.com/mcp" } } } ``` Commit it. Each developer still authenticates individually via `/mcp`, so everyone sees their own CRM data under their own permissions. ## What you can do with it - **Ad-hoc CRM queries while you work.** "Which of my listings are still active?", "Pull the contact info for the buyer on the Maple St escrow." - **Scripted, non-interactive queries** with print mode: ```bash claude -p "Using ActuallyCare, list my hot leads as a markdown table with name, phone, and source" ``` Pipe that into files, cron jobs, or Slack notifiers. - **Building automations and integrations.** Claude Code can call ActuallyCare tools while it writes code against them — e.g. "fetch one real client record with `clients_get`, then generate a TypeScript interface for it." Most tool names are entity first (`escrows_list`, `clients_create`, `leads_convert`); workflow tools are verb first (`get_dashboard_stats`, `draft_email`). The server advertises a set of everyday tools, and those are the ones Claude Code can call. `discover_tools` can describe the rest of the catalog, but to run those tools, use the [REST API](/api) or a [custom MCP client](/mcp/custom-apps), which can call any tool by name. Browse the full reference at [/tools](/tools). ## Headless use with an API key OAuth is right for interactive use, but CI jobs and servers can't click through a browser. The MCP server also accepts an ActuallyCare API key in an `X-API-Key` header: ```bash claude mcp add --transport http actuallycare https://mcp.actuallycare.com/mcp \ --header "X-API-Key: $ACTUALLYCARE_API_KEY" ``` Or in `.mcp.json`, with environment-variable expansion so the key never lands in the repo: ```json { "mcpServers": { "actuallycare": { "type": "http", "url": "https://mcp.actuallycare.com/mcp", "headers": { "X-API-Key": "${ACTUALLYCARE_API_KEY}" } } } } ``` Create a key at [app.actuallycare.com](https://app.actuallycare.com) → Settings → API Keys (`/settings?tab=api`). Keys are 64-character hex strings shown once at creation — store the full value immediately, and choose its access level. On the MCP server, a key's access level decides which tools it can call: **Full access** unlocks read and write tools, while **Read-only** and **Read & write** keys get read tools only (a write tool may delete). Keys with only per-resource grants are refused with `403 insufficient_scope`. Every user can create their own keys (Settings → API Keys → Create API Key). Full details in [API authentication](/api/authentication). ## Troubleshooting | Symptom | Fix | |---|---| | `claude mcp list` shows the server as failed or needing auth | Run `/mcp` inside a session and re-authenticate. | | Connection errors right after adding | Confirm you used `--transport http` and the exact URL `https://mcp.actuallycare.com/mcp`. | | Worked, then 401s in a headless setup | The API key was likely revoked or expired — create a new one in Settings → API Keys. | | Claude answers without calling tools | Say "Using ActuallyCare, ..." explicitly, or check the server is connected with `/mcp`. | ## Next steps - [Custom apps](/mcp/custom-apps) — talk to the MCP server from your own code instead of Claude Code - [API vs MCP](/concepts/api-vs-mcp) — when to use the REST API instead - [Tool reference](/tools) — every tool, generated from the live registry --- # Connect Claude Desktop > Set up the connector in the Claude Desktop app. > > **Takes:** 5 min · **Skill:** No code · **Needs:** Claude Desktop app Claude Desktop is the Claude app you install on your Mac or PC. Connecting it to ActuallyCare uses the exact same flow as the web: **Customize → Connectors → + Add → Add custom connector**. There are no files to edit and nothing to install beyond the app itself. ## Check first — it may already be connected Connectors belong to your Claude *account*, not to one device. If you already added ActuallyCare on [claude.ai](/mcp/claude-web) and you're signed in to Claude Desktop with the same account, the connector is often already there. 1. Open Claude Desktop and start a new chat, then click the **+** button by the message box and choose **Connectors**. **What you should see:** If **ActuallyCare** appears in the list, you're already set — skip down to [Verify it works](#verify-it-works). If it's not there, continue below. ## Add the connector in Claude Desktop 1. Open Claude Desktop and make sure you're signed in. **What you should see:** Claude's chat screen, the same layout as the website. 2. In the left sidebar, click **Customize**, then **Connectors**. **What you should see:** The **Connectors** page. It opens on the **Discover** tab; click **Yours** to see the connectors you've added. There's a **+ Add** button in the top corner. > [!STUCK] There's no Customize or Connectors option > > On a Claude Team or Enterprise plan, only an owner can add a custom connector, so ask yours to add ActuallyCare first. On the free plan, you can have one custom connector: if you already use a different one, remove it or upgrade. More in [I can't find the Connectors option](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). 3. Click **+ Add**, then **Add custom connector**. Type "ActuallyCare" in the **Name** box, paste `https://mcp.actuallycare.com/mcp` into the **MCP server URL** box, and click **Continue**. Claude then shows the sign-in settings it found: leave them as they are, and click **Continue**, then **Add**. **What you should see:** Your browser opens an ActuallyCare sign-in window. This is your CRM asking for permission — you sign in with your ActuallyCare username (or email) and password, not your Claude login. > [!STUCK] It won't accept my password > > The sign-in window wants your **ActuallyCare** username (or email) and password, the ones you use at [app.actuallycare.com](https://app.actuallycare.com), not your Claude login. If you've forgotten it, use **Forgot password?** on that sign-in page, then try again. 4. Sign in to ActuallyCare if asked, then click **Continue** on the screen titled **Connect with ActuallyCare**. It lists four permissions: read your CRM data (escrows, listings, clients, leads, and calendar); create and update records when you ask; draft emails and texts for your approval; and archive or delete records, with confirmation. **What you should see:** The browser window closes or tells you you're done, and ActuallyCare shows as connected on the **Yours** tab of Claude Desktop's Connectors page. > [!STUCK] It shows the wrong ActuallyCare account > > The screen shows which account you're signed in to. If it isn't the one with your clients and deals, click **Use a different account** and sign in with the right one before you click **Continue**. Already connected the wrong one? [Disconnect and reconnect](/agents/troubleshooting#how-do-i-disconnect-or-reconnect). ## Verify it works 1. Start a **new chat** in Claude Desktop, click **+** by the message box, then **Connectors**, and make sure **ActuallyCare** is switched on. **What you should see:** ActuallyCare in the Connectors list with its switch on. > [!STUCK] ActuallyCare isn't in the Connectors list > > Open **Customize → Connectors** in Claude Desktop and check that ActuallyCare is listed as connected. If it shows on claude.ai but not here, Claude Desktop is probably signed in to a different Claude account: check the account in both, sign in with the one that has the connector, or add it again under this account. 2. Ask: "Using ActuallyCare, give me a quick summary of my dashboard." **What you should see:** Claude checks ActuallyCare (if it asks permission first, choose **Allow**), then answers with your real numbers: leads, escrows, appointments. > [!STUCK] Claude gave general advice instead of my data > > Claude answered from memory instead of checking your CRM. Make sure **ActuallyCare** is switched on under **+** → **Connectors** (step 1), then start your question with "Using ActuallyCare, …". More in [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic). From here, anything in [What can I ask?](/agents/what-can-i-ask) works in Desktop exactly as it does on the web. The connection stays signed in on its own — you won't be asked to approve again during normal use. ## Managing or removing the connection Turning ActuallyCare off for a single conversation, or disconnecting it entirely, works the same as on the web — it's all done from Claude's own settings, and removing the connector there cuts off access from every device at once. See [managing the connection](/mcp/claude-web#manage-the-connection) for the steps. ## If something didn't work See the [troubleshooting page](/agents/troubleshooting), especially: - [I can't find the Connectors option in Claude](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude) — including when the connector shows on the web but not in Desktop (usually a different-account issue) - [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic) - [It says I'm unauthorized or my session expired](/agents/troubleshooting#it-says-im-unauthorized-or-my-session-expired) --- # Connect Claude on your phone > Use your CRM connector from the Claude mobile app. > > **Skill:** No code · **Needs:** Connector added on claude.ai first Your phone is where this connection earns its keep — between showings, in the car, walking out of a listing appointment. The Claude mobile app (iOS and Android) can use your ActuallyCare connector, with one catch: **you can't add the connector from inside the mobile app**. You add it once on claude.ai in a browser, and it then appears in the app automatically. ## First, add the connector on the web 1. Add the ActuallyCare connector on claude.ai by following [Connect Claude.ai (web)](/mcp/claude-web). You can do this in the browser on your phone — it doesn't need a computer. **What you should see:** ActuallyCare listed as connected under **Customize → Connectors** on claude.ai. If you've already done the web setup, there's nothing to repeat. Connectors belong to your Claude account, so the one you added on the web travels with you. ## Find it in the Claude mobile app 1. Open the Claude app on your phone and make sure you're signed in with the **same Claude account** you used on claude.ai. **What you should see:** Claude's chat screen. Same-account matters — a connector added under one account won't show up under another. 2. Start a new chat, tap the **+** button by the message box, then tap **Connectors**. **What you should see:** Your connectors, with **ActuallyCare** among them. You can switch it on or off per conversation right here. > [!STUCK] ActuallyCare isn't in the list > > Usually the app is signed in to a different Claude account than the one you used on claude.ai. Check the account email in the app's settings against claude.ai and sign in with the matching one. If they match, open claude.ai in your phone's browser and check that ActuallyCare shows as connected under **Customize → Connectors**; if it doesn't, add it there first. 3. Make sure ActuallyCare is toggled on, then ask: "Using ActuallyCare, give me a summary of my pipeline: how many active escrows and clients do I have?" **What you should see:** Claude checks ActuallyCare (if it asks permission first, tap **Allow**), then answers with your real numbers. > [!STUCK] Claude gave general advice instead of my data > > Claude answered from memory instead of checking your CRM. Make sure **ActuallyCare** is switched on under **+** → **Connectors** (step 2), then start your question with "Using ActuallyCare, …". More in [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic). ## Made for the road The mobile app supports voice dictation, which turns Claude into a hands-free CRM assistant. Tap the microphone and talk. Some real-world asks: **Right after a showing**, before you forget what the buyers said: > "Using ActuallyCare, log showing feedback for 42 Oak Ave — the buyers loved the kitchen, thought the backyard felt small, and want a second look this weekend." **Driving between appointments** (passenger seat or parked, please): > "What's left on my calendar today, and what are the addresses?" **Leaving an open house** with a pocket full of new names: > "Create a lead: Maria Lopez, phone 555-0142, met her at the Oak Avenue open house, looking for three bedrooms under seven fifty." **Walking up to a client's door**, needing a refresher: > "Give me a quick summary of everything we have on the Nguyens." **Waiting in the title office:** > "What's the status of the Hendersons' escrow? Anything due this week?" A note on safety: everything Claude logs or creates lands in your CRM where you can see and edit it. The connection works as your account — the same access you approved at setup — and anything outbound, like an email, starts as a draft until you give a clear okay. Details in [Permissions and safety](/agents/permissions-and-safety). ## If it isn't showing up The usual cause is two different Claude accounts — one on the web, another on the phone. Check the account email in the app's settings against the one on claude.ai. For everything else, see [I can't find the Connectors option in Claude](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude) and the rest of the [troubleshooting page](/agents/troubleshooting). --- # Connect Claude.ai (web) > Set up the connector on claude.ai in your browser. > > **Takes:** 5 min · **Skill:** No code · **Needs:** A Claude account (the free plan works) This is the full walkthrough for connecting ActuallyCare to Claude on the web at [claude.ai](https://claude.ai). It covers the same setup as the [5-minute quickstart](/mcp/quickstart), at a slower pace, plus how to manage the connection afterward — turning it on and off per conversation, and disconnecting it completely. The web setup is the one to learn first. The connector you add here belongs to your Claude account, so it also shows up in the [Claude desktop app](/mcp/claude-desktop) and the [Claude mobile app](/mcp/claude-mobile) when you're signed in with the same account. ## What you need - Your ActuallyCare login — the username (or email) and password you use at [app.actuallycare.com](https://app.actuallycare.com) - A Claude account at [claude.ai](https://claude.ai). Any Claude plan works, including the free one. The free plan allows one custom connector, so if you already use a different one, remove it first or upgrade. On a Claude Team or Enterprise plan, an owner adds ActuallyCare for your organization first, then you connect your own account. See [I can't find the Connectors option](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). You won't need anything technical. There are no codes to copy except one web address, and nothing you do here can delete or change your CRM data. ## Add the connector 1. Go to [app.actuallycare.com](https://app.actuallycare.com) in your browser and sign in. **What you should see:** Your ActuallyCare dashboard. You're doing this first so the sign-in step later happens automatically. ![The ActuallyCare dashboard after signing in: the top menu, the ActuallyCare Bar and a week strip with today highlighted](/screens/actuallycare-dashboard.webp "Signed in: your dashboard (shown with demo data)") 2. In a new tab, go to [claude.ai](https://claude.ai) and sign in to Claude. **What you should see:** Claude's chat screen, with a box at the bottom or middle where you'd normally type a message, and a sidebar on the left. 3. In the left sidebar, click **Customize**. **What you should see:** Claude's Customize page, open on its **Skills** tab, with **Connectors** and **Plugins** as tabs beside it. If a pop-up about Claude's features covers the page the first time, close it. 4. Click **Connectors**. **What you should see:** The **Connectors** page. It opens on the **Discover** tab; click **Yours** to see the connectors you've added. There's a **+ Add** button in the top corner. If you've never added one, **Yours** is empty, and that's normal. > [!STUCK] There's no Customize or Connectors option > > Adding a connector needs claude.ai in a web browser, not the phone app. On a Claude Team or Enterprise plan, only an owner can add a custom connector, so ask yours to add ActuallyCare first. More in [I can't find the Connectors option](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). 5. Click **+ Add**, then **Add custom connector**. **What you should see:** A form titled **Add custom connector**, with a **Name** box and an **MCP server URL** box, and a note to only use connectors from developers you trust. That note appears for every custom connector. ![Claude's Connectors page, with the + Add menu open on Add custom connector](/screens/claude-connectors-add.webp "Customize → Connectors, then + Add") 6. Type a name you'll recognize in the **Name** box — "ActuallyCare" works — and paste `https://mcp.actuallycare.com/mcp` into the **MCP server URL** box, exactly as written. **Continue** turns on once both are filled in; click it. **What you should see:** Claude shows the sign-in settings it found for ActuallyCare, over one or two screens. ![The Add custom connector form filled in: the name ActuallyCare and the URL https://mcp.actuallycare.com/mcp, with Cancel and Continue buttons](/screens/claude-add-custom-connector.webp "The form, filled in. Click Continue.") 7. Don't change those settings: Claude picked the right ones. Click **Continue**, then **Add**. **What you should see:** A new window or tab opens. This is the ActuallyCare sign-in and permission window — the next section explains what's in it. > [!STUCK] Nothing happened — no window opened > > A pop-up blocker most likely stopped it. Look for a blocked pop-up icon or message near the address bar and allow pop-ups for claude.ai. On an iPhone or iPad, open the **Settings** app, tap **Safari**, and turn off **Block Pop-ups** (you can turn it back on afterward). If ActuallyCare is now on your **Yours** tab with a **Connect** button, click it. Otherwise try again, and check that the address is exactly `https://mcp.actuallycare.com/mcp`, with no spaces. More in [The sign-in window never opened](/agents/troubleshooting#the-actuallycare-sign-in-window-never-opened). > [!STUCK] It won't accept my password > > The sign-in window wants your **ActuallyCare** username (or email) and password, the ones you use at [app.actuallycare.com](https://app.actuallycare.com), not your Claude login. If you've forgotten it, use **Forgot password?** on that sign-in page, then try again. ## What the sign-in window looks like This part trips people up, so here's exactly what to expect. The window that opens is an **ActuallyCare** page, not a Claude or Anthropic page. You're signing in to *your CRM* to tell it that Claude is allowed in. So: - If you weren't already signed in to ActuallyCare, you'll see the normal ActuallyCare login screen first. Use your ActuallyCare username (or email) and password — not your Claude login. - Once you're signed in, you'll see a permission screen titled **Connect with ActuallyCare**, naming Claude as the app asking for access. ![The ActuallyCare sign-in screen: Continue with Google, Continue with Microsoft, username and password fields, and a Sign in button](/screens/actuallycare-sign-in.webp "The ActuallyCare sign-in screen. If you see this, sign in with your ActuallyCare login.") 8. Read the permission screen. It lists exactly four permissions: - Read your CRM data — escrows, listings, clients, leads, and calendar - Create and update records when you ask - Draft emails and texts for your approval — nothing sends without your okay - Archive or delete records, with confirmation Click **Continue** when you're ready. **What you should see:** The window closes on its own, and back on Claude's Connectors page, ActuallyCare now appears on the **Yours** tab as connected. ![Claude's Customize page on Connectors → Yours, with ActuallyCare listed as Web, Custom, with a check mark under Status](/screens/claude-connectors-connected.webp "Connected: ActuallyCare on your Yours tab") > [!STUCK] It shows the wrong ActuallyCare account > > The screen shows which account you're signed in to. If it isn't the one with your clients and deals, click **Use a different account** and sign in with the right one before you click **Continue**. Already connected the wrong one? [Disconnect and reconnect](/agents/troubleshooting#how-do-i-disconnect-or-reconnect). Once you approve, you stay connected. Behind the scenes the connection refreshes itself automatically, so you won't be asked to approve again during normal use. For more on what Claude can and can't do once connected, see [Permissions and safety](/agents/permissions-and-safety). ## Use it in a conversation 9. Start a **new chat** in Claude. **What you should see:** A fresh, empty conversation. 10. Click the **+** button by the message box, then **Connectors**, and check that **ActuallyCare** is switched on. **What you should see:** ActuallyCare in the Connectors list with its switch on. If it's off, click the switch. ![The + menu under Claude's message box, open on Connectors, with ActuallyCare switched on in the submenu](/screens/claude-plus-menu-connectors.webp "In a chat: + then Connectors, ActuallyCare on") > [!STUCK] It says Reconnect, or ActuallyCare has a warning sign > > The connection has lapsed. In a chat, ActuallyCare shows a ⚠ warning sign and no switch. Go to **Customize → Connectors**, click **Yours**, and click **Reconnect** next to ActuallyCare. Sign in to ActuallyCare and click **Continue**. More in [It says Reconnect](/agents/troubleshooting#it-says-reconnect). 11. Ask something only your CRM would know, like: "Using ActuallyCare, give me a summary of my pipeline: how many active escrows and clients do I have?" **What you should see:** Claude checks ActuallyCare, then answers with your real numbers. On a new account, zero still counts. Whether Claude asks first depends on the chat's permission setting, next to the message box: in **Auto**, the default, it goes ahead without asking; if it does ask, choose **Allow**. > [!STUCK] Claude gave general advice instead of my data > > Claude answered from memory instead of checking your CRM. Make sure **ActuallyCare** is switched on under **+** → **Connectors** (step 10), then start your question with "Using ActuallyCare, …". More in [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic). Two useful things to know about how this works: - **Saying "Using ActuallyCare" helps.** Once Claude has used the connector a few times in a chat, you can drop it and just talk naturally. - **Claude already has its tools.** ActuallyCare turns on its everyday tools for Claude, so you never have to pick tools yourself. Some features — like production reports, open-house lists, and goals — aren't available in Claude yet. Not sure what to ask? Start with [What can I ask?](/agents/what-can-i-ask) ## Manage the connection ### Turn it off for one conversation You don't have to disconnect to keep ActuallyCare out of a particular chat. In any conversation, click **+** by the message box, then **Connectors**, and switch ActuallyCare off. That conversation won't touch your CRM; your other conversations are unaffected. ### Choose which tools need your OK Claude's connector page has a setting for each ActuallyCare tool. Click **Customize**, then **Connectors**, then **Yours**, then **ActuallyCare**. Next to each tool, pick **Always allow**, **Needs approval**, or **Blocked**. **Blocked** keeps Claude from using that tool at all. **Needs approval** makes Claude ask first, except in chats whose permission setting, next to the message box, is **Auto** (the default): there Claude goes ahead without asking. Whatever you choose, Claude can't send anything or delete records: see [Permissions and safety](/agents/permissions-and-safety). ### Disconnect completely 1. In claude.ai, click **Customize** in the left sidebar, then **Connectors**. **What you should see:** The Connectors page. Click **Yours** to see ActuallyCare in the list. 2. Find ActuallyCare and choose **Remove**. It may be behind the three-dot menu next to it. **What you should see:** ActuallyCare disappears from the list. Claude can no longer reach your CRM from any device. Disconnecting happens entirely on Claude's side — there's no separate switch to flip inside ActuallyCare. If you change your mind later, just add the connector again; it takes the same five minutes. ## If something didn't work Head to the [troubleshooting page](/agents/troubleshooting) for fixes to the most common problems: - [I can't find the Connectors option in Claude](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude) - [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic) - [It says I'm unauthorized or my session expired](/agents/troubleshooting#it-says-im-unauthorized-or-my-session-expired) - [How do I disconnect or reconnect?](/agents/troubleshooting#how-do-i-disconnect-or-reconnect) --- # Copy for AI > What the Copy for AI button copies, how a connected AI uses it, and what is deliberately left out. Every escrow, client, lead, appointment, listing, and contact in ActuallyCare has a **Copy for AI** action — in the ⋮ menu on dashboard cards, list rows, and table rows, and in the ⋯ menu on detail pages. One click puts a clean, AI-ready summary of that record on your clipboard, formatted so you can paste it straight into Claude, ChatGPT, or any assistant you use. ## What gets copied The copied text has two parts: **A snapshot.** A markdown table of the record's key fields — status, dates, prices, and so on — stamped with the date it was copied. Detail pages copy a fuller version than cards: more fields, and on escrows the buyer and seller roster too. Any AI (and any human) can read it as-is. **A live reference.** A short footer that tells a *connected* AI where the record lives: the ActuallyCare MCP server address, the record's ID, and which tool fetches it. If your AI is connected to ActuallyCare, it can ignore the snapshot and pull the current version of the record on demand — so your conversation stays accurate even as the deal moves. A trimmed example of what lands on your clipboard: ```text # Escrow — 123 Main St, Bakersfield _Snapshot from ActuallyCare CRM, copied 2026-07-24. Fields the platform excludes for fair-housing compliance are intentionally absent._ | Field | Value | | --- | --- | | Escrow status | active | | Purchase price | $485,000 | | Closing date | 2026-08-12 | ## Parties | Role | Name | Email | | --- | --- | --- | | Buyer (primary) | Jane Doe | jane@example.com | ## Live access via MCP - Server: https://mcp.actuallycare.com/mcp (OAuth) - Record: escrow `5f3c0000-…` - Call the `escrows_get` tool with `escrow_id` set to the record ID above. ``` ## With a connected AI vs. without **Connected (Claude today):** if you've linked Claude to ActuallyCare — see the [quickstart](/mcp/quickstart) — the footer is the useful half. Claude reads the record ID, calls the named tool, and works from live CRM data. You can paste just the stub of a copy into an ongoing conversation and say "pull this one up." **Not connected (ChatGPT and others, for now):** the snapshot is the useful half. It's a point-in-time copy, so treat it like a printout — accurate when copied, stale after things change. The copied date in the first line tells your AI exactly how fresh it is. Because the connection uses OAuth under your own ActuallyCare login, there are **no API keys to copy or paste, ever** — and a connected AI can only see what your account can see. ## What is deliberately left out Copy for AI is a compliance surface, not a raw export. The platform builds the text server-side and strips three categories before anything reaches your clipboard: - **Fair-housing and personal fields.** Protected characteristics (and adjacent fields like birthdays) are removed from every copy, the same data-layer rule ActuallyCare applies to its own AI. - **MLS-licensed listing data.** If a listing came from an MLS feed, its licensed content — address, price, remarks, photos — cannot be provided to outside services under IDX rules. Those copies show only your record ID, the listing status, and the city and state, plus a short MLS notice and the live-access footer. - **People who opted out.** A contact, client, or lead who opted out of AI processing can't be copied at all, and an opted-out party on an escrow is left off the roster — the copy notes how many people are excluded so your AI knows the list is incomplete. If a field you expected is missing from a copy, this list is almost always why. ## One thing to keep in mind Pasting into an outside AI shares that text with the AI's provider, under *their* data terms — same as pasting into any website. ActuallyCare strips what the law and your MLS license require, but choosing where to paste is up to you. The button politely refuses instead of copying if your brokerage has switched AI features off, or if you haven't yet accepted the AI Assistant disclosure in the app. --- # Build a custom MCP app > Connect your own application to the ActuallyCare MCP server with the TypeScript SDK, choose an auth method, and drive the tools with the Anthropic API. > > **Skill:** Developer (TypeScript) · **Needs:** Node.js The ActuallyCare MCP server isn't just for Claude. Any standards-compliant MCP client can connect to it, which means you can build things like: - **An internal dashboard** that asks the CRM questions in plain English and renders the answers - **A voice assistant** that looks up escrows and schedules showings while an agent is driving between appointments - **A nightly AI analyst** that pulls pipeline stats, flags stalled deals, and emails a summary before the morning standup The shape is always the same: your app speaks MCP to `https://mcp.actuallycare.com/mcp` over Streamable HTTP — JSON-RPC requests via POST, with an SSE stream for server-initiated messages. A legacy HTTP+SSE transport also exists at `/sse` for older clients. ## Quickstart: a TypeScript MCP client Install the official MCP TypeScript SDK ([github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk)): ```bash npm install @modelcontextprotocol/sdk ``` Then connect, list the tools, and call one. This example authenticates with an API key in the `X-API-Key` header (see [Authentication](#authentication) below for the other options): ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const mcp = new Client({ name: "my-actuallycare-app", version: "1.0.0" }); const transport = new StreamableHTTPClientTransport( new URL("https://mcp.actuallycare.com/mcp"), { requestInit: { headers: { "X-API-Key": process.env.ACTUALLYCARE_API_KEY! }, }, }, ); await mcp.connect(transport); // Discover the advertised tools const { tools } = await mcp.listTools(); console.log("Advertised tools:", tools.map((t) => t.name).join(", ")); // Call one const result = await mcp.callTool({ name: "escrows_list", arguments: {}, }); console.log(JSON.stringify(result.content, null, 2)); await mcp.close(); ``` You should see the advertised tool names first — names like `escrows_list`, `clients_list`, `appointments_today`, plus discovery tools like `discover_tools` — followed by the tool result. Tool results come back as MCP content blocks: an array of text items whose `text` carries the data as JSON. ```json [ { "type": "text", "text": "..." } ] ``` One important nuance: `tools/list` does **not** return everything. The server advertises a set of everyday tools plus discovery meta-tools. Your app can still call any other tool by name with `tools/call` — but Claude's own apps (claude.ai, Desktop, Code) can only call the advertised tools. Browse the full surface at [/tools](/tools) or fetch it as machine-readable JSON from [/tools.json](/tools.json). ## Authentication The MCP server accepts three credentials. Pick based on who the app acts as: | Method | Best for | Header | |---|---|---| | API key | Server-side apps acting as one account (dashboards, cron jobs) | `X-API-Key` | | JWT bearer token | Apps where users log in with their ActuallyCare credentials | `Authorization: Bearer ...` | | OAuth 2.1 | Apps users authorize without sharing credentials | `Authorization: Bearer ...` | ### API key (simplest) API keys are 64-character hex strings. Create one in the app under Settings → API Keys (`https://app.actuallycare.com/settings?tab=api`). Every user can create their own keys: Settings → API Keys → Create API Key. The full key is shown once at creation, so store it immediately; the UI only displays the first 8 and last 4 characters afterward. On the MCP server, a key's access level decides which tools it can call: **Full access** unlocks read and write tools, while **Read-only** and **Read & write** keys get read tools only (a write tool may delete). Keys with only per-resource grants are refused with `403 insufficient_scope`. Pass the key in the `X-API-Key` header on every request, as in the quickstart above. See [API authentication](/api/authentication) for key creation via the REST API and key management details. ### JWT bearer token (user-session apps) If your app already signs users in against the ActuallyCare REST API, the same JWT works against the MCP server. Log in via the REST API to get an access token, then send it as `Authorization: Bearer` instead of `X-API-Key`: ```typescript const transport = new StreamableHTTPClientTransport( new URL("https://mcp.actuallycare.com/mcp"), { requestInit: { headers: { Authorization: `Bearer ${accessToken}` }, }, }, ); ``` Access-token lifetime is role-based (15 minutes to 8 hours), so build in token refresh. The login and refresh flows are documented in [API authentication](/api/authentication). ### OAuth 2.1 (user-delegated apps) For apps acting on behalf of users who shouldn't hand you their password, the MCP server supports OAuth 2.1 with PKCE and dynamic client registration. Register your client with `POST /register` on `mcp.actuallycare.com`, then run the standard authorization-code flow with PKCE: the user logs into ActuallyCare, approves a consent screen, and your app receives tokens scoped to that user. Request `read` for read tools and `write` for write tools. The server also accepts an `mcp` scope, but it grants nothing on its own. If you omit `scope`, you get `read write mcp`. The full list is published in the [authorization-server metadata](https://mcp.actuallycare.com/.well-known/oauth-authorization-server). Access tokens last 24 hours, and refresh tokens last 30 days and rotate on every refresh, so the connection stays live without re-approval as long as it's used at least once every 30 days. To disconnect a user, call `POST /revoke` with their token. This is the same flow Claude itself uses when someone adds ActuallyCare as a connector. ## Drive the tools with Claude The most common custom app is a thin loop: send a question to Claude through the Anthropic API, hand it the ActuallyCare tool definitions, execute whatever tools it asks for against the MCP server, and feed the results back. ```bash npm install @anthropic-ai/sdk ``` ```typescript import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); // reads ANTHROPIC_API_KEY from the environment // 1. Fetch tool definitions from the MCP server and convert to Anthropic's shape const { tools } = await mcp.listTools(); const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description ?? "", input_schema: t.inputSchema, })); // 2. The tool-use loop let messages: Anthropic.MessageParam[] = [ { role: "user", content: "Which of my escrows are closing soonest?" }, ]; while (true) { const response = await anthropic.messages.create({ model: "claude-sonnet-5-5", max_tokens: 16000, tools: anthropicTools, messages, }); if (response.stop_reason !== "tool_use") { for (const block of response.content) { if (block.type === "text") console.log(block.text); } break; } // 3. Execute each tool_use block against the MCP server messages.push({ role: "assistant", content: response.content }); const toolResults: Anthropic.ToolResultBlockParam[] = []; for (const block of response.content) { if (block.type === "tool_use") { const result = await mcp.callTool({ name: block.name, arguments: block.input as Record, }); toolResults.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(result.content), }); } } // 4. Return the results and let Claude continue messages.push({ role: "user", content: toolResults }); } ``` Because `listTools()` only returns the advertised hot-list, Claude starts with the most-used tools. That's usually what you want — but if your app needs the whole surface up front, build your tool array from [/tools.json](/tools.json) instead. Every documented tool is callable by name whether or not it's advertised. For the full tool-use pattern — streaming, parallel tool calls, error handling — see the Anthropic documentation at [docs.anthropic.com](https://docs.anthropic.com). ## Operational notes | Limit | Value | |---|---| | Requests | 120 per minute per user | | Tool calls | 30 per minute per user | | Tool execution timeout | 300 seconds | A few things to design around: - **Back off on rate-limit errors.** The per-user limits above apply across everything that user's credentials touch, so a busy dashboard and a background job sharing one key share one budget. - **Long-running tools.** Most tools return in well under a second, but the server allows up to 300 seconds per call — keep your own HTTP timeouts above that if you call heavyweight tools. - **Progressive disclosure.** As covered above, `tools/list` advertises only the everyday tools; call anything else by name. Consult [/tools.json](/tools.json) for the complete, always-current catalog. - **Large results are truncated.** A tool result is cut off at roughly 25,000 tokens, so page through big lists with `limit` and `offset`. - **One request per POST.** JSON-RPC batches are rejected with `400`. The server accepts the `2025-06-18` and `2025-03-26` protocol versions in the `MCP-Protocol-Version` header. - **Safe retries.** Send an `Idempotency-Key` header on `tools/call` so a retried write runs only once. - **Browser origins.** Requests with an `Origin` header are accepted only from Claude, ActuallyCare, and `localhost` origins; anything else gets `403`. Call the server from your backend. - **Built-in prompts.** The server ships ready-made prompt templates — `daily_summary`, `escrow_status_check`, `hot_leads_followup`, and more — that your app can list and invoke via the standard MCP prompts capability. The full reference is at [/prompts](/prompts). ## Security - **Keep credentials server-side.** Never put an API key, JWT, or OAuth token in browser JavaScript — anything shipped to the client is readable by anyone who opens dev tools. Browser apps should talk to your backend, and your backend talks to the MCP server. - **Scope keys minimally.** Scopes are what **grant** a key access. Give each app the narrowest level that works: a **Read-only** key for a dashboard, and **Full access** only for an app that must call write tools, and set an expiration rather than minting forever-keys — a key without one never expires. - **Write access can act in the real world.** Any credential with `write` can call every tool by name, including ones that are never offered to Claude. Some have real side effects and no confirmation step: `send_review_request` emails a client, and `website_publish` and `landing_page_publish` make pages public. If your app calls these, add your own confirmation. - **One key per app.** Separate keys per integration make rotation painless and let you revoke a compromised app without breaking the others. - **Treat keys like passwords.** They're stored hashed and shown once — if a key leaks, revoke it and create a new one. --- # Connect Claude in 5 minutes > Link Claude to your ActuallyCare CRM, step by step. > > **Takes:** 5 min · **Skill:** No code · **Needs:** A Claude account (the free plan works) This page connects Claude — the AI assistant from Anthropic — to your ActuallyCare account. Once connected, you can ask Claude things like "what's on my calendar today?" and it answers straight from your CRM. You'll do everything in your web browser on claude.ai. A computer, tablet, or phone all work — on a phone, use the browser rather than the Claude app for this one-time setup. No downloads, no technical setup. It takes about five minutes, and you can undo it any time from Claude's connector settings. ## Before you start You need two things: - Your ActuallyCare login: the username (or email) and password you use at [app.actuallycare.com](https://app.actuallycare.com) - A Claude account at [claude.ai](https://claude.ai). Any Claude plan works, including the free one. The free plan allows one custom connector, so if you already use a different one, remove it first or upgrade. On a Claude Team or Enterprise plan, an owner adds ActuallyCare for your organization first, then you connect your own account. See [I can't find the Connectors option](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). ## Connect Claude 1. Go to [app.actuallycare.com](https://app.actuallycare.com) and sign in to ActuallyCare. **What you should see:** Your ActuallyCare dashboard. Signing in now means you won't have to type your password again mid-setup. ![The ActuallyCare dashboard after signing in: the top menu, the ActuallyCare Bar and a week strip with today highlighted](/screens/actuallycare-dashboard.webp "Signed in: your dashboard (shown with demo data)") 2. Open a new browser tab and sign in at [claude.ai](https://claude.ai). **What you should see:** Claude's chat screen with a message box in the middle and a sidebar on the left. 3. In Claude's left sidebar, click **Customize**, then **Connectors**. **What you should see:** Customize opens on its **Skills** tab, with **Connectors** as a tab beside it. On the Connectors tab, **Discover** is selected; click **Yours** to see the connectors you've added. There's a **+ Add** button in the top corner. If a pop-up about Claude's features covers the page the first time, close it. > [!STUCK] There's no Customize or Connectors option > > Adding a connector needs claude.ai in a web browser. If you're on the Claude phone app, open claude.ai in your phone's browser for this setup. On a Claude Team or Enterprise plan, only an owner can add a custom connector, so ask yours to add ActuallyCare first. More in [I can't find the Connectors option](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). 4. Click **+ Add**, then **Add custom connector**. **What you should see:** A form titled **Add custom connector** with two boxes, **Name** and **MCP server URL**, and **Cancel** and **Continue** buttons. ![Claude's Connectors page, with the + Add menu open on Add custom connector](/screens/claude-connectors-add.webp "Customize → Connectors, then + Add") 5. Type **ActuallyCare** in the **Name** box and paste `https://mcp.actuallycare.com/mcp` into the **MCP server URL** box. **Continue** turns on once both are filled in; click it. **What you should see:** Claude shows the sign-in settings it found for ActuallyCare. (The form also warns you to only use connectors from developers you trust. That's Claude's standard note for every custom connector.) ![The Add custom connector form filled in: the name ActuallyCare and the URL https://mcp.actuallycare.com/mcp, with Cancel and Continue buttons](/screens/claude-add-custom-connector.webp "The form, filled in. Click Continue.") 6. Leave those settings as they are: click **Continue**, then **Add**. **What you should see:** A new window opens asking you to connect to ActuallyCare. If you weren't already signed in to ActuallyCare, it asks you to sign in first. Use your normal ActuallyCare login, not your Claude login. > [!STUCK] Nothing happened — no window opened > > A pop-up blocker most likely stopped it. Look for a blocked pop-up icon or message near the address bar and allow pop-ups for claude.ai. On an iPhone or iPad, open the **Settings** app, tap **Safari**, and turn off **Block Pop-ups** (you can turn it back on afterward). If ActuallyCare is now in your connectors list with a **Connect** button, click it. If it still won't open, check that the address is exactly `https://mcp.actuallycare.com/mcp`, with no spaces. More in [The sign-in window never opened](/agents/troubleshooting#the-actuallycare-sign-in-window-never-opened). > [!STUCK] It won't accept my password > > This window wants your **ActuallyCare** username (or email) and password, the ones you use at [app.actuallycare.com](https://app.actuallycare.com), not your Claude login. If you've forgotten it, use **Forgot password?** on that sign-in page, then try this step again. 7. On the screen titled **Connect with ActuallyCare**, check that it names Claude as the app asking for access, read the permissions, and click **Continue**. It asks for exactly four things: - Read your CRM data — escrows, listings, clients, leads, and calendar - Create and update records when you ask - Draft emails and texts for your approval — nothing sends without your okay - Archive or delete records, with confirmation **What you should see:** The window closes and ActuallyCare appears in your connectors list as connected. ![Claude's Customize page on Connectors → Yours, with ActuallyCare listed as Web, Custom, with a check mark under Status](/screens/claude-connectors-connected.webp "Connected: ActuallyCare on your Yours tab") > [!STUCK] It shows the wrong ActuallyCare account > > The screen shows which account you're signed in to. If it isn't the one with your clients and deals, click **Use a different account** and sign in with the right one before you click **Continue**. Already connected the wrong one? [Disconnect and reconnect](/agents/troubleshooting#how-do-i-disconnect-or-reconnect). 8. Go back to Claude and start a new chat. Click the **+** button by the message box, then **Connectors**, and make sure **ActuallyCare** is switched on. **What you should see:** ActuallyCare in the Connectors list with its switch on. ![The + menu under Claude's message box, open on Connectors, with ActuallyCare switched on in the submenu](/screens/claude-plus-menu-connectors.webp "In a chat: + then Connectors, ActuallyCare on") > [!STUCK] It says Reconnect, or ActuallyCare has a warning sign > > The connection has lapsed. In a chat, ActuallyCare shows a ⚠ warning sign and no switch. Go to **Customize → Connectors**, click **Yours**, and click **Reconnect** next to ActuallyCare. Sign in to ActuallyCare and click **Continue**. More in [It says Reconnect](/agents/troubleshooting#it-says-reconnect). 9. Type this and send it: "Using ActuallyCare, give me a summary of my pipeline: how many active escrows and clients do I have?" **What you should see:** Claude checks ActuallyCare, then tells you how many active escrows and clients you have, pulled live from your CRM. Check the numbers against the app. On a new account, "you have no active escrows yet" still counts as success. Whether Claude asks first depends on the chat's permission setting, next to the message box: in **Auto**, the default, it goes ahead without asking; if it does ask, choose **Allow**. > [!STUCK] Claude gave general advice instead of my numbers > > Claude answered from memory instead of checking your CRM. Make sure **ActuallyCare** is switched on under **+** → **Connectors** (step 8), then start your question with "Using ActuallyCare, …". Ask something only your CRM knows, like a client's phone number, and check that it matches the app. More in [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic). That's it. You're connected. Claude gets ActuallyCare's everyday tools automatically, so there's nothing else to configure. ## Try these first Five good first asks, in plain English: - "Show me my hot leads." - "Give me a summary of my dashboard — what needs my attention?" - "Which of my escrows are closing this month?" - "Pull up everything we have on the Hendersons." - "Create a lead: Maria Lopez, phone 555-0142, met her at the open house on Oak Avenue." For a much longer list of ideas, see [What can I ask?](/agents/what-can-i-ask) And if you're wondering what Claude is and isn't allowed to do with your data, read [Permissions and safety](/agents/permissions-and-safety). ## Using Claude somewhere other than the browser The connector you just added follows your Claude account around: - **On the Claude desktop app** — it's usually already there. See [Connect Claude Desktop](/mcp/claude-desktop). - **On your phone** — it shows up in the Claude mobile app automatically. See [Connect Claude on your phone](/mcp/claude-mobile). - **Developer in a terminal** — add it to Claude Code with one command. See [Connect Claude Code](/mcp/claude-code). ## If something didn't work The fixes for the most common problems are on the [troubleshooting page](/agents/troubleshooting): - The Connectors section or the connector itself is missing — see [I can't find the Connectors option in Claude](/agents/troubleshooting#i-cant-find-the-connectors-option-in-claude). - Nothing happened after you pasted the URL — it's usually a pop-up blocker. See [The ActuallyCare sign-in window never opened](/agents/troubleshooting#the-actuallycare-sign-in-window-never-opened). - Claude answers from general knowledge instead of your CRM — see [It connected but answers seem generic](/agents/troubleshooting#it-connected-but-answers-seem-generic). - ActuallyCare shows a ⚠ or a **Reconnect** button — see [It says Reconnect](/agents/troubleshooting#it-says-reconnect). - It worked before and stopped — see [It says I'm unauthorized or my session expired](/agents/troubleshooting#it-says-im-unauthorized-or-my-session-expired). --- # Where to find the ActuallyCare MCP server > Every place the ActuallyCare MCP server is published or discoverable — the endpoint, the registry entry, machine-readable indexes, and support contacts. One MCP server, several ways to discover it. This page is the canonical list — if a tool, registry, or agent needs to find ActuallyCare, everything it needs is below. ## The server | | | | --- | --- | | Endpoint | `https://mcp.actuallycare.com/mcp` | | Transport | Streamable HTTP (a legacy HTTP+SSE endpoint exists at `/sse` for older clients) | | Auth | OAuth 2.1 with PKCE and dynamic client registration — clients discover everything from the `WWW-Authenticate` header and `/.well-known/oauth-authorization-server`. Custom clients can also use an API key (`X-API-Key`) or a JWT | | Scopes | `read` for read tools, `write` for write tools (`mcp` is accepted but grants nothing on its own) | | Account required | An ActuallyCare login ([app.actuallycare.com](https://app.actuallycare.com)) | To connect from Claude, follow [Connect Claude in 5 minutes](/mcp/quickstart) (Claude.ai, Desktop, or mobile) or [Connect Claude Code](/mcp/claude-code). For any other MCP client, paste the endpoint URL and complete the OAuth flow in your browser. ## Official MCP Registry The server's canonical registry identity is **`com.actuallycare/actuallycare`** on the [official MCP Registry](https://registry.modelcontextprotocol.io) — the feed that downstream directories (Smithery, Glama, MCP.so) and client-side registry search mirror. The listing is live (published July 4, 2026). ## Machine-readable surfaces For AI agents and crawlers, everything on this site is available in machine-friendly form: | Surface | URL | What it is | | --- | --- | --- | | Pointer file | [`/.well-known/ai.json`](https://docs.actuallycare.com/.well-known/ai.json) | One JSON file linking every surface in this table | | Tool index | [`/tools.json`](https://docs.actuallycare.com/tools.json) | Every MCP tool — names, descriptions, JSON schemas, safety annotations | | llms.txt | [`/llms.txt`](https://docs.actuallycare.com/llms.txt) | Index of all documentation pages with one-line summaries | | llms-full.txt | [`/llms-full.txt`](https://docs.actuallycare.com/llms-full.txt) | Every documentation page concatenated into one file | | Sectioned files | [`/llms-mcp.txt`](https://docs.actuallycare.com/llms-mcp.txt), [`/llms-api.txt`](https://docs.actuallycare.com/llms-api.txt), [`/llms-tools.txt`](https://docs.actuallycare.com/llms-tools.txt) | Smaller slices of the full file: MCP and agent setup, the REST API, and the tool reference | | OpenAPI spec | [`api.actuallycare.com/v1/openapi.json`](https://api.actuallycare.com/v1/openapi.json) | The REST API specification | | Markdown mirrors | append `.md` to any page URL | Raw Markdown of every docs page (not the home page); also served via `Accept: text/markdown` | ## Support and policies - **Support:** [support@actuallycare.com](mailto:support@actuallycare.com) or [www.actuallycare.com/contact](https://www.actuallycare.com/contact) — questions about the MCP server, the API, or these docs. Signed-in users can also file issues from the in-app support widget. - **Privacy policy:** [www.actuallycare.com/privacy](https://www.actuallycare.com/privacy) - **Troubleshooting the connector:** [Troubleshooting](/agents/troubleshooting) --- # Prompt library > The built-in MCP prompts plus the best plain-English asks for your CRM. Once Claude is connected to ActuallyCare (five-minute setup: [quickstart](/mcp/quickstart)), there are two ways to get things done. Pick a ready-made prompt from Claude's menu, or skip the menu and ask in your own words. Both work. This page covers both. ## Built-in prompts The ActuallyCare MCP server ships ready-made prompts. On claude.ai and in the Claude apps, they show up in Claude's prompt menu — in a chat, look behind the **+** button by the message box. Each one is a guided starting point: a well-written request that tells Claude what to look up and what to ask you for. **What you should see:** the ActuallyCare prompts listed by name — daily_summary, find_client, and the rest of the table below. The menu is optional. If you don't see it, just ask in your own words — same result. Prompts use the same everyday tools as any other ask. When a prompt asks for something those tools don't cover — like paid commissions from your commission ledger, or follow-up reminders — Claude works from what it can see (your escrows, clients, leads, and calendar), so that part of the answer may be partial. | Prompt | Reach for it when... | |---|---| | [daily_summary](/prompts/daily_summary) | Monday morning, coffee in hand — "what does today look like?" | | [hot_leads_followup](/prompts/hot_leads_followup) | You're worried leads are going cold and want a follow-up plan | | [find_client](/prompts/find_client) | You half-remember a name, or only have a phone number | | [client_portfolio](/prompts/client_portfolio) | You're about to call a client and want their full history first | | [lead_qualification](/prompts/lead_qualification) | A brand-new lead just came in and you want to qualify them properly | | [update_lead_status](/prompts/update_lead_status) | A lead just moved forward — or stalled — in your pipeline | | [create_escrow](/prompts/create_escrow) | You just opened escrow and want it in the system without missing a field | | [escrow_status_check](/prompts/escrow_status_check) | Someone asks "where are we on the Smith deal?" | | [closing_checklist](/prompts/closing_checklist) | Closing is a week out and you want nothing slipping through | | [document_request](/prompts/document_request) | An escrow is missing paperwork and you need to chase it down | | [schedule_showing](/prompts/schedule_showing) | A buyer wants to see a property | | [commission_report](/prompts/commission_report) | You want to know what's pending and what's been paid | | [market_snapshot](/prompts/market_snapshot) | You're prepping a listing presentation and need current numbers | ### What a daily_summary response looks like Here's a realistic example of the kind of answer **daily_summary** produces — your data will differ, but the shape is the same: > **Good morning! Here's your briefing for January 18, 2026:** > > **Today's Schedule (3 appointments):** > - 10:00 AM - Showing at 123 Oak St with Sarah Johnson > - 2:00 PM - Listing presentation at 456 Pine Ave > - 4:30 PM - Buyer consultation with Michael Chen > > **Deadlines This Week (2):** > - 321 Elm St: Contingency removal due in 3 days > - 789 Maple Dr: Appraisal due Friday > > **Past Due (1):** > - 456 Pine Ave: Seller disclosures were due 2 days ago > > **Hot Leads to Contact (3):** > - David Kim - Last contacted 8 days ago (buyer, $800K budget) > - Jennifer Lee - Requested showing, no response yet > - Robert Taylor - Pre-approved, looking in Beverly Hills > > **Quick Stats:** > - Active escrows: 4 > - Closing this month: 2 > - New leads this month: 7 > > Would you like me to expand on any of these items? ## Or just ask You never need the menu. Claude understands plain English and picks the right tool on its own — the built-in prompts are shortcuts, not requirements. Some of the best asks, grouped by mood: ### Morning - "What's my day look like?" - "Anything urgent I should handle before my 10 a.m.?" ### Money - "What's my split on the Maple Drive sale at 2.5%?" - "Run a seller net sheet for Pine Avenue at $725,000." ### People - "Who haven't I talked to in 30 days?" - "Pull up everything we have on the Hendersons before I call them." - "Which of my leads are going cold?" ### Transactions - "Which escrows close this month, and is anything blocking them?" - "What deadlines are coming up on the Maple Drive escrow?" - "Draft a status update email for my seller on Pine Avenue." For a much longer list of ideas, see [What can I ask?](/agents/what-can-i-ask) And if you're wondering what Claude can and can't do with your data, read [Permissions and safety](/agents/permissions-and-safety). --- # client_portfolio > Get complete portfolio and history for a client Get complete portfolio and history for a client. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **client_portfolio** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Give me the full picture on the Garcias." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `client_name` | Yes | Client name or email | --- # closing_checklist > Generate pre-closing verification checklist for an escrow Generate pre-closing verification checklist for an escrow. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **closing_checklist** from the prompt menu — or skip the menu entirely and just ask in plain English: > "What's left before we can close 123 Main St?" ## Arguments | Argument | Required | Description | | --- | --- | --- | | `escrow_id` | Yes | Escrow ID or property address | --- # commission_report > Generate a commission report with pending and paid amounts Generate a commission report with pending and paid amounts. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **commission_report** from the prompt menu — or skip the menu entirely and just ask in plain English: > "How much commission do I have pending this month?" ## Arguments | Argument | Required | Description | | --- | --- | --- | | `period` | No | Time period (this_month, last_month, this_year, all) | --- # create_escrow > Guided workflow for creating a new escrow transaction Guided workflow for creating a new escrow transaction. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **create_escrow** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Open a new escrow for 123 Main St at $450,000." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `property_address` | Yes | Property address for the escrow | | `purchase_price` | Yes | Purchase price in dollars | | `buyer_name` | No | Name of the buyer | | `seller_name` | No | Name of the seller | --- # daily_summary > Generate a summary of today's activities, tasks, and appointments Generate a summary of today's activities, tasks, and appointments. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **daily_summary** from the prompt menu — or skip the menu entirely and just ask in plain English: > "What's my day look like?" ## Arguments _None — this prompt needs no input._ --- # document_request > Generate document request for an escrow Generate document request for an escrow. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **document_request** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Draft a request for the missing inspection report on the Smith escrow." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `escrow_id` | Yes | Escrow ID | | `doc_type` | No | Document type needed (optional) | --- # escrow_status_check > Check the status of an escrow and its pending tasks Check the status of an escrow and its pending tasks. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **escrow_status_check** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Where are we on the Johnson escrow?" ## Arguments | Argument | Required | Description | | --- | --- | --- | | `escrow_identifier` | Yes | Escrow number, property address, or client name | --- # find_client > Smart client lookup by name, email, or phone number Smart client lookup by name, email, or phone number. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **find_client** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Find my client Sarah — I think her email ends in @gmail.com." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `search_term` | Yes | Name, email, or phone to search for | --- # hot_leads_followup > Get a list of hot leads that need follow-up with suggested actions Get a list of hot leads that need follow-up with suggested actions. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **hot_leads_followup** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Who should I follow up with today?" ## Arguments _None — this prompt needs no input._ --- # lead_qualification > Guided lead qualification questionnaire Guided lead qualification questionnaire. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **lead_qualification** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Help me qualify the new lead from the open house." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `lead_name` | Yes | Lead name or email | --- # market_snapshot > Current real estate market statistics Current real estate market statistics. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **market_snapshot** from the prompt menu — or skip the menu entirely and just ask in plain English: > "How's the market in Bakersfield right now?" ## Arguments | Argument | Required | Description | | --- | --- | --- | | `area` | No | City or zip code (optional) | --- # schedule_showing > Schedule a property showing appointment Schedule a property showing appointment. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **schedule_showing** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Set up a showing at 42 Oak Ave for the Hendersons next Saturday afternoon." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `property_address` | Yes | Property address or MLS number | | `client_name` | Yes | Client name for the showing | | `preferred_date` | No | Preferred date (e.g., "tomorrow", "next Monday") | | `preferred_time` | No | Preferred time (e.g., "2pm", "afternoon") | --- # update_lead_status > Update the status of a lead in the pipeline Update the status of a lead in the pipeline. ## How to use it This is a built-in prompt on the ActuallyCare MCP server. In Claude clients that support MCP prompts you can pick **update_lead_status** from the prompt menu — or skip the menu entirely and just ask in plain English: > "Mark the lead Mike Torres as qualified — he got pre-approved today." ## Arguments | Argument | Required | Description | | --- | --- | --- | | `lead_identifier` | Yes | Lead name, email, or ID | | `new_status` | Yes | New status (new, contacted, qualified, converted, lost) | | `notes` | No | Notes about the status change |