Show API Menu

AI Assistants

Clientary works with AI assistants through an MCP server. An assistant is given the server address, sends the person to sign in and approve the connection through OAuth, and then works in the account as that person, with exactly their permissions. Every tool below runs through this API.

https://www.clientary.com/mcp

Setup steps for Claude, ChatGPT, Claude Code, and Gemini CLI are in the help article. The server answers initialize, ping, and tools/list to anyone, so a client can read the catalog before a person signs in. Every other message needs the person's token.

A tool marked read-only changes nothing. A tool marked destructive sends something to a client or deletes something, and an assistant confirms with the person before running one. Creating a document makes a draft. Sending it is its own tool.

Clients

list_clients read-only

Find clients by name or number, or list them. Returns one page at a time; use the page number for more. Archived clients are excluded unless asked for.

  • query string — Part of a client name or number to search for
  • filter string: archived — Pass "archived" to list archived clients instead of active ones
  • page integer
get_client read-only

The full record of one client, including its contacts.

  • id integer, required
create_client

Add a new client. Only the name is required.

  • name string, required — Client name (a company or a person)
  • number string — Client number or code, as the account numbers its clients
  • address string
  • address_2 string
  • city string
  • state string
  • zip string
  • country string
  • tax_id string
  • website string
  • description string — Notes about the client, visible to staff
  • note string — A note that prints on the client's invoices
  • status string: active, archived — Archived clients are hidden from lists
update_client

Change fields on an existing client. Only the fields given are changed.

  • id integer, required
  • name string — Client name (a company or a person)
  • number string — Client number or code, as the account numbers its clients
  • address string
  • address_2 string
  • city string
  • state string
  • zip string
  • country string
  • tax_id string
  • website string
  • description string — Notes about the client, visible to staff
  • note string — A note that prints on the client's invoices
  • status string: active, archived — Archived clients are hidden from lists
delete_client destructive

Permanently delete a client and everything attached to it. Prefer archiving (update status to "archived") unless the person clearly wants deletion.

  • id integer, required

Leads

list_leads read-only

Search or list leads. Open leads by default; pass a filter for closed (won), lost, or all.

  • query string — Part of a lead name to search for
  • filter string: closed, lost, all
  • sort string: name, oldest — Default is newest first
  • page integer
get_lead read-only

The full record of one lead, including its contacts.

  • id integer, required
create_lead

Add a new lead. Only the name is required.

  • name string, required — Lead name (a company or a person)
  • number string
  • address string
  • address_2 string
  • city string
  • state string
  • zip string
  • country string
  • website string
  • description string — Notes about the lead
  • lead_value number — Expected value of the deal, in the account currency
  • lead_origin string — Where the lead came from, e.g. "Referral" or "Website"
  • assignee_id integer — Staff user id the lead is assigned to
  • status string: lead, won, lost — Marking a lead won converts it to a client
  • lost_reason_str string — Why the lead was lost, when marking it lost
update_lead

Change fields on a lead, including marking it won or lost. Only the fields given are changed.

  • id integer, required
  • name string — Lead name (a company or a person)
  • number string
  • address string
  • address_2 string
  • city string
  • state string
  • zip string
  • country string
  • website string
  • description string — Notes about the lead
  • lead_value number — Expected value of the deal, in the account currency
  • lead_origin string — Where the lead came from, e.g. "Referral" or "Website"
  • assignee_id integer — Staff user id the lead is assigned to
  • status string: lead, won, lost — Marking a lead won converts it to a client
  • lost_reason_str string — Why the lead was lost, when marking it lost
delete_lead destructive

Permanently delete a lead. Prefer marking it lost unless the person clearly wants deletion.

  • id integer, required

Invoices

list_invoices read-only

Search or list invoices, optionally for one client or project, or by status. Overdue means open and past due. Returns one page at a time.

  • query string — Part of an invoice number, title, or client name
  • client_id integer
  • project_id integer
  • status string: draft, open, overdue, paid, pending, cancelled
  • from_date string — YYYY-MM-DD, by document date
  • to_date string — YYYY-MM-DD, by document date
  • page integer
get_invoice read-only

One invoice with its line items, totals, and payment state.

  • id integer, required
create_invoice

Create a draft invoice for a client with line items. Nothing is sent; use send_invoice afterwards, after the person confirms.

  • items array, required — The line items
  • client_id integer, required — The client being billed
  • title string — A title shown on the invoice
  • number string — Only when the person gives a specific invoice number ("issue invoice #123456"). Otherwise leave it out: the account assigns its next number, and a made-up one breaks the sequence
  • date string — Invoice date, YYYY-MM-DD; defaults to today
  • due_date string — Due date, YYYY-MM-DD
  • currency_code string — ISO currency code, e.g. USD; defaults to the account currency
  • po string — The client's purchase order number
  • summary string — A summary shown above the line items
  • note string — A note shown below the line items
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, paid, cancelled — Set directly only to record a state; use send_invoice to actually send
  • associated_contract_id integer — The signed proposal or contract this invoice fulfils. Links the two so the proposal shows as invoiced. Only a signed one, and only once
update_invoice

Change fields on an invoice. Items given are added to the invoice; existing items are kept.

  • id integer, required
  • items array — Line items to add
  • client_id integer — The client being billed
  • title string — A title shown on the invoice
  • number string — Only when the person gives a specific invoice number ("issue invoice #123456"). Otherwise leave it out: the account assigns its next number, and a made-up one breaks the sequence
  • date string — Invoice date, YYYY-MM-DD; defaults to today
  • due_date string — Due date, YYYY-MM-DD
  • currency_code string — ISO currency code, e.g. USD; defaults to the account currency
  • po string — The client's purchase order number
  • summary string — A summary shown above the line items
  • note string — A note shown below the line items
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, paid, cancelled — Set directly only to record a state; use send_invoice to actually send
  • associated_contract_id integer — The signed proposal or contract this invoice fulfils. Links the two so the proposal shows as invoiced. Only a signed one, and only once
delete_invoice destructive

Permanently delete an invoice. Prefer cancelling (update status to "cancelled") for anything a client has seen.

  • id integer, required
send_invoice destructive

Email an invoice to the client, with the PDF attached. Recipients default to the client's contacts when omitted. Confirm with the person before sending.

  • id integer, required
  • recipients array — Email addresses; the client's contacts when omitted
  • subject string — Defaults to the account's standard subject
  • message string — Defaults to the account's standard message

Retainers

list_retainers read-only

List retainer invoices, optionally for one client or by status. Also returns what each client has left on account. Returns one page at a time.

  • client_id integer
  • status string: draft, open, paid, pending, cancelled
  • from_date string — YYYY-MM-DD, by document date
  • to_date string — YYYY-MM-DD, by document date
  • page integer
get_retainer read-only

One retainer with its line items, totals, and payments.

  • id integer, required
create_retainer

Ask a client to pay a retainer up front, by creating a retainer invoice. Nothing is sent, and nothing reaches their balance until they pay it. A retainer cannot be attached to an estimate or a project.

  • items array, required — The line items
  • client_id integer, required — The client being asked for the retainer
  • title string
  • number string — Only when the person gives a specific number. Otherwise leave it out: the account assigns its next number
  • date string — Retainer date, YYYY-MM-DD; defaults to today
  • due_date string — Due date, YYYY-MM-DD; defaults to the account setting
  • currency_code string — ISO currency code; defaults to the account currency
  • po string
  • summary string
  • note string
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, paid, cancelled — Set directly only to record a state
update_retainer

Change a retainer's fields.

  • id integer, required
  • client_id integer — The client being asked for the retainer
  • title string
  • number string — Only when the person gives a specific number. Otherwise leave it out: the account assigns its next number
  • date string — Retainer date, YYYY-MM-DD; defaults to today
  • due_date string — Due date, YYYY-MM-DD; defaults to the account setting
  • currency_code string — ISO currency code; defaults to the account currency
  • po string
  • summary string
  • note string
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, paid, cancelled — Set directly only to record a state
delete_retainer destructive

Delete a retainer.

  • id integer, required
send_retainer destructive

Email a retainer to the client to pay, with the PDF attached. Recipients default to the client's contacts when omitted. Confirm with the person before sending.

  • id integer, required
  • recipients array — Email addresses; the client's contacts when omitted
  • subject string
  • message string

Estimates

list_estimates read-only

Search or list estimates, optionally for one client or project, or by status. Returns one page at a time.

  • query string — Part of an estimate number, title, or client name
  • client_id integer
  • project_id integer
  • status string: draft, open, accepted, declined, expired, archived
  • from_date string — YYYY-MM-DD, by document date
  • to_date string — YYYY-MM-DD, by document date
  • page integer
get_estimate read-only

One estimate with its line items and totals.

  • id integer, required
create_estimate

Create a draft estimate for a client with line items. Nothing is sent; use send_estimate afterwards, after the person confirms.

  • items array, required — The line items
  • client_id integer, required — The client the estimate is for
  • title string
  • number string — Only when the person gives a specific estimate number. Otherwise leave it out: the account assigns its next number, and a made-up one breaks the sequence
  • date string — Estimate date, YYYY-MM-DD; defaults to today
  • expiration_date string — When the estimate expires, YYYY-MM-DD
  • delivery_date string — When the work would be delivered, YYYY-MM-DD
  • currency_code string — ISO currency code; defaults to the account currency
  • po string
  • note string — A note shown below the line items
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, accepted, declined, archived — Set directly only to record a state; use send_estimate to actually send
update_estimate

Change fields on an estimate. Items given are added; existing items are kept.

  • id integer, required
  • items array — Line items to add
  • client_id integer — The client the estimate is for
  • title string
  • number string — Only when the person gives a specific estimate number. Otherwise leave it out: the account assigns its next number, and a made-up one breaks the sequence
  • date string — Estimate date, YYYY-MM-DD; defaults to today
  • expiration_date string — When the estimate expires, YYYY-MM-DD
  • delivery_date string — When the work would be delivered, YYYY-MM-DD
  • currency_code string — ISO currency code; defaults to the account currency
  • po string
  • note string — A note shown below the line items
  • tax number — Tax rate as a percentage
  • tax_label string
  • status string: draft, accepted, declined, archived — Set directly only to record a state; use send_estimate to actually send
delete_estimate destructive

Permanently delete an estimate. Prefer archiving (update status to "archived") for anything a client has seen.

  • id integer, required
send_estimate destructive

Email an estimate to the client, with the PDF attached. Recipients default to the client's contacts when omitted. Confirm with the person before sending.

  • id integer, required
  • recipients array
  • subject string
  • message string

Projects

list_projects read-only

Search or list projects, optionally for one client. Active projects by default; pass a filter for closed, billable, unbilled, over-budget, or all.

  • query string — Part of a project name
  • client_id integer
  • filter string: all, closed, billable, unbilled, overbudget
  • page integer
get_project read-only

One project.

  • id integer, required
create_project

Create a project for a client, optionally from one of the account's project templates, which brings its phases and tasks. Name and client are required.

  • template_id integer — A project template to start from
  • client_id integer, required
  • name string, required
  • number string
  • description string
  • note string
  • status string: active, completed — Completed projects are closed
  • project_type string: hourly, flat_rate — How the project is billed
  • rate number — Hourly rate; defaults to the person's own hourly rate, or 0
  • currency_code string
  • budget_enabled boolean
  • budget_type string: hours, cost — Whether the budget is in hours or in money; a flat-rate project budgets in hours
  • budget number
  • end_date string — Target end date, YYYY-MM-DD
  • client_visible boolean — Whether the client can see the project in their portal
update_project

Change fields on a project, including closing it. Only the fields given are changed.

  • id integer, required
  • client_id integer
  • name string
  • number string
  • description string
  • note string
  • status string: active, completed — Completed projects are closed
  • project_type string: hourly, flat_rate — How the project is billed
  • rate number — Hourly rate; defaults to the person's own hourly rate, or 0
  • currency_code string
  • budget_enabled boolean
  • budget_type string: hours, cost — Whether the budget is in hours or in money; a flat-rate project budgets in hours
  • budget number
  • end_date string — Target end date, YYYY-MM-DD
  • client_visible boolean — Whether the client can see the project in their portal
delete_project destructive

Permanently delete a project with its tasks and time. Prefer completing it unless the person clearly wants deletion.

  • id integer, required
list_project_templates read-only

The account's project templates, each with the phases and tasks a project made from it starts with.

  • query string
get_project_template read-only

One project template with its phases and tasks by name.

  • id integer, required

Tasks

list_tasks read-only

List tasks, optionally for one project or client, open or done. Returns one page at a time.

  • project_id integer
  • client_id integer
  • status string: open, done
  • page integer
get_task read-only

One task.

  • id integer, required
create_task

Add a task to a project. Title and project are required.

  • project_id integer, required
  • title string, required
  • description string
  • due_date string — YYYY-MM-DD
  • assignee_id integer — Staff user id the task is assigned to
  • complete boolean — Mark done or reopen
  • budget_type string: hours, cost — Whether the budget is in hours or in money
  • budget number
update_task

Change a task, including marking it done. Only the fields given are changed.

  • id integer, required
  • project_id integer
  • title string
  • description string
  • due_date string — YYYY-MM-DD
  • assignee_id integer — Staff user id the task is assigned to
  • complete boolean — Mark done or reopen
  • budget_type string: hours, cost — Whether the budget is in hours or in money
  • budget number
delete_task destructive

Permanently delete a task.

  • id integer, required

Time Entries

list_time_entries read-only

List the time logged on one project, all of it or only billed or unbilled.

  • project_id integer, required
  • filter string: billed, unbilled
get_time_entry read-only

One time entry.

  • id integer, required
log_time

Log hours on a project for the person, dated today unless told otherwise.

  • project_id integer, required
  • hours number, required — Hours worked, decimal (1.5 is an hour and a half)
  • completion_date string — The day the work was done, YYYY-MM-DD; defaults to today
  • title string — What the time was for
  • description string
  • billable boolean — Defaults to the project's setting
update_time_entry

Change a time entry. Only the fields given are changed.

  • id integer, required
  • project_id integer
  • hours number — Hours worked, decimal (1.5 is an hour and a half)
  • completion_date string — The day the work was done, YYYY-MM-DD; defaults to today
  • title string — What the time was for
  • description string
  • billable boolean — Defaults to the project's setting
delete_time_entry destructive

Permanently delete a time entry.

  • id integer, required

Contracts

list_contracts read-only

List the account's contracts (not templates), optionally by status or date. Returns one page at a time.

  • status string: draft, sent, viewed, signed, voided
  • from_date string — YYYY-MM-DD, by document date
  • to_date string — YYYY-MM-DD, by document date
  • page integer
get_contract read-only

One contract with its sections as readable text.

  • id integer, required
create_contract

Create a draft contract for a client, from one of the account's templates or from plain-text sections. Nothing is sent to the client. Prefer a template when one fits: it carries the account's own wording. Write sections yourself only when the person has given you the terms; otherwise ask.

  • template_id integer — A contract template to start from; its sections and title are used unless sections or a subject are given
  • sections array — Required when no template is given
  • client_id integer, required
  • subject string — The document title
  • date string — YYYY-MM-DD; defaults to today
  • project_id integer
  • status string: draft, declined — Record that the client declined, or return a draft. Sending and signing set the other states
  • settings_auto_create_invoice_after_sign boolean — When the client signs, an invoice for what they chose is created and sent to them without anyone doing it by hand
update_contract

Change a contract's title, date, client, project, or status. Sections given replace all existing sections; omit them to leave the text alone.

  • id integer, required
  • sections array
  • client_id integer
  • subject string — The document title
  • date string — YYYY-MM-DD; defaults to today
  • project_id integer
  • status string: draft, declined — Record that the client declined, or return a draft. Sending and signing set the other states
  • settings_auto_create_invoice_after_sign boolean — When the client signs, an invoice for what they chose is created and sent to them without anyone doing it by hand
delete_contract destructive

Permanently delete a contract. Prefer declining or leaving it for anything the client has seen.

  • id integer, required
send_contract destructive

Email a contract to the client, with a link to read and sign it and the PDF attached. Recipients default to the client's contacts when omitted. Confirm with the person before sending.

  • id integer, required
  • recipients array — Email addresses; the client's contacts when omitted
  • subject string — Defaults to the account's standard subject
  • message string — Defaults to the account's standard message
list_contract_templates read-only

The account's contract templates, with the built-in ones, by name and description. Make a contract from one with create_contract and its template_id.

get_contract_template read-only

One contract template with its sections as readable text.

  • id integer, required — Negative for a built-in template

Proposals

list_proposals read-only

List the account's proposals (not templates), optionally by status or date. Returns one page at a time.

  • status string: draft, sent, viewed, signed, voided
  • from_date string — YYYY-MM-DD, by document date
  • to_date string — YYYY-MM-DD, by document date
  • page integer
get_proposal read-only

One proposal with its sections as readable text.

  • id integer, required
create_proposal

Create a draft proposal for a client, from one of the account's templates or from plain-text sections. Nothing is sent to the client. Prefer a template when one fits: it carries the account's own wording. Write sections yourself only when the person has given you the terms; otherwise ask.

  • template_id integer — A proposal template to start from; its sections and title are used unless sections or a subject are given
  • sections array — Required when no template is given
  • client_id integer, required
  • subject string — The document title
  • date string — YYYY-MM-DD; defaults to today
  • project_id integer
  • status string: draft, declined — Record that the client declined, or return a draft. Sending and signing set the other states
  • settings_auto_create_invoice_after_sign boolean — When the client signs, an invoice for what they chose is created and sent to them without anyone doing it by hand
update_proposal

Change a proposal's title, date, client, project, or status. Sections given replace all existing sections; omit them to leave the text alone.

  • id integer, required
  • sections array
  • client_id integer
  • subject string — The document title
  • date string — YYYY-MM-DD; defaults to today
  • project_id integer
  • status string: draft, declined — Record that the client declined, or return a draft. Sending and signing set the other states
  • settings_auto_create_invoice_after_sign boolean — When the client signs, an invoice for what they chose is created and sent to them without anyone doing it by hand
delete_proposal destructive

Permanently delete a proposal. Prefer declining or leaving it for anything the client has seen.

  • id integer, required
send_proposal destructive

Email a proposal to the client, with a link to read and sign it and the PDF attached. Recipients default to the client's contacts when omitted. Confirm with the person before sending.

  • id integer, required
  • recipients array — Email addresses; the client's contacts when omitted
  • subject string — Defaults to the account's standard subject
  • message string — Defaults to the account's standard message
list_proposal_templates read-only

The account's proposal templates, with the built-in ones, by name and description. Make a proposal from one with create_proposal and its template_id.

get_proposal_template read-only

One proposal template with its sections as readable text.

  • id integer, required — Negative for a built-in template

Recurring Schedules

list_recurring_schedules read-only

List recurring invoice schedules, optionally for one client or by status.

  • client_id integer
  • status string: active, paused, finished, archived
  • query string
  • page integer
get_recurring_schedule read-only

One recurring schedule with its line items.

  • id integer, required
create_recurring_schedule destructive

Start a recurring invoice schedule for a client: line items, a cadence, and a first date. Each invoice is drafted for review unless the action says otherwise. When the person asks for a retainer, set retainer. Confirm the cadence and amount with the person first.

  • items array, required
  • client_id integer, required
  • title string
  • time_interval string, required: weekly, biweekly, semimonthly, monthly, bimonthly, quarterly, semiannually, annually — How often an invoice is issued
  • next_date string, required — When the next invoice is issued, YYYY-MM-DD
  • action string: draft, send, autobill — What happens on each date: draft the invoice for review (default), send it to the client, or charge the client's card on file
  • occurrences integer — How many invoices remain; omit for an open-ended schedule
  • due_period integer — Days until each invoice is due; defaults to the account setting
  • currency_code string
  • po string
  • summary string
  • note string
  • tax number — Tax rate as a percentage
  • tax_label string
  • retainer boolean — Each occurrence issues a retainer invoice asking the client to top up their balance, rather than an ordinary invoice for work done
  • retainer_threshold number — The retainer balance below which the client is asked to top up
  • use_retainer_balance boolean — Each occurrence draws against the client's existing retainer balance instead of charging them. Needs the autobill action, and cannot be combined with retainer
update_recurring_schedule

Change a schedule's cadence, next date, action, remaining occurrences, or fields. Items given are added. Use pause or resume to stop and restart it.

  • id integer, required
  • items array
  • status string: active, paused — Pause or resume the schedule
  • client_id integer
  • title string
  • time_interval string: weekly, biweekly, semimonthly, monthly, bimonthly, quarterly, semiannually, annually — How often an invoice is issued
  • next_date string — When the next invoice is issued, YYYY-MM-DD
  • action string: draft, send, autobill — What happens on each date: draft the invoice for review (default), send it to the client, or charge the client's card on file
  • occurrences integer — How many invoices remain; omit for an open-ended schedule
  • due_period integer — Days until each invoice is due; defaults to the account setting
  • currency_code string
  • po string
  • summary string
  • note string
  • tax number — Tax rate as a percentage
  • tax_label string
  • retainer boolean — Each occurrence issues a retainer invoice asking the client to top up their balance, rather than an ordinary invoice for work done
  • retainer_threshold number — The retainer balance below which the client is asked to top up
  • use_retainer_balance boolean — Each occurrence draws against the client's existing retainer balance instead of charging them. Needs the autobill action, and cannot be combined with retainer
delete_recurring_schedule destructive

Permanently delete a recurring schedule. Prefer pausing it.

  • id integer, required

Recurring Time

list_recurring_time read-only

List recurring time entries, optionally by status.

  • status string: active, paused, stopped, archived
  • page integer
get_recurring_time read-only

One recurring time entry.

  • id integer, required
create_recurring_time destructive

Log hours on a project automatically on a cadence, starting on a date. Confirm the cadence and hours with the person first.

  • project_id integer, required — The project the time is logged on
  • title string, required — What the time is for
  • description string
  • hours number, required — Hours logged each time
  • time_interval string, required: daily, workdays, weekly, biweekly, monthly
  • next_date string, required — The first date to log, YYYY-MM-DD
  • occurrences integer — How many times to log; omit for open-ended
  • billable boolean
  • user_id integer — Staff user the time is logged for; defaults to the person
update_recurring_time

Change a recurring time entry. Only the fields given are changed.

  • id integer, required
  • project_id integer — The project the time is logged on
  • title string — What the time is for
  • description string
  • hours number — Hours logged each time
  • time_interval string: daily, workdays, weekly, biweekly, monthly
  • next_date string — The first date to log, YYYY-MM-DD
  • occurrences integer — How many times to log; omit for open-ended
  • billable boolean
  • user_id integer — Staff user the time is logged for; defaults to the person
pause_recurring_time

Pause a recurring time entry; nothing is logged until it is resumed.

  • id integer, required
resume_recurring_time

Resume a paused recurring time entry.

  • id integer, required
archive_recurring_time destructive

Stop a recurring time entry for good and hide it from lists. Past entries stay.

  • id integer, required

Comments

list_comments read-only

The comments on one invoice, estimate, project, task, proposal, or contract, newest first.

  • on string, required: invoice, estimate, project, task, proposal, contract — What kind of record
  • id integer, required — That record's id
add_comment

Post a comment on a record. Clients with portal access see it unless staff_only is set. The people involved are notified as they would be for a comment made in the app.

  • on string, required: invoice, estimate, project, task, proposal, contract
  • id integer, required
  • body string, required
  • staff_only boolean — Hide from client contacts
update_comment

Edit a comment the person wrote.

  • id integer, required
  • body string, required
delete_comment destructive

Delete a comment the person wrote.

  • id integer, required

Reports

report_summary read-only

Totals for a date range: invoiced (by invoice date, drafts and cancellations excluded), paid (by the day payment arrived), outstanding balances split into current and overdue as of today, estimates issued and accepted, proposals sent and signed with the value of what signed clients chose, retainer money deposited and drawn with what clients have left on account, and hours logged (total and billable). Money figures are keyed by currency code with a total and count each, since amounts in different currencies don't add. Dates are inclusive calendar dates in the account's bookkeeping; work out the range from the person's own calendar and pass it. Defaults to this month. Use this for how much or how many; use the list tools for which ones.

  • from_date string — YYYY-MM-DD
  • to_date string — YYYY-MM-DD
  • client_id integer — Narrow to one client