# Harvest — how to use (mcp.ai)

Harvest is a time-tracking and invoicing tool designed for teams and freelancers, helping them log billable hours, manage projects, and streamline payments

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_harvest?ms=1781542920000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `harvest_create_client`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/harvest`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/harvest/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/harvest/create/client` — Tool to create a new client. use after gathering client details to register a new client in harvest.
  - body: { name: string, address?: string, currency?: string, is_active?: boolean }
- `POST https://api.mcp.ai/api/harvest/create/client/contact` — Tool to create a new client contact. use when you need to add a contact under an existing client. call after you've retrieved or confirmed the client id.
  - body: { fax?: string, email?: string, title?: string, client_id: integer, last_name?: string, first_name: string, phone_mobile?: string, phone_office?: string }
- `POST https://api.mcp.ai/api/harvest/create/estimate` — Tool to create a new estimate. use after gathering client and line item details.
  - body: { tax?: number, tax2?: number, notes?: string, number?: string, subject?: string, currency?: string, discount?: number, client_id: integer, issue_date?: string, line_items?: object[], purchase_order?: string }
- `POST https://api.mcp.ai/api/harvest/create/estimate/item/category` — Tool to create a new estimate item category in harvest. use after deciding to categorize line items within an estimate.
  - body: { name: string }
- `POST https://api.mcp.ai/api/harvest/create/estimate/message` — Tool to create a new message for an estimate. use when you have an estimate id and want to send a message or run an event (send, accept, decline, re-open) on the estimate.
  - body: { body?: string, subject?: string, event_type?: string, recipients?: object[], estimate_id: integer, send_me_a_copy?: boolean }
- `POST https://api.mcp.ai/api/harvest/create/expense` — Tool to create a new expense entry. use when recording costs against projects. ensure either units or total cost is provided.
  - body: { notes?: string, units?: number, receipt?: string, user_id?: integer, billable?: boolean, project_id: integer, spent_date: string, total_cost?: number, expense_category_id: integer }
- `POST https://api.mcp.ai/api/harvest/create/invoice` — Tool to create a new invoice. use when you have gathered all invoice details and need to bill a client in harvest.
  - body: { tax?: number, tax2?: number, notes?: string, state?: string, number?: string, subject?: string, currency?: string, discount?: number, due_date?: string, client_id: integer, issue_date?: string, line_items: object[], purchase_order?: string }
- `POST https://api.mcp.ai/api/harvest/create/invoice/item/category` — Tool to create a new invoice item category. use after you have decided on the category name to register it in harvest.
  - body: { name: string }
- `POST https://api.mcp.ai/api/harvest/create/invoice/message` — Tool to create a new message for an invoice. use after confirming the invoice id when you need to notify a client with invoice details.
  - body: { body?: string, subject?: string, thank_you?: boolean, attach_pdf?: boolean, event_type?: string, invoice_id: integer, recipients?: object[], send_me_a_copy?: boolean, include_link_to_client_invoice?: boolean }
- `POST https://api.mcp.ai/api/harvest/create/invoice/payment` — Tool to create a new payment on an invoice. use when recording a payment against an existing invoice.
  - body: { notes?: string, amount: number, paid_at?: string, paid_date?: string, invoice_id: integer, send_thank_you?: boolean }
- `POST https://api.mcp.ai/api/harvest/create/project` — Tool to create a new project. use after confirming the client exists.
  - body: { fee?: number, code?: string, name: string, notes?: string, budget?: number, bill_by?: string, ends_on?: string, budget_by?: string, client_id: integer, is_active?: boolean, starts_on?: string, cost_budget?: number, hourly_rate?: number, is_billable?: boolean, is_fixed_fee?: boolean, budget_is_monthly?: boolean, show_budget_to_all?: boolean, notify_when_over_budget?: boolean, cost_budget_include_expenses?: boolean, over_budget_notification_percentage?: number }
- `POST https://api.mcp.ai/api/harvest/create/task` — Tool to create a new task. use after identifying task details to register it in harvest.
  - body: { name: string, is_active?: boolean, is_default?: boolean, billable_by_default?: boolean, default_hourly_rate?: number }
- `POST https://api.mcp.ai/api/harvest/create/time/entry` — Tool to create a new time entry. use when logging hours for a project by specifying start/end times or duration.
  - body: { hours?: number, notes?: string, task_id: integer, user_id?: integer, ended_time?: string, project_id: integer, spent_date: string, started_time?: string, external_reference?: object }
- `POST https://api.mcp.ai/api/harvest/create/user` — Tool to create a new user. use after gathering user details to invite them to harvest.
  - body: { email: string, roles?: string[], timezone?: string, cost_rate?: number, is_active?: boolean, last_name: string, first_name: string, access_roles?: string[], is_contractor?: boolean, weekly_capacity?: integer, default_hourly_rate?: number, has_access_to_all_future_projects?: boolean }
- `POST https://api.mcp.ai/api/harvest/delete/client` — Tool to delete a client. use when you need to remove a client that has no associated projects, invoices, or estimates. call after confirming the client id exists and has no dependent resources.
  - body: { client_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/client/contact` — Tool to delete a client contact. use when you need to remove a contact that is no longer relevant. call after confirming the contact id exists.
  - body: { contact_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/estimate` — Tool to delete an estimate. use when you need to remove an estimate that is no longer needed. call after confirming the estimate id exists and has no dependent resources.
  - body: { estimate_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/estimate/message` — Tool to delete an estimate message. use when you need to remove a message from an estimate. call after confirming estimate id and message id are correct.
  - body: { message_id: integer, estimate_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/invoice` — Tool to delete an invoice. use when you need to remove an invoice that has no associated payments. call after confirming the invoice id exists.
  - body: { invoice_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/invoice/item/category` — Tool to delete an invoice item category. use when you need to remove an obsolete or incorrect invoice item category. call after confirming the invoice item category id exists.
  - body: { invoice_item_category_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/invoice/message` — Tool to delete a message from an invoice. use when you need to remove a specific message that is no longer relevant. call after confirming the invoice id and message id.
  - body: { invoice_id: integer, message_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/invoice/payment` — Tool to delete an invoice payment. use when you need to remove a payment from an invoice after confirming payment details.
  - body: { invoice_id: integer, payment_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/project` — Tool to delete a project. use when you need to remove a project and all its associated time entries and expenses; invoices remain intact. call after confirming the project id exists.
  - body: { project_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/task` — Tool to delete a task. use when you need to remove a task that has no associated time entries. call after confirming the task id exists and has no dependent time entries.
  - body: { task_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/time/entry` — Tool to delete a time entry. use when removing an existing time entry that is deletable (not closed or on archived projects/tasks). call after confirming the time entry id exists.
  - body: { time_entry_id: integer }
- `POST https://api.mcp.ai/api/harvest/delete/user` — Tool to delete a user. use when you need to remove a user that has no associated time entries or expenses. call after confirming the user id exists and has no dependent time entries or expenses.
  - body: { user_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/client` — Tool to retrieve a specific client by id. use when you need details of a client before invoicing or reporting.
  - body: { client_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/client/contact` — Tool to retrieve a specific client contact. use when you have client id and contact id to fetch and verify contact details.
  - body: { client_id: integer, contact_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/company/info` — Tool to retrieve information about the authenticated user's company. use after authentication to fetch company settings for display or configuration.
- `POST https://api.mcp.ai/api/harvest/get/estimate` — Tool to retrieve a specific estimate by id. use after confirming the estimate id. example: "get estimate with id 123456".
  - body: { estimate_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/invoice` — Tool to retrieve a specific invoice by id. use when you need the full details of an invoice after selecting or creating it. example: 'get invoice with id 13150378.'
  - body: { invoice_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/project` — Tool to retrieve a specific harvest project by id. use when you have a project id and need its details.
  - body: { project_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/task` — Tool to retrieve a specific task by id. use when you have a task id and need its detailed information.
  - body: { task_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/time/entry` — Tool to retrieve a single time entry by id. use when you have a specific time entry id and need its full details.
  - body: { time_entry_id: integer }
- `POST https://api.mcp.ai/api/harvest/get/user` — Tool to retrieve a specific user by id. use after obtaining a valid user id (for example via list users). example: "get details of user 3230547".
  - body: { user_id: integer }
- `POST https://api.mcp.ai/api/harvest/list/client/contacts` — Tool to list client contacts. use when you need to retrieve contacts with optional filtering and pagination.
  - body: { page?: integer, per_page?: integer, client_id?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/clients` — Tool to list clients. use when you need to retrieve a paginated list of clients from harvest. ensure you have a valid access token in metadata before calling.
  - body: { page?: integer, per_page?: integer, is_active?: boolean, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/estimate/messages` — Tool to list messages for an estimate. use after obtaining an estimate id to retrieve associated messages, supports pagination and filtering by update time.
  - body: { page?: integer, per_page?: integer, estimate_id: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/expense/categories` — Tool to list expense categories. use when you need to retrieve a paginated list of expense categories, optionally filtering by active status or last update timestamp.
  - body: { page?: integer, per_page?: integer, is_active?: boolean, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/invoice/item/categories` — Tool to retrieve invoice item categories. use when you need to fetch a paginated list of invoice item categories in harvest.
  - body: { page?: integer, per_page?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/invoice/messages` — Tool to list messages associated with a given invoice. use when you need to retrieve invoice messages with optional filtering by update time and pagination.
  - body: { page?: integer, per_page?: integer, invoice_id: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/invoice/payments` — Tool to retrieve payments for a specific invoice. use when you need to list all payments applied to an invoice after confirming the invoice exists.
  - body: { page?: integer, per_page?: integer, invoice_id: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/invoices` — Tool to list invoices. use when you need to retrieve invoices filtered by client, project, date range, or state. example: 'list invoices for client 5735776 from 2023-01-01 to 2023-01-31.'
  - body: { page?: integer, state?: string, to_date?: string, per_page?: integer, client_id?: integer, from_date?: string, project_id?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/projects` — Tool to list projects. use when you need to retrieve a paginated list of projects from harvest. ensure a valid access token is present in metadata before calling.
  - body: { page?: integer, client?: integer, per_page?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/tasks` — Tool to list tasks. use when you need to retrieve a paginated list of tasks from harvest. ensure you have a valid access token in metadata before calling.
  - body: { page?: integer, per_page?: integer, is_active?: boolean, is_default?: boolean, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/list/time/entries` — Tool to retrieve a list of time entries. use when you need to fetch tracked hours with filters or date ranges for reporting or invoicing. example: "list time entries for project 123 between 2023-01-01
  - body: { to?: string, page?: integer, task_id?: integer, user_id?: integer, per_page?: integer, client_id?: integer, from_date?: string, is_billed?: boolean, is_running?: boolean, project_id?: integer, updated_since?: string, external_reference_id?: string }
- `POST https://api.mcp.ai/api/harvest/list/users` — Tool to list users. use when you need to retrieve a paginated list of users from harvest.
  - body: { page?: integer, per_page?: integer, is_active?: boolean, updated_since?: string }
- `POST https://api.mcp.ai/api/harvest/update/client` — Tool to update an existing client. use after retrieving client details to modify its properties. supports partial updates; omit fields to leave them unchanged.
  - body: { name?: string, address?: string, currency?: string, client_id: integer, is_active?: boolean }
- `POST https://api.mcp.ai/api/harvest/update/client/contact` — Tool to update a client contact. use when you have a contact id and need to modify its details.
  - body: { email?: string, title?: string, last_name?: string, contact_id: integer, first_name?: string, phone_mobile?: string, phone_office?: string }
- `POST https://api.mcp.ai/api/harvest/update/company/info` — Tool to update information about the company. use to modify company settings such as name, timezone, or formatting options. use after obtaining current settings to apply changes.
  - body: { name?: string, currency?: string, timezone?: string, color_scheme?: string, decimal_symbol?: string, week_start_day?: string, thousands_separator?: string }
- `POST https://api.mcp.ai/api/harvest/update/estimate` — Tool to update an existing estimate. use when you need to modify specific fields of an estimate; omit parameters to leave other fields unchanged.
  - body: { tax?: number, tax2?: number, notes?: string, number?: string, subject?: string, currency?: string, discount?: number, client_id?: integer, issue_date?: string, line_items?: object[], estimate_id: integer, purchase_order?: string }
- `POST https://api.mcp.ai/api/harvest/update/estimate/item/category` — Tool to update an estimate item category. use after retrieving the category to change its name.
  - body: { name?: string, estimate_item_category_id: integer }
- `POST https://api.mcp.ai/api/harvest/update/expense` — Tool to update an existing expense. use after retrieving an expense to modify project, category, date, cost, or delete a receipt; omit fields to leave unchanged.
  - body: { notes?: string, units?: number, billable?: boolean, expense_id: integer, project_id?: integer, spent_date?: string, total_cost?: number, delete_receipt?: boolean, expense_category_id?: integer }
- `POST https://api.mcp.ai/api/harvest/update/invoice` — Tool to update an existing invoice. use after retrieving invoice details to modify its fields. supports partial updates; omit fields to leave unchanged.
  - body: { tax?: number, tax2?: number, notes?: string, number?: string, subject?: string, currency?: string, discount?: number, due_date?: string, client_id?: integer, invoice_id: integer, issue_date?: string, line_items?: object[], estimate_id?: integer, retainer_id?: integer, payment_term?: string, purchase_order?: string, payment_options?: string[] }
- `POST https://api.mcp.ai/api/harvest/update/project` — Tool to update an existing project. use when you need to modify one or more fields of a project by its id. invoke after confirming the project id and desired changes.
  - body: { fee?: number, code?: string, name?: string, notes?: string, budget?: number, bill_by?: string, ends_on?: string, budget_by?: string, client_id?: integer, is_active?: boolean, starts_on?: string, project_id: integer, cost_budget?: number, hourly_rate?: number, is_billable?: boolean, is_fixed_fee?: boolean, budget_is_monthly?: boolean, show_budget_to_all?: boolean, notify_when_over_budget?: boolean, cost_budget_include_expenses?: boolean, over_budget_notification_percentage?: number }
- `POST https://api.mcp.ai/api/harvest/update/task` — Tool to update an existing task. use after retrieving task details to modify its attributes such as name, billing defaults, or status. supports partial updates; omit fields to leave them unchanged.
  - body: { name?: string, task_id: integer, is_active?: boolean, is_default?: boolean, billable_by_default?: boolean, default_hourly_rate?: number }
- `POST https://api.mcp.ai/api/harvest/update/time/entry` — Tool to update an existing time entry. use after retrieving the entry to adjust hours, notes, project, or task details. supports partial updates; omit fields to leave unchanged.
  - body: { hours?: number, notes?: string, task_id?: integer, ended_time?: string, project_id?: integer, spent_date?: string, started_time?: string, time_entry_id: integer }
- `POST https://api.mcp.ai/api/harvest/update/user` — Tool to update an existing user. use when you need to modify a user's profile or settings after confirming the user id.
  - body: { email?: string, roles?: string[], user_id: integer, timezone?: string, is_active?: boolean, last_name?: string, first_name?: string, access_roles?: string[], is_contractor?: boolean, weekly_capacity?: integer, has_access_to_all_future_projects?: boolean }

## More
- Page: https://mcp.ai/harvest
- Agent spec (llms.txt): https://mcp.ai/harvest/llms.txt
- Postman collection: https://mcp.ai/harvest/postman.json