Skip to content
For developers

Connect Claude Code

Add the ActuallyCare MCP server to Claude Code.

Skill
Terminal
Needs
Claude Code

Last updated

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

Add the server#

One command, run anywhere:

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

claude mcp list

What you should see: output similar to:

actuallycare: https://mcp.actuallycare.com/mcp (HTTP) - ✓ Connected

Then prove it end to end inside a session:

> 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:

claude mcp add --transport http --scope project actuallycare https://mcp.actuallycare.com/mcp

This writes .mcp.json at the project root:

{
  "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:

    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 or a custom MCP client, which can call any tool by name. Browse the full reference at /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:

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:

{
  "mcpServers": {
    "actuallycare": {
      "type": "http",
      "url": "https://mcp.actuallycare.com/mcp",
      "headers": {
        "X-API-Key": "${ACTUALLYCARE_API_KEY}"
      }
    }
  }
}

Create a key at 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.

Troubleshooting#

SymptomFix
claude mcp list shows the server as failed or needing authRun /mcp inside a session and re-authenticate.
Connection errors right after addingConfirm you used --transport http and the exact URL https://mcp.actuallycare.com/mcp.
Worked, then 401s in a headless setupThe API key was likely revoked or expired — create a new one in Settings → API Keys.
Claude answers without calling toolsSay "Using ActuallyCare, ..." explicitly, or check the server is connected with /mcp.

Next steps#

  • Custom apps — talk to the MCP server from your own code instead of Claude Code
  • API vs MCP — when to use the REST API instead
  • Tool reference — every tool, generated from the live registry