# Connect Claude Code

> Add the ActuallyCare MCP server to Claude Code.

<!-- Source: https://docs.actuallycare.com/mcp/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 approve the **Grant Claude access to ActuallyCare** consent screen.

   **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 listings expire this month?", "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."

Tool names follow an `entity_verb` convention — `escrows_list`, `clients_create`, `leads_convert`, `appointments_today`, `get_dashboard_stats`. The server advertises the most-used tools up front and lets Claude discover the rest on demand, so don't worry if the initial tool list looks short. 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 make sure the key is granted the scopes it needs (a key with no scopes gets `403` everywhere). 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