# Freeagent — how to use (mcp.ai)

Connect your Freeagent account and use 76 tools for accounting straight from your AI agent. Connect in one click, no API key needed. Cloud-based accounting software for freelancers and small businesses.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_freeagent?ms=1787291220000`
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. `freeagent_cashflow_summary_for_a_given_date_range`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/freeagent`
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/freeagent/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/freeagent/cashflow/summary/for/a/given/date/range` — Tool to retrieve cashflow summary for a given date range from FreeAgent. Use when you need to analyze cash inflow and outflow over a specific period. Provides net cashflow balance, incoming and outgoi
  - body: { to_date: string, from_date: string }
- `POST https://api.mcp.ai/api/freeagent/company/details` — Tool to retrieve company details from FreeAgent. Use when you need information about the company's registration, accounting periods, or settings.
- `POST https://api.mcp.ai/api/freeagent/create/a/journal/set` — Tool to create a journal set in FreeAgent. Use when you need to create manual journal entries for accounting corrections or adjustments. All journal entries must balance to zero (total debits equal to
  - body: { tag?: string, dated_on?: string, description: string, journal_entries: object[] }
- `POST https://api.mcp.ai/api/freeagent/create/a/sales/tax/period` — Tool to create a sales tax period in FreeAgent. Use when you need to establish a new sales tax period with specific rates and settings for tax reporting.
  - body: { is_locked?: boolean, locked_reason?: string, effective_date: string, sales_tax_name: string, sales_tax_rate_1?: string, sales_tax_rate_2?: string, sales_tax_rate_3?: string, sales_tax_is_value_added: boolean, sales_tax_registration_number?: string, sales_tax_registration_status: string }
- `POST https://api.mcp.ai/api/freeagent/create/a/task/under/a/certain/project` — Tool to create a task under a specific project in FreeAgent. Use when you need to add a new task to an existing project for tracking billable or non-billable work.
  - body: { name: string, status?: string, project: string, currency?: string, is_billable?: boolean, billing_rate?: string, billing_period?: string }
- `POST https://api.mcp.ai/api/freeagent/create/a/timeslip` — Tool to create a new timeslip in FreeAgent. Use when you need to log time worked on a project task by a specific user on a given date.
  - body: { task: string, user: string, hours: string, comment?: string, project: string, dated_on: string }
- `POST https://api.mcp.ai/api/freeagent/create/a/user` — Tool to create a new user in FreeAgent. Use when you need to add a new team member with specific role and permissions. Requires 'Tax, Accounting & Users' permission level.
  - body: { role: string, email: string, last_name: string, ni_number?: string, first_name: string, opening_mileage?: number, send_invitation?: boolean, permission_level?: integer, unique_tax_reference?: string }
- `POST https://api.mcp.ai/api/freeagent/create/bank/account` — Tool to create a bank account in FreeAgent. Use when you need to add a new bank account, PayPal account, or credit card account to track financial transactions.
  - body: { name: string, type: string, email?: string, status?: string, currency: string, is_personal?: boolean, account_number?: string, opening_balance?: string }
- `POST https://api.mcp.ai/api/freeagent/create/bill/with/attachment` — Tool to create a bill with optional attachment in FreeAgent. Use when you need to record a supplier bill with line items and optionally attach supporting documentation.
  - body: { due_on: string, contact: string, dated_on: string, reference: string, attachment?: object, bill_items: object[] }
- `POST https://api.mcp.ai/api/freeagent/create/category` — Tool to create a custom category in FreeAgent. Use when you need to add a new category for classifying income or costs. Note that tax_reporting_name is required for cost_of_sales, admin_expenses, curr
  - body: { description: string, nominal_code: string, category_group: string, allowable_for_tax?: boolean, tax_reporting_name?: string, auto_sales_tax_rate?: string }
- `POST https://api.mcp.ai/api/freeagent/create/contact` — Tool to create a new contact in FreeAgent. Use when you need to add a new client, supplier, or business contact with their details.
  - body: { town?: string, email?: string, locale?: string, mobile?: string, region?: string, country?: string, address1?: string, address2?: string, address3?: string, postcode?: string, last_name?: string, first_name?: string, phone_number?: string, billing_email?: string, charge_sales_tax?: string, organisation_name?: string, contact_name_on_invoices?: boolean, default_payment_terms_in_days?: integer, sales_tax_registration_number?: string, uses_contact_invoice_sequence?: boolean }
- `POST https://api.mcp.ai/api/freeagent/create/credit/note` — Tool to create a credit note in FreeAgent. Use when you need to issue a credit note to a contact for refunds or adjustments. The credit note is created with 'Draft' status.
  - body: { due_on?: string, contact: string, project?: string, comments?: string, currency?: string, dated_on: string, reference?: string, omit_header?: boolean, bank_account?: string, discount_percent?: string, credit_note_items?: object[], payment_terms_in_days: integer }
- `POST https://api.mcp.ai/api/freeagent/create/credit/note/reconciliation` — Tool to create a credit note reconciliation in FreeAgent. Use when you need to reconcile a credit note against an invoice, offsetting the invoice amount with the credit note.
  - body: { invoice: string, currency: string, dated_on: string, credit_note: string, gross_value: string, exchange_rate: string }
- `POST https://api.mcp.ai/api/freeagent/create/estimate` — Tool to create a new estimate in FreeAgent. Use when you need to create an estimate, quote, or proposal for a client. Requires contact, reference, date, type, status, and at least one estimate item wi
  - body: { notes?: string, status: string, contact: string, project?: string, currency?: string, dated_on: string, ec_status?: string, reference: string, estimate_type: string, estimate_items: object[], place_of_supply?: string, discount_percent?: string, client_contact_name?: string, include_sales_tax_on_total_value?: boolean }
- `POST https://api.mcp.ai/api/freeagent/create/estimate/item` — Tool to create an estimate item in FreeAgent. Use when you need to add a line item to an existing estimate with details like position, type, quantity, price, and optional description.
  - body: { estimate: string, estimate_item: object }
- `POST https://api.mcp.ai/api/freeagent/create/estimates/duplicate` — Tool to duplicate an existing estimate in FreeAgent. Use when you need to create a copy of an estimate. The duplicated estimate will always have status=Draft, the next reference in the sequence, and d
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/create/estimates/send/email` — Tool to email an estimate in FreeAgent. Use when you need to send an estimate to a contact via email with customizable subject, body, and attachments. You can use an existing email template (use_templ
  - body: { id: string, estimate: object }
- `POST https://api.mcp.ai/api/freeagent/create/invoice` — Tool to create an invoice in FreeAgent. Use when you need to generate a new invoice for a contact. The invoice will be created in 'Draft' status and can be modified or sent later.
  - body: { due_on: string, contact: string, comments?: string, currency?: string, dated_on: string, reference?: string, invoice_items?: object[], send_reminder_emails?: boolean, payment_terms_in_days: integer, send_thank_you_emails?: boolean, send_new_invoice_emails?: boolean }
- `POST https://api.mcp.ai/api/freeagent/create/invoice/item` — Tool to create an invoice item in FreeAgent. Use when you need to add a line item to an existing invoice with details like type, quantity, price, and description.
  - body: { invoice: string, invoice_item: object }
- `POST https://api.mcp.ai/api/freeagent/create/invoices/duplicate` — Tool to duplicate an existing invoice in FreeAgent. Use when you need to create a new invoice based on an existing one. The duplicated invoice is always created with status 'Draft', today's date, and 
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/create/notes` — Tool to create a note for a contact or project in FreeAgent. Use when you need to add documentation, reminders, or context to contacts or projects.
  - body: { note: string, contact?: string, project?: string }
- `POST https://api.mcp.ai/api/freeagent/create/price/list/items` — Tool to create a price list item in FreeAgent. Use when you need to add a new item to the price list with code, description, pricing, and tax information.
  - body: { code: string, price: string, category?: string, quantity: string, item_type: string, vat_status?: string, description: string, sales_tax_rate?: string, second_sales_tax_rate?: string }
- `POST https://api.mcp.ai/api/freeagent/create/project` — Tool to create a project in FreeAgent. Use when you need to set up a new project for tracking time, expenses, and billing against a specific client or internal initiative.
  - body: { name: string, budget: number, status: string, contact: string, ends_on?: string, is_ir35?: boolean, currency: string, starts_on?: string, budget_units: string, hours_per_day?: number, billing_period?: string, normal_billing_rate?: number, contract_po_reference?: string, uses_project_invoice_sequence: boolean }
- `POST https://api.mcp.ai/api/freeagent/delete/bank/transaction` — Tool to delete a bank transaction explanation in FreeAgent. Use when you need to remove an explanation from a bank transaction.
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/delete/estimates/default/additional/text` — Tool to delete default additional text for estimates in FreeAgent. Use when you need to remove the default additional text that appears on estimates.
- `POST https://api.mcp.ai/api/freeagent/delete/notes1` — Tool to delete a note by its ID. Use when you need to permanently remove a note from FreeAgent.
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/get/invoice/timeline` — Tool to retrieve invoice timeline showing chronological record of invoice-related events. Use when you need to track invoice payment history and related activities.
- `POST https://api.mcp.ai/api/freeagent/get/mileage/settings` — Tool to retrieve mileage settings including engine type/size options and reimbursement rates. Use when you need to determine valid engine configurations or current mileage rates for expense claims.
- `POST https://api.mcp.ai/api/freeagent/get/opening/balances` — Tool to retrieve the Opening Balances journal set for a company. Use when you need to access initial account balances including journal entries, bank accounts, and stock items.
- `POST https://api.mcp.ai/api/freeagent/get/personal/profile` — Tool to retrieve the authenticated user's personal profile from FreeAgent. Use when you need information about the current user's details, role, or permissions.
- `POST https://api.mcp.ai/api/freeagent/get/the/opening/balances` — Tool to retrieve the opening balances from the trial balance summary. Use when you need to get the initial balance amounts for all account categories at the start of the accounting period.
- `POST https://api.mcp.ai/api/freeagent/get/the/pl/summary` — Tool to retrieve the Profit and Loss summary for a specified period from FreeAgent. Use when you need financial performance overview including income, expenses, and retained profit.
  - body: { to_date?: string, from_date?: string, accounting_period?: string }
- `POST https://api.mcp.ai/api/freeagent/get/the/trial/balance/summary` — Tool to get the trial balance summary from FreeAgent. Use when you need to retrieve the trial balance report data for accounting purposes.
  - body: { to_date?: string, from_date?: string }
- `POST https://api.mcp.ai/api/freeagent/list/accounting/balance/sheet` — Tool to retrieve the balance sheet for a FreeAgent account. Use when you need to get financial position data including assets, liabilities, and equity. Returns balance sheet data for the specified dat
  - body: { as_at_date?: string }
- `POST https://api.mcp.ai/api/freeagent/list/accounting/balance/sheet2` — Tool to retrieve opening balances for the balance sheet from FreeAgent. Use when you need to get the initial financial position values including capital assets, current assets, liabilities, and equity
- `POST https://api.mcp.ai/api/freeagent/list/accounting/transactions` — Tool to list all accounting transactions from FreeAgent. Use when you need to retrieve transaction history for accounting purposes. Filter by date range or nominal code to narrow results.
  - body: { page?: integer, to_date?: string, per_page?: integer, from_date?: string, nominal_code?: string }
- `POST https://api.mcp.ai/api/freeagent/list/all/cis/bands/for/a/company` — Tool to list all CIS (Construction Industry Scheme) bands for a company. Use when you need to retrieve the available CIS bands configured for a UK company enrolled in CIS for Subcontractors. The bands
- `POST https://api.mcp.ai/api/freeagent/list/all/expenses` — Tool to list all expenses from FreeAgent. Use when you need to retrieve expense records, optionally filtered by view type (recent/recurring), date range, project, or last update timestamp.
  - body: { page?: integer, view?: string, project?: string, to_date?: string, per_page?: integer, from_date?: string, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/all/price/list/items` — Tool to list all price list items from FreeAgent. Use when you need to retrieve all price list items with optional sorting by creation date, code, or update date.
  - body: { page?: integer, sort?: string, per_page?: integer }
- `POST https://api.mcp.ai/api/freeagent/list/all/properties` — Tool to list all properties in FreeAgent. Use when you need to retrieve property records for UK unincorporated landlord companies. Supports pagination for large result sets.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/freeagent/list/all/recurring/invoices` — Tool to retrieve a list of recurring invoices from FreeAgent. Use when you need to query recurring invoices by status or contact. Supports filtering by draft, active, or inactive status and can includ
  - body: { page?: integer, view?: string, contact?: string, per_page?: integer, nested_invoice_items?: boolean }
- `POST https://api.mcp.ai/api/freeagent/list/all/sales/tax/periods/for/a/company` — Tool to list all sales tax periods for a company in FreeAgent. Use when you need to retrieve sales tax configuration history including rates, registration status, and effective dates. Available for US
- `POST https://api.mcp.ai/api/freeagent/list/all/stock/items` — Tool to list all stock items from FreeAgent. Use when you need to retrieve stock items with optional sorting by creation date, description, or update date.
  - body: { page?: integer, sort?: string, per_page?: integer }
- `POST https://api.mcp.ai/api/freeagent/list/all/tasks` — Tool to list all tasks in FreeAgent. Use when you need to retrieve tasks with optional filtering by status, project, or update date, and sorting options.
  - body: { page?: integer, sort?: string, view?: string, project?: string, per_page?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/all/timeslips` — Tool to list all timeslips from FreeAgent. Use when you need to retrieve time tracking records with optional filtering by date range, user, project, task, billing status, or last update timestamp.
  - body: { page?: integer, task?: string, user?: string, view?: string, nested?: boolean, project?: string, to_date?: string, per_page?: integer, from_date?: string, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/all/users` — Tool to list users in FreeAgent. Use when you need to retrieve users with optional filtering by type (all, staff, advisors). Requires 'Tax, Accounting & Users' permission scope.
  - body: { view?: string }
- `POST https://api.mcp.ai/api/freeagent/list/bank/accounts` — Tool to list bank accounts in FreeAgent. Use when you need to retrieve all bank accounts or filter by account type (standard, credit card, or PayPal).
  - body: { view?: string }
- `POST https://api.mcp.ai/api/freeagent/list/bank/feeds` — Tool to list all bank feeds for a company. Use when you need to retrieve the list of bank feeds and their current status.
- `POST https://api.mcp.ai/api/freeagent/list/bank/transactions` — Tool to list all bank transactions under a certain bank account in FreeAgent. Use when you need to retrieve transaction history, reconcile accounts, or find specific transactions for a bank account.
  - body: { page?: integer, view?: string, to_date?: string, per_page?: integer, from_date?: string, bank_account: string, last_uploaded?: boolean, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/bills` — Tool to retrieve a list of bills from FreeAgent. Use when you need to view bills with optional filters by status, date range, contact, or project.
  - body: { page?: integer, view?: string, contact?: string, project?: string, to_date?: string, per_page?: integer, from_date?: string, updated_since?: string, nested_bill_items?: boolean }
- `POST https://api.mcp.ai/api/freeagent/list/business/categories` — Tool to retrieve all available business categories from FreeAgent. Use when you need to get the complete list of industry classifications for company categorization.
- `POST https://api.mcp.ai/api/freeagent/list/categories` — Tool to retrieve all categories for the current FreeAgent company. Categories are used to classify income or costs for estimate items, invoice items, expenses, bills, and bank transaction explanations
  - body: { sub_accounts?: boolean }
- `POST https://api.mcp.ai/api/freeagent/list/contacts` — Tool to list contacts in FreeAgent. Use when you need to retrieve contacts with optional filtering by type, sort order, or update date.
  - body: { page?: integer, sort?: string, view?: string, per_page?: integer, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/credit/note/reconciliations` — Tool to retrieve all credit note reconciliations from FreeAgent. Use when you need to list credit notes that have been reconciled against invoices. Optionally filter by update timestamp or date range.
  - body: { page?: integer, to_date?: string, per_page?: integer, from_date?: string, updated_since?: string }
- `POST https://api.mcp.ai/api/freeagent/list/credit/notes` — Tool to list credit notes from FreeAgent. Use when you need to retrieve credit notes with optional filtering by contact, project, status, or date range. Requires 'Estimates and Invoices' permission.
  - body: { page?: integer, sort?: string, view?: string, contact?: string, project?: string, per_page?: integer, updated_since?: string, nested_credit_note_items?: boolean }
- `POST https://api.mcp.ai/api/freeagent/list/ec/moss/sales/tax/rates` — Tool to retrieve EC VAT MOSS sales tax rates for a specific EU country and date. Use when you need to determine the applicable VAT rates for cross-border digital services within the EU.
  - body: { date: string, country: string }
- `POST https://api.mcp.ai/api/freeagent/list/estimates` — Tool to list estimates in FreeAgent. Use when you need to retrieve estimates with optional filtering by status, date range, contact, project, or invoice. Set nested_estimate_items to true to include e
  - body: { page?: integer, view?: string, contact?: string, invoice?: string, project?: string, to_date?: string, per_page?: integer, from_date?: string, updated_since?: string, nested_estimate_items?: boolean }
- `POST https://api.mcp.ai/api/freeagent/list/estimates/default/additional/text` — Tool to retrieve the default additional text for estimates. Use when you need to get the default text that appears on all estimate documents.
- `POST https://api.mcp.ai/api/freeagent/list/final/accounts/reports` — Tool to list final accounts reports for a company in FreeAgent. Use when you need to retrieve all final accounts reports with their filing status and period dates.
- `POST https://api.mcp.ai/api/freeagent/list/hire/purchases` — Tool to retrieve all hire purchases for the authorized FreeAgent account. Use when you need to view existing hire purchase agreements. Requires 'Bills' access level and is only available for UK compan
- `POST https://api.mcp.ai/api/freeagent/list/invoices/default/additional/text` — Tool to get the default additional text shown on all invoices. Use when you need to retrieve the default invoice text.
- `POST https://api.mcp.ai/api/freeagent/list/notes` — Tool to retrieve a list of notes for a contact or project. Use when you need to view all notes associated with a specific contact or project.
  - body: { page?: integer, contact?: string, project?: string, per_page?: integer }
- `POST https://api.mcp.ai/api/freeagent/list/projects` — Tool to list projects in FreeAgent. Use when you need to retrieve projects with optional filtering by status and sorting. Requires 'Contacts and Projects' permission scope.
  - body: { page?: integer, sort?: string, view?: string, nested?: boolean, per_page?: integer }
- `POST https://api.mcp.ai/api/freeagent/list/vat/returns` — Tool to list VAT returns for a company in FreeAgent. Use when you need to retrieve VAT return records, their filing status, and payment information.
- `POST https://api.mcp.ai/api/freeagent/show/tax/timeline` — Tool to retrieve the company's tax timeline showing upcoming tax events and deadlines. Use when you need to view VAT returns, corporation tax payments, Companies House filings, and other tax-related e
- `POST https://api.mcp.ai/api/freeagent/update/bank/transaction/explanations` — Tool to update a bank transaction explanation in FreeAgent. Use when you need to modify an existing explanation's details such as description, category, amounts, or tax information.
  - body: { id: string, bank_transaction_explanation: object }
- `POST https://api.mcp.ai/api/freeagent/update/estimates/default/additional/text` — Tool to update the default additional text for estimates in FreeAgent. Use when you need to set or change the standard text that appears on all estimates.
  - body: { default_additional_text: string }
- `POST https://api.mcp.ai/api/freeagent/update/estimates/transitions/convert` — Tool to convert an estimate to an invoice in FreeAgent. Use when an estimate has been approved and needs to be converted into a billable invoice. The estimate's status will transition to 'Invoiced' an
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/update/expenses` — Tool to update an existing expense in FreeAgent. Use when you need to modify expense details such as description, amount, date, category, or tax information. Only the fields you provide will be update
  - body: { id: string, user?: string, mileage?: string, project?: string, category?: string, currency?: string, dated_on?: string, description?: string, gross_value?: string, rebill_type?: string, vehicle_type?: string, rebill_factor?: string, sales_tax_rate?: string, reclaim_mileage?: integer, sales_tax_value?: string, receipt_reference?: string, manual_sales_tax_amount?: string }
- `POST https://api.mcp.ai/api/freeagent/update/invoices/default/additional/text` — Tool to update the default additional text shown on all invoices. Use when you need to set or change the default invoice text that appears at the bottom of all invoices.
  - body: { default_additional_text: string }
- `POST https://api.mcp.ai/api/freeagent/update/invoices/transitions/convert` — Tool to convert a draft negative invoice to a credit note in FreeAgent. Use when you need to transform a draft invoice with a negative value into a credit note. The invoice must be in draft status and
  - body: { id: string }
- `POST https://api.mcp.ai/api/freeagent/update/journal/sets` — Tool to update a journal set in FreeAgent. Use when you need to modify journal entries, change description, date, or tag. Can add new entries, modify existing ones, or remove entries using _destroy fl
  - body: { id: string, tag?: string, dated_on?: string, description?: string, journal_entries?: object[] }
- `POST https://api.mcp.ai/api/freeagent/update/notes1` — Tool to update an existing note in FreeAgent. Use when you need to modify the text content of a note attached to a contact or project.
  - body: { id: string, note: string }
- `POST https://api.mcp.ai/api/freeagent/update/price/list/items` — Tool to update a price list item in FreeAgent. Use when you need to modify existing price list item fields like description, price, code, quantity, or tax settings.
  - body: { id: string, code?: string, price?: string, category?: string, quantity?: string, item_type?: string, vat_status?: string, description?: string, sales_tax_rate?: string, second_sales_tax_rate?: string }
- `POST https://api.mcp.ai/api/freeagent/update/users/me` — Tool to update the authenticated user's personal profile in FreeAgent. Use when you need to modify user details such as name, email, role, or tax information.
  - body: { role?: string, email?: string, last_name?: string, ni_number?: string, first_name?: string, opening_mileage?: integer, permission_level?: integer, unique_tax_reference?: string }
- `POST https://api.mcp.ai/api/freeagent/upload/a/bank/statement` — Tool to upload a bank statement to FreeAgent. Use when you need to import multiple bank transactions at once for a specific bank account.
  - body: { statement: object[], bank_account: string }

## Example prompts
- "What can I do in Freeagent?"
- "Show me a summary of my Freeagent account"

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