honeybook-mcp

MCP server for HoneyBook's client portal — contracts, invoices, questionnaires, messages, meetings, tasks and payments across multiple wedding vendors, with magic-link session capture, in-portal messaging, and deep-link fallback for signing and paying.

Tools

• use_magic_link — Capture a portal session from a vendor magic-link URL (/app/link/resolve/…)
• use_flow_link — Capture a questionnaire credential from a flow link (/flow/<flowId>?hash=…)
• list_active_sessions — Show active credentials, split into portalSessions and flowCredentials
• get_flow(flow_id?, view?) — Read one questionnaire (flow) and its answers (two calls: public /minimal for the vendor company id, then /client/flow/<id>/active?ctxc=…)
• list_workspace_files — All files one vendor has shared (filter by type)
• get_workspace_file(file_id, section?) — Full detail for one file. Takes section, not view — see below
• get_workspace — Workspace detail + status flags
• list_payment_methods — Saved payment methods
• sign_contract — Deep link to sign in portal (asks the user to confirm first)
• pay_invoice — Deep link to pay in portal (asks the user to confirm first)
• list_projects — Your projects (HoneyBook "events") with a vendor, each with the workspace_id the tools below take
• get_project(project_id, view?) — Project details: date, time, location, guests, custom fields, people (name/email/phone/role)
• list_messages — Messages in a workspace (kind=activity for the activity log, kind=all for both): compact cards, newest first; never marks anything seen
• get_message — One message in full (format=text default, or html) with attachments and delivery status
• send_message — Send a new message (subject + body) or reply (reply_to_message_id, subject inherited) through the portal; asks the user to confirm first
• mark_messages_seen — Mark feed items seen, the way opening the Activity tab does
• list_meetings — Meetings the vendor scheduled (consultations, Zoom calls): time, join link, password; rescheduled meetings show their latest time
• list_tasks — Tasks assigned to you with today/this-week/overdue counts and task groups
• list_notes — Notes the vendor shared (meeting notes, AI recaps)
• list_attachments — Loose images, files and bookmarks (not contracts/invoices — those are workspace files)
• list_payments — Every payment on every file in a workspace, with paid/unpaid totals

Response shape (view)

Only two tools here take the fleet's view parameter: get_project and get_flow. Both honour compact | raw, and compact is the default — you get the cheap shape without asking for it. There is no full rung on either: raw already IS every field HoneyBook sent, so a third value would silently alias to one of the other two.

The two compact rungs are not the same kind of thing, and the difference decides which one you can trust to be complete:

• get_project compact is a field projection. It keeps _id, name, type, date/end_date, time_start/time_end, timezone, location, venue_name, guests, budget, details, project_dates, non-empty custom_fields, image_url, last_activity_date, and a de-duplicated people[] (_id, name, email, phone, role, job_title, company). Everything else is dropped — view: "raw" returns the untrimmed /details response, which embeds the vendor's entire account. Ask for it only when you need a field the list above does not name.
• get_flow compact is a byte ceiling, not a projection. No field is pruned. Under 200,000 bytes the questionnaire comes back whole and compact and raw differ only in indentation. Over it, compact replaces the flow with truncated: { bytes, limit, topLevelKeys, hint } — its own table of contents instead of its content. So on a large questionnaire the compact rung returns no questions at all; that is the signal to re-call with view: "raw". (A real /active payload measured 96,246 bytes, comfortably under the ceiling, so the ordinary case is the whole thing.)

get_workspace_file does not take view. It takes section — summary (default) | pricing | agreement | payments | all | raw — and that is a different question, deliberately kept. view asks how much of the whole record to keep; section asks which part of it to expand: line items and tax/svc detail (pricing), contract HTML and signatures (agreement), the full payment schedule (payments). all is the whole file with the vendor-side heavy fields pruned — vendor_emails alone measured ~1.3 MB on one real proposal — and raw keeps even those.

The surprise worth knowing: passing view: to get_workspace_file does not error. The unknown key is stripped during validation, the call succeeds, and you get the summary section — the default you would have got anyway. Nothing tells you the argument was ignored. Use the section name.

Every other tool has no shape parameter, for one of two reasons:

• Its output is already narrow, with no fatter rung to ask for. list_projects, list_messages, list_meetings, list_payments, list_tasks and list_active_sessions return hand-built rows rather than the upstream payload. list_messages in particular returns compact cards with a 240-character preview and no body — get_message is the way to the full text, not a view value.
• It does not return a record at all. sign_contract, pay_invoice, use_magic_link and use_flow_link answer with prose, a deep link, or a capture receipt.

One last mechanical note: raw comes back indented, while compact is minified. That is deliberate — raw is the rung a person reads when a payload is not what they expected, and indentation is most of what makes an unfamiliar shape legible.

Workflows

• First time → user pastes magic-link URL from vendor email → use_magic_link → session captured
• "Fill in / read the vendor's questionnaire" → user pastes the /flow/<id>?hash=… link → use_flow_link → get_flow
• "What contracts haven't I signed?" → list_workspace_files with file_type=agreement, filter by is_file_accepted=false
• "Summarize my HB status with Silk Veil" → get_workspace (status flags) + list_workspace_files
• "Send me a link to sign the photographer's contract" → list_workspace_files → sign_contract (confirm when prompted)
• "Which invoices are overdue?" → list_workspace_files with file_type=invoice, sort by due date
• "What did the planner send me?" / "Read me the latest checklist" → list_projects → list_messages → get_message
• "Reply to Ivy and ask about the rehearsal" → list_messages (find the message) → send_message with reply_to_message_id → show the user the preview → once they approve, re-run with the same arguments plus the returned confirmToken (on a client that shows a confirmation prompt, the prompt replaces these two steps, unless the server sets MCP_CONFIRM_ELICITATION=off)
• "When is my next Zoom with the planner?" → list_meetings; the join link and password are in the row
• "What have I paid and what's left?" → list_payments (totals.paid / totals.unpaid); to pay one, pay_invoice
• "Do I have anything to do?" → list_tasks (counts.overdue, counts.today)

Notes

• Each vendor = separate session keyed by portal origin (e.g. https://acme.hbportal.co)
• Sessions cached in ~/.honeybook-mcp/sessions.json (mode 0600)
• Two credential kinds, not interchangeable. A portal session reads workspaces/files/invoices; a flow credential is HoneyBook's "weak auth", scoped to ONE questionnaire, cached separately in ~/.honeybook-mcp/flows.json. A portal tool refuses a flow credential by name rather than failing upstream
• The flow storage key contains the flow id, so the ContextMint Bridge extension asks to re-approve the scope once per new questionnaire
• Write tools (sign_contract, pay_invoice) return deep links in v2
• Session expires → re-run use_magic_link with a fresh URL from the vendor's email
• send_message goes out as a real HoneyBook email to everyone in the workspace (the vendor and any co-clients). Always show the user the preview and get their explicit approval before passing the confirmToken back — never reuse or invent a token
• list_messages / get_message read the same feed the Activity tab renders and do not mark items seen; unseen_count counts messages from other people you have not opened