> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Claude and Cursor to run AgencyHandy with MCP
> Connect Claude, Cursor, or a cloud-hosted agent to AgencyHandy with MCP so it can brief you, assign work, investigate cash and delivery risk, and fill custom fields — in plain language.
AgencyHandy's MCP connection lets you talk to **Claude** or **Cursor** in plain language and have them run everyday work in your AgencyHandy workspace — without opening every screen yourself.
You stay in control. Claude and Cursor only act with the workspace API key you generate, and they ask you to confirm when a name matches more than one person.
## Two ways to connect
| Where your agent runs | How to connect | Setup |
| ----------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
| **On your computer** — Claude Desktop or Cursor | The `agencyhandy-mcp` package, started by the app | **Set up Claude or Cursor MCP**, below — needs Node.js 20+ |
| **In the cloud** — Cloudflare Workers, Vercel, n8n, a hosted Claude or Cursor | Our hosted MCP server at `https://mcp.agencyhandy.com/` | **Connect a cloud agent**, below — nothing to install |
Both use the same workspace API key and give the agent the same tools.
You need a role that can open **Workspace Config** and manage **API keys** (typically **SuperAdmin** or **Admin**). For the local setup you also need **Node.js 20+** on the machine where Claude Desktop or Cursor runs — the hosted server needs no install at all.
## Requirements
| Requirement | Details |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| **AgencyHandy workspace** | Access to **Workspace Config** → **API Key** |
| **An MCP host** | Claude Desktop or Cursor on your computer, or any agent that can call an MCP server over HTTP |
| **Node.js** *(local setup only)* | Version **20** or newer (`node -v` to check) |
| **MCP package** *(local setup only)* | `npx -y agencyhandy-mcp@1` (ships **1.7.2+** on the `1` tag) |
## Set up Claude or Cursor MCP
Use this when Claude Desktop or Cursor runs on your own computer. For an agent running in the cloud, skip ahead to **Connect a cloud agent**.
In AgencyHandy, open **Workspace Config** (company settings), then go to the **API Key** tab.
Create a new workspace API key (or use one you already saved). Copy the key when it appears — AgencyHandy cannot show the full key again later. Keys are **JWTs**; placeholders like `test-key` are rejected.
On the same **API Key** tab, use the Claude / Cursor MCP setup panel. Click **Copy MCP config** so the JSON includes your key and backend URL.
Paste the config into:
* **Cursor**: project or user `.mcp.json`
* **Claude Desktop**: `claude_desktop_config.json`
Keep the `npx -y agencyhandy-mcp@1` command and your API key as generated. The backend URL should be **https** (http is only allowed for localhost during local testing).
Fully quit and reopen **Cursor** or **Claude Desktop**. Then ask something simple, such as a Monday pulse or morning briefing for your workspace.
If Claude or Cursor cannot find the MCP server, confirm **Node.js 20+** is installed and that you restarted the app after saving the config. If the server exits immediately, check stderr for invalid URL/key messages — expired or placeholder keys fail fast.
## Connect a cloud agent (hosted server)
If your agent runs somewhere you cannot install a package — Cloudflare Workers, Vercel functions, n8n, or a hosted Claude or Cursor — point it at the MCP server we host for you:
```
https://mcp.agencyhandy.com/
```
There is nothing to install and no server to keep running. Authenticate every request with the same workspace API key as a bearer token. The workspace is read from the key, so each user connects with their own.
**Cursor, Claude Code, and any host that sends custom headers:**
```json theme={null}
{
"mcpServers": {
"agency-handy": {
"url": "https://mcp.agencyhandy.com/",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**Claude Desktop** cannot send custom headers, so bridge it with `mcp-remote`:
```json theme={null}
{
"mcpServers": {
"agency-handy": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.agencyhandy.com/",
"--header", "Authorization:Bearer YOUR_API_KEY"
]
}
}
}
```
**Claude Code** from the command line:
```bash theme={null}
claude mcp add agency-handy --transport http https://mcp.agencyhandy.com/ \
--header "Authorization: Bearer YOUR_API_KEY"
```
The address is the **root path** — `https://mcp.agencyhandy.com/`, not `/mcp`. To check the server is reachable, open `https://mcp.agencyhandy.com/health`.
Building your own integration against the HTTP API instead? Send a **`User-Agent`** header with your requests. Some runtimes — including Cloudflare Workers' `fetch()` — send none by default, and requests without one are rejected before they reach the API.
## Example prompts
Ask like an owner: **spot the risk → dig into the record → take the next action**. Prefer full names or emails when assigning so the right person is selected.
### Owner / money / pipeline
| Goal | Example prompt |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Monday pulse** | “What’s on fire this morning — cash overdue, proposals going cold, and work that’s slipping?” |
| **Cash concentration** | “Who are our top 5 clients by open AR, and how much of that is past 30 / 60 / 90 days? Flag anyone who also looks churny.” |
| **Collect next** | “Pick the single best invoice to chase today (biggest \$ at risk that isn’t brand new), open full context, then send it if it’s ready.” |
| **Proposal triage** | “Which proposals are stale or expiring soon? For the worst one, summarize comments and tell me if we’re waiting on them or us.” |
| **Pipeline hygiene** | “List proposals waiting on clients longer than two weeks — which ones should I bump this week vs write off?” |
| **Lead quality mix** | “Segment leads by source and by Industry. Where are we getting volume but not converting status?” |
| **Churn watchlist** | “Which clients look at risk — overdue invoices *and* quiet orders? Give me a short watchlist with why each scored high.” |
| **At-risk deep dive** | “Take the highest churn-risk client: open their latest order and unpaid invoices, then tell me the one action that would reduce risk this week.” |
### Delivery / assignment
| Goal | Example prompt |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Smart assign** | “On the Acme website order, find the stuck task, recommend who should own it from the order team (not the busiest), then assign them.” |
| **Ticket load balance** | “For the Acme homepage redesign ticket, who on the team has capacity vs already overloaded on this order — recommend and assign.” |
| **Named assign** | “Assign the Acme homepage redesign ticket to Jordan Lee ([jordan@agency.com](mailto:jordan@agency.com)).” |
| **Order health** | “Full context on the Acme website order: open tasks, tickets, files, related invoices — what’s blocking delivery vs billing?” |
| **Proposal readiness** | “Summarize the Bright Studio proposal: status, comments, linked service — are they ready to accept or stuck on a question?” |
| **Invoice story** | “Explain INV-1042 end-to-end: amounts, due aging, linked order, and other open invoices for that client — should I nudge or escalate?” |
### CRM / custom fields / actions
| Goal | Example prompt |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Qualified lead in** | “Create lead Nora Patel at Bright Studio ([nora@brightstudio.com](mailto:nora@brightstudio.com)), set Industry to Agency software and Estimated budget to 12000.” |
| **VIP client in** | “Create client Ada Lovelace ([ada@acme.com](mailto:ada@acme.com)) and set VIP to true.” |
| **Enrich existing** | “On lead [nora@brightstudio.com](mailto:nora@brightstudio.com), set Estimated budget to 12000 — use the existing field id, don’t create a duplicate.” |
| **Close the loop** | “Mark INV-1042 paid, then refresh cash risk so I can see if that client drops off the top AR list.” |
## Advanced context packs
Claude should prefer these **context** tools instead of calling many small lookups. They return a short **summary**, **guidance**, and related sources.
| Context pack | What you get | Best for |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **Task** (`ah_task_context`) | Task details, comments, time entries, current assignees, **ranked people to assign** (order team / PM + workload on that order), linked order | “Who should do this?” / stuck delivery work |
| **Ticket** (`ah_ticket_context`) | Same assignment help for tickets/issues | Support or client-facing issues |
| **Order / project** (`ah_order_context` / `ah_project_context`) | Order summary, tasks, tickets, files, related invoices & subscriptions, prefix settings | Delivery health for one engagement |
| **Proposal** (`ah_proposal_context`) | Commercial summary, comment thread, public view, linked service | Negotiation / accept readiness |
| **Invoice** (`ah_invoice_context`) | Billing summary, public view, linked order, related invoices for the same client | Cash / overdue / billing questions |
## API builder context (for custom MCP tools)
If you build your **own** MCP tools against the AgencyHandy HTTP API (or Claude reads workspace resources), prefer the built-in resource **`ah://api-context`** (also inside **`ah://full-context`**). It documents path renames and easy mistakes for:
| Area | What to remember |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Leads** | No `/leads` route — use `/members` + `bulk-lead` / `isConvertedClient=false`. Never call `PUT /accounts/update` without `accountId` (that updates the API-key owner). |
| **Projects** | UI project = API `/orders` (not `/projects`). |
| **Tasks / tickets** | Board tickets are tasks with `type=issue`. Status **ObjectId** on lists, **name** on updates. |
| **Comments** | Task comments = `/comments`; proposal comments = `/quotation-comments`. Use `agencyComment` vs `clientComment` for visibility. |
| **Labels** | Company labels use `create-for-company` / `suggest-by-company`. |
| **Clients** | Live path is `/members` (not stale `/company/.../members` docs). |
| **Invoices** | Named permissions (`getInvoice`, …); resend and public routes differ from status PUT. |
| **Vouchers / forms / webhooks** | Admin CRUD vs public apply/respond/event-id rules — see `ah://api-context`. |
Shipped in **`agencyhandy-mcp@1.7.2+`**.
**Assignment flow (tasks & tickets)**
1. Ask for context on the task or ticket (include the order/project when you know it).
2. Claude reads `assignment.assignmentCandidates` and `assignment.advice`.
3. It assigns with a real member id from that list (or resolves a name you gave — it will not invent ids).
Passing the **order / project id** makes assignee suggestions much stronger (order team + PM + how many open items they already own on that order).
## Owner insights (workspace)
These tools scan recent lists and return **heuristic** owner dashboards (not a full data warehouse). Always drill into a real id from the result. Shipped in **`agencyhandy-mcp@1.7+`** (current **1.7.2**).
| Insight | Tool | What you get |
| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
| **Cash / AR risk** | `ah_cash_risk` | Aging buckets (0–7 … 90+), total due, top clients by amount owed |
| **Proposal pipeline** | `ah_proposal_pipeline` | Waiting-on-client, stale sent, expiring soon |
| **Lead segmentation** | `ah_lead_segments` | Counts by status & source; optional breakout by a lead custom field name (e.g. Industry) |
| **Client churn risk** | `ah_client_churn_risk` | Scored clients from overdue invoices + quiet orders (heuristic) |
| **Morning snapshot** | `ah_dashboard_digest` | Open invoices, overdue work, new leads |
## Lead and client custom fields (MCP)
Custom fields are workspace definitions under **Workspace Config** → **Custom Fields**. Lead fields and client fields are **separate** lists.
**Typical flow**
1. List definitions (`ah_custom_field_list` with type `lead` or `client`) — copy the real `_id`.
2. Fill values with `ah_custom_field_set_values`, or pass `customFields` when creating a lead/client.
3. To change a value later, load the person with `ah_member_custom_fields` and prefer an existing filled-value id when one is returned.
**Duplicate definitions**
* Within **leads**, names must be unique (case and spacing ignored). Creating `Industry` again returns **Field already exists** and does not add a second lead field.
* Within **clients**, the same rule applies.
* The same display name **can** exist once on leads **and** once on clients — different owners, different ids. Always pick the id for the owner you mean (`lead` vs `client`).
Never invent field ids. If a create is rejected as a duplicate, list fields and reuse the existing id.
## When two people share a name
If two teammates are both named Sara, Claude will ask which one you mean. It does **not** invent IDs or guess silently.
Always include a **full name** or **email** in the prompt when names might collide.
## What works now vs not yet
| Works now (`agencyhandy-mcp@1.7.2+`) | Not available from MCP yet |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Morning briefings and deep lookups (proposal, order, task, ticket, invoice context packs) | Replying in **client chat** from MCP |
| **Recommend who to assign** on tasks/tickets (ranked candidates + workload), then assign | Full BI / warehouse-grade reporting |
| **Cash risk**, **proposal pipeline aging**, **lead segments**, **client churn heuristics** | — |
| **API builder context** (`ah://api-context`) for leads, orders, tasks, comments, labels, clients, invoices, vouchers, forms | — |
| Investigate orders / proposals / invoices with linked records | — |
| Create leads and clients; list/create/fill **custom fields** | — |
| Send invoices and mark invoices paid | — |
MCP supports both reading your workspace and taking actions (create, assign, send, update) with your API key. Client chat replies are not exposed through MCP yet. Owner insights are sample-based heuristics — confirm before big decisions.
## Related
* Generate keys and copy config in-app under **Workspace Config** → **API Key**
* Hosted server for cloud agents: `https://mcp.agencyhandy.com/` (health check at `/health`)
* Package: [`agencyhandy-mcp`](https://www.npmjs.com/package/agencyhandy-mcp) on npm — use `npx -y agencyhandy-mcp@1` (latest **1.7.2**)
* [Lead Custom Fields](/crm/lead-custom-fields) · [Client Custom Fields](/crm/client-custom-fields)