Connect Claude and Cursor to run AgencyHandy with MCP

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.

Open Workspace Config

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

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. Keys are JWTs; placeholders like test-key are rejected.

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.

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. The backend URL should be https (http is only allowed for localhost during local testing).

Restart and try a prompt

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:

{
  "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:

{
  "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:

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).”
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), set Industry to Agency software and Estimated budget to 12000.”
VIP client in	“Create client Ada Lovelace (ada@acme.com) and set VIP to true.”
Enrich existing	“On lead 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)

Ask for context on the task or ticket (include the order/project when you know it).
Claude reads assignment.assignmentCandidates and assignment.advice.
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

List definitions (ah_custom_field_list with type lead or client) — copy the real _id.
Fill values with ah_custom_field_set_values, or pass customFields when creating a lead/client.
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. 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.

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 on npm — use npx -y agencyhandy-mcp@1 (latest 1.7.2)
Lead Custom Fields · Client Custom Fields

Get Started

Workspace Setup

CRM

Services & Orders

Proposals & Invoices

Team & Tasks

Forms & Files

Account & Billing

Payments

Integrations

Connect Claude and Cursor to run AgencyHandy with MCP

Two ways to connect

Requirements

Set up Claude or Cursor MCP

Connect a cloud agent (hosted server)

Example prompts

Owner / money / pipeline

Delivery / assignment

CRM / custom fields / actions

Advanced context packs

API builder context (for custom MCP tools)

Owner insights (workspace)

Lead and client custom fields (MCP)

What works now vs not yet

​Two ways to connect

​Requirements

​Set up Claude or Cursor MCP

​Connect a cloud agent (hosted server)

​Example prompts

​Owner / money / pipeline

​Delivery / assignment

​CRM / custom fields / actions

​Advanced context packs

​API builder context (for custom MCP tools)

​Owner insights (workspace)

​Lead and client custom fields (MCP)

​When two people share a name

​What works now vs not yet

​Related

Two ways to connect

Requirements

Set up Claude or Cursor MCP

Connect a cloud agent (hosted server)

Example prompts

Owner / money / pipeline

Delivery / assignment

CRM / custom fields / actions

Advanced context packs

API builder context (for custom MCP tools)

Owner insights (workspace)

Lead and client custom fields (MCP)

When two people share a name

What works now vs not yet

Related