Skip to main content
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.
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.

​
Requirements

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

1

Open Workspace Config

In AgencyHandy, open Workspace Config (company settings), then go to the API Key tab.
2

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

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

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

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

​
Example prompts

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

​
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

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.