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

> Set up the AgencyHandy MCP package so you can ask Claude Desktop or Cursor to brief you, assign tickets, send invoices, and more — 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.

<Note>
  You need a role that can open **Workspace Config** and manage **API keys** (typically **SuperAdmin** or **Admin**). You also need **Node.js 20+** installed on the computer where Claude Desktop or Cursor runs.
</Note>

## Requirements

| Requirement                      | Details                                      |
| -------------------------------- | -------------------------------------------- |
| **Node.js**                      | Version **20** or newer (`node -v` to check) |
| **Claude Desktop** or **Cursor** | One of these apps installed on your computer |
| **AgencyHandy workspace**        | Access to **Workspace Config** → **API Key** |

The MCP package on npm is `agencyhandy-mcp`. Claude and Cursor run it with `npx -y agencyhandy-mcp@1`.

## Set up Claude or Cursor MCP

<Steps>
  <Step title="Open Workspace Config">
    In AgencyHandy, open **Workspace Config** (company settings), then go to the **API Key** tab.
  </Step>

  <Step title="Generate a workspace API key">
    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.
  </Step>

  <Step title="Copy the MCP config">
    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.
  </Step>

  <Step title="Paste into Cursor or Claude Desktop">
    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.
  </Step>

  <Step title="Restart and try a prompt">
    Fully quit and reopen **Cursor** or **Claude Desktop**. Then ask something simple, such as a morning briefing for your workspace.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Example prompts

Use natural language. Prefer full names or emails when you assign work so the right person is selected.

| Goal                      | Example prompt                                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Morning briefing**      | “Give me a morning briefing: open tickets, unpaid invoices, and proposals waiting on clients.”                              |
| **Assign a ticket**       | “Assign the ticket about the Acme homepage redesign to Jordan Lee ([jordan@agency.com](mailto:jordan@agency.com)).”         |
| **Send an invoice**       | “Send invoice INV-1042 to the client by email.”                                                                             |
| **Create a lead**         | “Create a lead for Nora Patel at Bright Studio, email [nora@brightstudio.com](mailto:nora@brightstudio.com).”               |
| **Lead + custom field**   | “Create a lead for Nora Patel ([nora@brightstudio.com](mailto:nora@brightstudio.com)) and set Industry to Agency software.” |
| **Client + custom field** | “Create client Ada Lovelace ([ada@acme.com](mailto:ada@acme.com)) and set VIP to true.”                                     |
| **Update a field value**  | “On lead [nora@brightstudio.com](mailto:nora@brightstudio.com), set Estimated budget to 12000.”                             |
| **Mark an invoice paid**  | “Mark invoice INV-1042 as paid.”                                                                                            |

## 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                                                               | Not available from MCP yet           |
| ----------------------------------------------------------------------- | ------------------------------------ |
| Briefings and lookups across proposals, projects, tickets, and invoices | Replying in **client chat** from MCP |
| Assign tickets and other team work                                      | —                                    |
| Create leads and clients                                                | —                                    |
| List, create, and fill **lead** / **client 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.

## Related

* Generate keys and copy config in-app under **Workspace Config** → **API Key**
* Package: [`agencyhandy-mcp`](https://www.npmjs.com/package/agencyhandy-mcp) on npm (`npx -y agencyhandy-mcp@1`)
* [Lead Custom Fields](/crm/lead-custom-fields) · [Client Custom Fields](/crm/client-custom-fields)