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
Last updated
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):
npm install @modelcontextprotocol/sdkThen connect, list the tools, and call one. This example authenticates with an API key in the X-API-Key header (see Authentication below for the other options):
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.
[
{
"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 or fetch it as machine-readable JSON from /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 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:
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.
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. 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.
npm install @anthropic-ai/sdkimport 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<string, unknown>,
});
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 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.
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/listadvertises only the everyday tools; call anything else by name. Consult /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
limitandoffset. - One request per POST. JSON-RPC batches are rejected with
400. The server accepts the2025-06-18and2025-03-26protocol versions in theMCP-Protocol-Versionheader. - Safe retries. Send an
Idempotency-Keyheader ontools/callso a retried write runs only once. - Browser origins. Requests with an
Originheader are accepted only from Claude, ActuallyCare, andlocalhostorigins; anything else gets403. 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.
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
writecan call every tool by name, including ones that are never offered to Claude. Some have real side effects and no confirmation step:send_review_requestemails a client, andwebsite_publishandlanding_page_publishmake 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.