XBert MCP Server

XBert is an AI automation platform for accounting firms. The XBert MCP server gives AI assistants secure, real-time access to accounting data from Xero and QuickBooks, along with workflow automation, document generation, and practice management tools.

Server URL: https://mcp-gateway.xbert.io MCP Protocol Version: 2025-03-26 (Streamable HTTP)

Who is this for?

Accounting firms and bookkeepers who use XBert with Xero or QuickBooks. The MCP server allows AI assistants like Claude to query financial data, manage tasks, generate reports, and automate workflows on your behalf.

Quick Start

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "xbert": {
      "url": "https://mcp-gateway.xbert.io/mcp"
    }
  }
}

Claude Desktop will handle the OAuth 2.1 authentication flow automatically.

Claude.ai

Open Settings > MCP Integrations
Click Add MCP Server
Enter the server URL: https://mcp-gateway.xbert.io/mcp
Follow the authentication prompts to connect your XBert account

Other MCP Clients

Any MCP-compatible client can connect using the server URL above. The server supports OAuth 2.1 with PKCE for authentication (see below).

Authentication

The XBert MCP server uses OAuth 2.1 with PKCE (S256). Most MCP clients handle this automatically, but here is the flow for reference:

Discovery

The server publishes standard OAuth metadata endpoints:

GET /.well-known/oauth-authorization-server (RFC 8414)
GET /.well-known/oauth-protected-resource (RFC 9728)

Flow

Dynamic Client Registration -- POST /oauth/register to obtain a client_id
Authorisation -- Redirect the user to GET /oauth/authorize with PKCE challenge (S256 required)
Token Exchange -- POST /oauth/token with the authorisation code and PKCE verifier
Business Selection -- Call Auth_ListBusinesses to see available businesses. If you have access to only one, it is selected automatically. Otherwise, call Auth_SelectBusiness to choose one.

All subsequent tool calls operate within the context of the selected business.

Scopes

openid profile email offline_access

Rate Limiting

The server enforces rate limits to protect service availability. If you receive a 429 Too Many Requests response, wait before retrying.

Available Tools

The XBert MCP server exposes 70+ tools across these categories:

Category	Tools	Description
Auth	4	Business selection and session management
Data	40+	Read-only accounting data retrieval
Features	12+	Work management, notes, templates, scheduling
Workflow	7	Automation actions (notes, reports, reminders, lock dates)
Practice	1	Practice-level account review
Utility	5	CSV, Excel, PDF, Word export and entity link generation
SemanticExtraction	3	Document text extraction and analysis
XBert	2	XBert notification resolve data and instructions
Fabric	2	Duplicate bill and bank transaction detection
Product	2	Add comments and update status on work items
AutomationPlan	2	Automation checkpoint management

See docs/TOOL-CATALOGUE.md for the full tool catalogue with parameters and safety classifications.

See docs/EXAMPLES.md for example prompts and use cases.

Safety Classifications

Tools are classified for safety:

Read-only -- Tools that only retrieve data. No changes are made to your accounting system or XBert workspace.
Destructive -- Tools that create, update, or modify data. These are clearly marked in the tool catalogue.

XBert MCP Tool Catalogue

This document lists every tool exposed through the XBert MCP Gateway, grouped by category. Each tool includes its parameters, whether it is read-only or destructive, and a brief description.

Server-injected parameters such as userProfileId, connectTenantId, firstName, and localeCode are automatically provided by the Gateway from your authenticated session. You do not need to supply these -- they are omitted from the parameter tables below.

Auth -- Business Selection and Session Management

These tools manage which business (Connect Portal) you are working with. Call Auth_ListBusinesses first after authentication.

Auth_ListBusinesses

Lists the businesses (Connect Portals) accessible to your account. If you only have access to one business, it will be automatically selected.

Safety	Read-only

Parameters: None

Auth_SelectBusiness

Selects a business (Connect Portal) to work with. Required before using any data or workflow tools.

Safety	Read-only

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	The Connect Tenant ID of the business to select, as returned by `Auth_ListBusinesses`.

Auth_SwitchBusiness

Switches to a different business (Connect Portal). Clears the current session and establishes a new one.

Safety	Read-only

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	The Connect Tenant ID of the business to switch to.

Auth_GetCurrentSession

Returns information about the currently selected business session, including the business name and when it was selected.

Safety	Read-only

Parameters: None

Data -- Accounting Data Retrieval

All Data tools are read-only. They retrieve financial and accounting data from the connected accounting system (Xero or QuickBooks).

Many Data tools share a common set of optional parameters:

Common Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID to retrieve data for. Use `Data_FindSimilarClientTenants` to find this.
`question`	string	No	Natural language question to filter or focus the data query.
`startDate`	string	No	Start date filter in `yyyy-MM-dd` format.
`endDate`	string	No	End date filter in `yyyy-MM-dd` format.
`dateFormats`	string	No	Date format preference for the response (default: `yyyy-MM-dd,MM/dd/yyyy,dd/MM/yyyy`).
`exportFormat`	string	No	Export the data as a file: `csv`, `pdf`, or `excel`. Leave empty to return data only.

Tools that deviate from these common parameters have their full parameter lists shown below.

Client Discovery

Data_FindSimilarClientTenants

Searches for client tenants matching a name. Use this first when a user mentions a client by name to resolve the name to a clientTenantId.

Parameter	Type	Required	Description
`searchTerm`	string	Yes	The client name to search for.

Data_GetAllAccessibleClients

Retrieves all client tenants the user has access to. Use when the user asks for "all clients" or makes a query without specifying a client.

Parameters: None (beyond server-injected)

Financial Statements

Data_FinancialStatements

Sprint 0 #1273 consolidation tool that retrieves a primary financial statement (balance sheet, profit & loss, or trial balance) for a client via the statement discriminator.

Parameter	Type	Required	Description
`clientTenantId`	int	Yes	The client tenant ID.
`userProfileId`	long	Yes	The authenticated user profile ID (server-injected).
`statement`	string	Yes	One of: `balanceSheet`, `profitAndLoss`, `trialBalance`. Aliases for profitAndLoss: `pl`, `p&l`.
`question`	string	No	Natural language question to focus the query (balanceSheet and profitAndLoss).
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`endDate`	string	No	End date in `yyyy-MM-dd` format.
`asOfDate`	string	No	As-of date in `yyyy-MM-dd` format (only used for `statement=trialBalance`; defaults to today).
`isAccrual`	string	No	Accounting method for P&L: `true` for accrual basis, `false` for cash basis. Default: `true`. Only used for `statement=profitAndLoss`.
`connectTenantId`	int	No	Practice portal ID. Only used for `statement=profitAndLoss` multi-tenant rollups.
`firstName`	string	No	Used only for `profitAndLoss` response formatting.
`localeCode`	string	No	Used only for `profitAndLoss` response formatting.
`exportFormat`	string	No	Export format: `csv`, `pdf`, or `excel` (schema-uniformity stub — value currently discarded).

Data_Cashflow

Retrieves cashflow data for a client. Uses common parameters.

Aged Balances

Data_AgedPayables

Retrieves aged payables data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`asOfDate`	string	No	As-of date for ageing calculation in `yyyy-MM-dd` format. Defaults to today.

Data_AgedReceivables

Retrieves aged receivables data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`asOfDate`	string	No	As-of date for ageing calculation in `yyyy-MM-dd` format. Defaults to today.

Transactions

Data_Invoices

Retrieves invoice data for a client. Uses common parameters.

Data_Bills

Retrieves bill data for a client. Uses common parameters.

Data_BankTransactions

Retrieves bank transaction data for a client. Uses common parameters.

Data_BankStatements

Retrieves bank statement data for a client. Uses common parameters.

Data_CreditNotes

Retrieves credit note data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`endDate`	string	No	End date in `yyyy-MM-dd` format.

Data_Prepayments

Retrieves prepayment data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_BatchPayments

Retrieves batch payment data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`endDate`	string	No	End date in `yyyy-MM-dd` format.

Data_BankTransfers

Retrieves bank transfer data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`startDate`	string	No	Start date in `yyyy-MM-dd` format. If omitted, defaults to 12 months ago.
`endDate`	string	No	End date in `yyyy-MM-dd` format. If omitted, defaults to today.

Data_ManualJournals

Retrieves manual journal data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`startDate`	string	No	Start date in `yyyy-MM-dd` format. If omitted, defaults to 3 months ago.
`endDate`	string	No	End date in `yyyy-MM-dd` format. If omitted, defaults to today.

Data_Quotes

Retrieves quote data for a client. Uses common parameters plus:

Additional Parameter	Type	Required	Description
`dateProperty`	string	No	Date field for filtering: `QuoteDate` (created) or `ExpiryDate` (expires). Default: `QuoteDate`.

Data_PurchaseOrders

Retrieves purchase order data for a client. Uses common parameters.

Accounts and Contacts

Data_ChartOfAccounts

Retrieves the chart of accounts for a client. Uses common parameters (no date filtering).

Data_Contacts

Retrieves contact data for a client. Uses common parameters (no date filtering).

Data_TaxRates

Retrieves tax rate data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_TrackingCategories

Retrieves tracking category data for a client. Uses common parameters.

Data_Organisation

Retrieves organisation details for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`exportFormat`	string	No	Export format: `csv`, `pdf`, or `excel`.

Banking

Data_BankAccounts

Retrieves bank account data for a client. Uses common parameters.

Data_ReconciliationStatus

Retrieves the reconciliation status for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_UnreconciledBankTransactions

Retrieves unreconciled bank transactions for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_LockDates

Retrieves lock date information for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Payroll

Data_PayRuns

Retrieves pay run data for a client. Uses common parameters.

Data_PayrollSettings

Retrieves payroll settings for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_EmployeeLeaveBalances

Retrieves employee leave balance data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_SuperannuationFunds

Retrieves superannuation fund data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Tax and Compliance

Data_BASSummary

Retrieves the BAS (Business Activity Statement) summary for a client (Australia).

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`basPeriod`	string	No	BAS period, e.g., `Q1 2024`, `Jan 2024`. Defaults to current quarter.
`periodType`	string	No	`Quarterly` (default) or `Monthly`.

Data_VATSummary

Retrieves the VAT summary for a client (United Kingdom).

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`vatPeriod`	string	No	VAT period, e.g., `Q1 2025`, `Jan 2025`. Defaults to current period.
`periodType`	string	No	`Quarterly` (default), `Monthly`, or `Annual`.

Data_IASSummary

Retrieves the IAS (Instalment Activity Statement) summary for a client (Australia).

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`iasPeriod`	string	No	IAS period, e.g., `Q1 2025`, `Jan 2025`. Defaults to current period.
`periodType`	string	No	`Quarterly` (default) or `Monthly`.

Data_IRDGSTSummary

Retrieves the IRD GST summary for a client (New Zealand).

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`gstPeriod`	string	No	GST period, e.g., `Jan-Feb 2025`, `Jul-Dec 2025`. Defaults to current period.
`periodType`	string	No	`TwoMonthly` (default), `Monthly`, or `SixMonthly`.

Data_MTDReadiness

Retrieves Making Tax Digital (MTD) readiness summary for a client (United Kingdom).

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`taxYear`	string	No	Tax year, e.g., `2025-26`. Defaults to current tax year.

Assets

Data_FixedAssets

Retrieves fixed asset data for a client. Uses common parameters.

Data_FixedAssetDepreciation

Retrieves fixed asset depreciation data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Budgets

Data_Budgets

Retrieves budget data for a client. Uses common parameters.

Data_BudgetAdherence

Retrieves budget adherence (actuals vs. budget) for a client. Uses common parameters plus:

Additional Parameter	Type	Required	Description
`isAccrual`	string	No	Accounting method: `true` for accrual basis, `false` for cash basis. Default: `true`.

Data Quality and Health

Data_LedgerHealthSummary

Retrieves the overall ledger health summary for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_DataQualityScore

Retrieves the data quality score for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_XBertConfigurations

Retrieves the XBert automation configurations for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_XBertNotificationSummary

Retrieves a summary of XBert notifications for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Record Retrieval

Data_GetSingleRecord

Retrieves a single accounting record by its source link.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`dataType`	string	Yes	Record type: `BankTransaction`, `Bill`, `Invoice`, `FixedAsset`, `CreditNote`, `PurchaseOrder`, `BankAccount`, `Budget`, `ProfitAndLoss`, `Payroll`, `BalanceSheet`, `Contact`, `ManualJournal`, `Quote`, `BankStatement`, `Organisation`, `Payment`, `PrePayment`, `ChartOfAccount`.
`sourceLink`	string	Yes	The SourceLink (accounting system GUID) that uniquely identifies the record.

Smart Search and Context

Data_GetReviewSummaryContext

Retrieves review summary context for a notification.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`notificationId`	long	Yes	The notification ID whose review has completed.
`conversationId`	long	Yes	The conversation/task ID for this review session.

Data_GetAgentSetupStatus

Retrieves the setup status of the XBert agent backing a plugin/slash command — whether the agent exists for the caller's Connect portal, whether it is active, and which XBert configurations are linked to it via AgentXBertConfiguration. Intended as the FIRST call from any XBert review plugin: if setup.configured is false the plugin must stop and relay the setup guidance instead of falling back to generic worklist data. Returns firm-level setup facts only — never agent instructions.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`userProfileId`	long	Yes	The user profile ID. Required for security — validates the user has access to the client.
`agentCommand`	string	Yes	Slash-command slug of the agent backing the plugin, without the leading slash (e.g. `anomaly-review`).

Returns a YAML document with a context: header (type, agentCommand, clientTenantId, connectTenantId), an agent: block (found, agentId, name, type — system or custom — and isActive; just found: false when no agent matches), a linkedXBerts: block (count plus items with xbertConfigurationId, isActive, name), and a setup: block (configured, reason, guidance).

Data_GetLinkedXBertsForAgent

Returns the deterministic list of outstanding XBerts (notifications) linked to a given agent via AgentXBertConfiguration, optionally bounded by a review period via TransactionDate. Used by XI Review sub-agents in XBert review mode so the LLM does not make the inclusion decision — it only writes a per-XBert relevance reason for each returned item.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`userProfileId`	long	Yes	The user profile ID. Required for security — validates the user has access to the client.
`agentId`	long	Yes	The agent whose linked XBert configurations drive the SQL filter.
`connectTenantId`	integer	No	Connect (portal) tenant ID where `AgentXBertConfiguration` rows live. Resolved from the validated `clientTenantId` when omitted.
`startDate`	string	No	Inclusive review-period start (`yyyy-MM-dd`). Excludes XBerts with earlier `TransactionDate`.
`endDate`	string	No	Inclusive review-period end (`yyyy-MM-dd`). Excludes XBerts with later `TransactionDate`.
`currentNotificationId`	long	No	The parent review-task notification ID to exclude from the result.

Returns a YAML document with a context: header (type, agentId, clientTenantId, connectTenantId, startDate, endDate, totalLinkedXBerts) and a linkedXBerts: list whose entries include notificationId, title, description, analyticsGroup, riskLevel, riskType, amount, transactionDate, dueDate, detected, status, assignedTo, xbertValueResultId, xbertConfigurationId, externalDataId, and suggestedDataArea.

Data_InsertNotificationSmartSearch

Inserts notification smart search filters.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`notificationId`	long	Yes	The notification ID these filters relate to.
`agentName`	string	Yes	Name of the agent.
`filtersJson`	string	Yes	JSON representation of filters.
`conversationId`	long	No	The conversation/task ID. Optional.

Practice Management Data

Data_JournalMaster

Retrieves journal master data for a client. Uses common parameters.

Data_RepeatingBills

Retrieves repeating bill data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_RepeatingInvoices

Retrieves repeating invoice data for a client.

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.

Data_XPMClients

Retrieves Xero Practice Manager client portfolio / client metadata (broad warehouse portfolio summary). Uses common parameters.

For job questions use the Data_XPMJobs_* trio below — Data_XPMClients returns the entire client portfolio with every nested job and is the wrong, expensive tool for job-level queries.

Data_XPMJobs_Search

Paged, filterable list of XPM (Xero Practice Manager) jobs (lean rows). Read-only; queries the XPM warehouse directly. Returns up to 25 rows per page (max 100) plus an opaque nextCursor. The date window filters on the job due date.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway.
`state`	string	No	Exact job state (e.g. `In Progress`, `Completed`).
`clientName`	string	No	Case-insensitive substring on the job's client name.
`manager`	string	No	Case-insensitive substring on the job manager's name.
`partner`	string	No	Case-insensitive substring on the job partner's name.
`dueFrom`	string	No	Inclusive lower bound on due date (`yyyy-MM-dd`).
`dueTo`	string	No	Inclusive upper bound on due date (`yyyy-MM-dd`).
`overdueOnly`	string	No	`true` to return only overdue jobs.
`pageSize`	integer	No	Rows per page. Default 25, max 100.
`cursor`	string	No	Opaque pagination cursor from a previous call.

Lean row: jobUuid, jobId, name, state, clientName, managerName, partnerName, startDate, dueDate, completedDate, overdue (computed).

Data_XPMJobs_Summary

Bucketed XPM job aggregates: counts by state, overdue-by-manager, due-this-week / due-this-month counts, and average turnaround (start → completion) for jobs completed in the range. Read-only; queries the XPM warehouse directly. Returns a SUMMARY_DATASET_TOO_LARGE structured error (remediation → Data_XPMJobs_Search) when the portfolio exceeds 5,000 jobs.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway.
`startDate`	string	Yes	Scopes the completed-in-range / average-turnaround calculation (`yyyy-MM-dd`).
`endDate`	string	Yes	Scopes the completed-in-range / average-turnaround calculation (`yyyy-MM-dd`).

The overdue and due-this-week/-month buckets are computed as of now; only the completed-in-range / turnaround metrics use the date range.

Data_XPMJobs_Get

Full detail for up to 25 XPM job UUIDs: tasks (estimated vs actual minutes, completed, billable), milestones, assigned staff, notes including comments, and client-level invoices (the warehouse has no reliable invoice→job link). Read-only; queries the XPM warehouse directly. UUIDs belonging to another connect tenant are silently dropped. This is the natural owner of job milestones / assigned staff / note comments — it supersedes the retired interim Data_XPMJobDetail.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway.
`jobUuids`	string	Yes	Comma-separated job UUIDs (up to 25). Obtain from `Data_XPMJobs_Search` / `Data_XPMJobs_Summary`.

Data_XPMStaff

Retrieves the XPM (Xero Practice Manager) staff roster — the people who work at the practice — aggregated across all XPM-enabled clients of the connect tenant and de-duplicated by staff UUID. Returns name, email, phone, mobile, payrollCode, webUrl. Use for "who works at the practice" / "the staff list". NOT for time logged BY staff (use Data_XPMTimesheets_*).

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID. The server fans out across XPM-enabled children.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.

Data_XPMClientDetail

Retrieves one XPM client's practice-CRM detail — contacts, groups, relationships, notes — by XPM client UUID. Returns { clientUuid, name, contacts[], groups[], relationships[], notes[] }. NOT Xero ledger contacts (use Data_Contacts_*). A UUID outside the connect's XPM-enabled tenants is dropped and audited.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`clientUuid`	string	Yes	The XPM client UUID (GUID). Obtain from `Data_XPMClients` or `Data_XPMClientGroups` membership.

Data_XPMClientGroups

Retrieves the XPM client-group catalogue and best-effort membership. Answers "which clients are in group Y?". Returns one row per group { groupUuid, groupName, members:[{ clientUuid, clientName }] }. Membership degrades to catalogue-only (empty members) when XPM returns lean client rows.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`groupName`	string	No	Filter to a single group by name (case-insensitive). Omit for the full catalogue.

Data_XPMStaffMatching

Cross-source identity map (#1709): which XPM staff member is linked to which payroll employee and which XBert user profile. Read-only; queries the XPM warehouse directly (xbert.matchof_staff_uid_to_payroll_employee_uid). Returns one row per staff member including unmatched staff (isMatched=false) so agents can flag matching gaps. Returns identity/routing keys only — never payroll amounts.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`unmatchedOnly`	string	No	`true` to return only staff with no payroll match. Default returns all staff.

Row: staffUuid, staffName, xbertUserProfileId, payrollEmployeeUid, payrollEmployeeName, payrollTenantId, matchedBy, matchedDate, isMatched.

Use this for the staff↔payroll link, not the roster — Data_XPMStaff returns name/email/phone with no payroll mapping, and Data_Employees_* is the payroll roster with no XPM linkage.

Data_XPMClientTenantMap

Cross-source mapping (#1709): which XBert client tenant id each XPM client corresponds to (xpm.tbl_client.tenant_id). Read-only; queries the XPM warehouse directly. This is the bridge that lets an agent pivot from an XPM client/job to that client's ledger tools — feed the returned xbertClientTenantId in as clientTenantId to Data_Invoices_*, Data_Contacts_*, etc. Returns unmapped XPM clients too (isMapped=false).

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`clientName`	string	No	Case-insensitive substring filter on the XPM client name.
`mappedOnly`	string	No	`true` to return only XPM clients mapped to an XBert tenant. Default returns all.

Row: clientUuid, clientName, xbertClientTenantId (null when unmapped), isMapped.

Use this for the authoritative XPM→tenant link, not Data_XPMClients (broad portfolio, no tenant-id bridge) and not Data_FindSimilarClientTenants (fuzzy name resolution).

Data_XPMTimesheets_Summary

Summarises XPM time entries with job/task/staff context (aggregate view). Connect-scoped; the server fans out across XPM-enabled children.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`startDate`	string	Yes	Start date in `yyyy-MM-dd` format.
`endDate`	string	Yes	End date in `yyyy-MM-dd` format.
`staffName`	string	No	Filter to a staff member by name.
`question`	string	No	Natural-language analytical question (Query mode).

Data_XPMTimesheets_Search

Searches/lists XPM time entries as lean rows with cursor paging. Use to find specific time-entry UUIDs before Data_XPMTimesheets_Get.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`startDate`	string	Yes	Start date in `yyyy-MM-dd` format.
`endDate`	string	Yes	End date in `yyyy-MM-dd` format.
`searchTerm`	string	No	Case-insensitive substring across staffName, jobName, taskName, note.
`staffName`	string	No	Filter to a staff member by name.
`billable`	string	No	`true` / `false` to filter by billable status.
`invoiceStatus`	string	No	`Invoiced` or `Uninvoiced`.
`pageSize`	integer	No	Rows per page. Default 25, max 100.
`cursor`	string	No	Opaque pagination cursor from a previous call.

Data_XPMTimesheets_Get

Fetches full XPM time-entry records (note, start/end, webUrl) for up to 25 timesheet UUIDs. Foreign-tenant UUIDs are silently dropped.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`userProfileId`	string	Yes	Auto-injected by the Gateway from the authenticated session.
`startDate`	string	Yes	Start date in `yyyy-MM-dd` format (same window used to find the UUIDs).
`endDate`	string	Yes	End date in `yyyy-MM-dd` format.
`timesheetUuids`	string	Yes	Comma-separated timesheet UUIDs (up to 25).

Data_XPMWip_Summary

Summarises Xero Practice Manager WIP and recoverability, time-denominated. All values are minutes (with a derived hours field) — there are NO dollar / rate values anywhere (charge-out rates are not warehoused).

Returns three analytical sections:

Over-budget jobs — jobs whose summed task actual_minutes exceed their summed estimated_minutes, with the overrun in minutes/hours and an overrun percentage (null when the job has no estimate). Top-N by overrun plus a total count. Computed as of now over current task estimates/actuals.
Unbilled WIP — billable, uninvoiced time (billable = 1 AND invoice_task_uuid IS NULL) within the date window, grouped by client, by job, and by staff (top-N by minutes each), plus a grand total.
Aging — unbilled time bucketed by entry-date age: 0-30 / 31-60 / 61-90 / 90+ days.

Parameter	Type	Required	Description
`connectTenantId`	integer	Yes	Practice portal tenant ID.
`startDate`	string (yyyy-MM-dd)	Yes	Inclusive lower bound on the time-entry date — scopes the unbilled + aging sections only.
`endDate`	string (yyyy-MM-dd)	Yes	Inclusive upper bound on the time-entry date — scopes the unbilled + aging sections only.
`topN`	integer	No	Top-N cap for the over-budget list and each unbilled grouping. Default 20, clamped 1-100.
`openJobsOnly`	string (`true`/`false`)	No	`true` (default) restricts over-budget jobs to open jobs (state not Completed/Cancelled).

The startDate/endDate window scopes only the unbilled + aging sections; the over-budget section is always computed as of now.

Use this for WIP / recoverability / over-budget / unbilled questions. For the client portfolio use Data_XPMClients; for raw time entries use Data_XPMTimesheets_Summary. Returns SUMMARY_DATASET_TOO_LARGE when the unbilled scan exceeds 5,000 rows — narrow the date window.

Features -- Work Management

All Features tools are read-only (they read and manage work items within XBert but do not modify the accounting system).

Features_Review

Reviews team capacity and workload. Shows tasks due, in progress, and completed.

Parameter	Type	Required	Description
`dueDateLimit`	string	No	Days from today for due date filter. Default: 21 (single user), 14 (all users).

Features_ReviewActivity

Reviews team activity and history within the practice.

Parameter	Type	Required	Description
`question`	string	No	Natural language question about activity.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`endDate`	string	No	End date in `yyyy-MM-dd` format.

Features_UserActualTimeReview

Reviews actual time logged by a user.

Parameter	Type	Required	Description
`reviewPeriod`	string	No	Period to review, e.g., `This Week`. Default: `This Week`.
`billableStatus`	string	No	Filter: `All`, `Billable`, or `Non-Billable`. Default: `All`.
`workStatus`	string	No	Filter: `All`, `Completed`, or `In Progress`. Default: `All`.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`endDate`	string	No	End date in `yyyy-MM-dd` format.

Features_GetWork

Retrieves work items (tasks and XBert notifications) with flexible filtering.

Parameter	Type	Required	Description
`notificationId`	string	No	Specific notification ID to retrieve.
`datePeriodType`	string	No	Date field to filter by: `start` (default), `due`, `completed`, or `created`.
`notificationStatusId`	string	No	Filter by notification status ID.
`includeCompleted`	string	No	Whether to include completed notifications.
`filterTerm`	string	No	Search term to filter by title, summary, or content.
`startDate`	string	No	Start date for filtering.
`endDate`	string	No	End date for filtering.
`showOnlyAssignedToUser`	string	No	Show only notifications assigned to the user. Default: `true`.
`assignedUserProfileIds`	string	No	Comma-separated list of user profile IDs to filter by assignee.
`notificationStatusIds`	string	No	Comma-separated list of status IDs.
`notificationFilterType`	string	No	`all`, `xbert`, or `task`. Default: `all`.
`priorityFilterType`	string	No	`all`, `priority_only`, or `no_priority`. Default: `all`.
`timezone`	string	No	IANA timezone, e.g., `Australia/Sydney`.

Features_CountNotifications

Counts work items matching the specified filters.

Parameter	Type	Required	Description
`startDate`	string	Yes	Start date for filtering in `yyyy-MM-dd` format.
`endDate`	string	Yes	End date for filtering in `yyyy-MM-dd` format.
`datePeriodType`	string	No	Date field to filter by: `start`, `created`, `due`, `completed`.
`notificationFilterType`	string	No	`all`, `xbert`, or `task`. Default: `all`.
`priorityFilterType`	string	No	`all`, `priority_only`, or `no_priority`. Default: `all`.
`showOnlyAssignedToUser`	string	No	Default: `false` for count.
`assignedUserProfileIds`	string	No	Comma-separated list of user profile IDs.
`notificationStatusIds`	string	No	Comma-separated list of status IDs.
`timezone`	string	No	IANA timezone.

Features_CreateClientTask

Creates a new task (work item) in XBert.

Parameter	Type	Required	Description
`title`	string	Yes	Task title (max 290 characters).
`description`	string	No	Detailed task description (max 8000 characters).
`url`	string	No	Related URL or link (max 1500 characters).
`assignedUserProfileId`	string	No	User profile ID to assign the task to.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`dueDate`	string	No	Due date in `yyyy-MM-dd` format.
`processTagId`	string	No	Process or category tag ID.
`notificationStatusId`	string	No	Initial status ID.
`estimatedTime`	string	No	Estimated completion time in minutes.
`isPriority`	string	No	`true` for high priority, `false` for normal. Default: `false`.
`subTasks`	string	No	JSON array of subtask objects: `[{"message": "Task", "note": "Details"}]`. Max 50 subtasks.

Features_UpdateWorkItem

Updates one or more existing work items.

Parameter	Type	Required	Description
`workItemIds`	string	Yes	Work item ID(s). Single ID, comma-separated IDs for bulk update, or title text to search.
`notificationStatusId`	string	No	New status name (e.g., `Completed`, `In Progress`).
`dueDate`	string	No	New due date in `yyyy-MM-dd` format. Use `clear` to remove.
`assignedUserProfileId`	string	No	User profile ID to assign to.
`processTagId`	string	No	Process tag ID to set. Look up IDs via `Features_ListProcessTags`. Can be changed but not cleared.

Features_CreateClientNote

Creates a client note (document) in XBert. Supports rich markdown formatting.

Parameter	Type	Required	Description
`title`	string	Yes	Document title (max 290 characters).
`content`	string	Yes	Document content in markdown format (max 8000 characters).
`assignedUserId`	string	No	User ID to assign this document to.
`dueDate`	string	No	Due date in `yyyy-MM-dd` format.
`processTagId`	string	No	Process tag ID for categorisation.

Features_CreateClientTemplate

Creates a task template that can be used to generate recurring tasks.

Parameter	Type	Required	Description
`title`	string	Yes	Template name (max 290 characters).
`description`	string	No	Template description.
`tagId`	string	No	Category tag ID.
`estimatedTime`	string	No	Estimated completion time in minutes.
`isPriority`	string	No	`true` for high priority. Default: `false`.
`subtasks`	string	No	JSON array of subtask definitions.

Features_CreateClientTemplateSchedule

Creates a recurring schedule for a task template.

Parameter	Type	Required	Description
`templateTaskId`	string	Yes	The template ID to create recurring tasks from.
`name`	string	Yes	Schedule name (max 200 characters).
`frequencyType`	string	Yes	Recurrence frequency: `Daily`, `Weekly`, `Fortnightly`, `Monthly`, `Quarterly`, `Yearly`.
`clientTenants`	string	No	JSON array of client tenant IDs, e.g., `[123, 456]`.
`assignedUserProfileId`	string	No	User profile ID for auto-assignment.
`startDate`	string	No	Start date in `yyyy-MM-dd` format.
`isActive`	string	No	`true` to activate immediately. Default: `false`.

Features_ListTemplates

Lists available task templates with optional filtering.

Parameter	Type	Required	Description
`pageNumber`	string	No	Page number (1-based). Defaults to 1.
`processTagIds`	string	No	Comma-separated process tag IDs to filter by.
`clientTenantIds`	string	No	Comma-separated client tenant IDs to filter by scheduled clients.

Features_FindUserProfileByName

Searches for a user profile by name. Use this to look up user profile IDs for task assignment.

Parameter	Type	Required	Description
`userName`	string	Yes	The user name to search for.

Workflow -- Automation Actions

Workflow tools perform actions within the XBert platform. Unless otherwise noted, they are not read-only (they create or modify data in XBert).

Workflow_CreateClientNote

Creates a client note linked to a specific notification.

Safety	Not read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID to link the note to.
`noteTitle`	string	Yes	Note title (max 290 characters).
`noteContent`	string	Yes	Note content (max 8000 characters).
`processTagId`	long	No	Process tag ID for categorisation.

Workflow_GenerateReport

Generates a financial report for a client.

Safety	Not read-only

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`reportType`	string	Yes	Report type: `ProfitAndLoss`, `BalanceSheet`, or `TrialBalance`.
`startDate`	string	Yes	Start date in `yyyy-MM-dd` format.
`endDate`	string	Yes	End date in `yyyy-MM-dd` format.

Workflow_SendReminder

Sends a reminder on a notification with optional user mentions.

Safety	Not read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID to send a reminder on.
`reminderMessage`	string	Yes	Reminder message (max 4000 characters).
`mentionUserProfileIds`	string	No	Comma-separated user profile IDs to @mention.
`reminderType`	string	No	Type: `followup`, `overdue`, `action_required`, `information`. Default: `followup`.

Workflow_UpdateSubtaskStatus

Marks a subtask as completed with optional evidence.

Safety	Not read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`subtaskMessage`	string	Yes	The subtask text to find and mark as completed (partial match).
`completionNote`	string	No	Evidence or notes for the completed subtask (max 4000 characters).

Workflow_AttachFileToTask

Attaches a file to a task.

Safety	Not read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`filename`	string	Yes	The filename of the attachment.
`uploadPath`	string	Yes	The upload path in blob storage.
`contentType`	string	Yes	The MIME content type.
`contentLength`	integer	Yes	The file size in bytes.

Workflow_LinkNoteToNotification

Links an existing client note to a notification.

Safety	Not read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`clientNoteId`	long	Yes	The ID of the client note to link.

XBert -- Notification Resolution

XBert_GetResolveData

Retrieves the resolve options and data for an XBert notification.

Safety	Read-only

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`notificationId`	long	Yes	The XBert notification ID.

XBert_GetManualResolveInstructions

Retrieves manual resolve instructions for an XBert notification when automatic resolution is not available.

Safety	Read-only

Parameter	Type	Required	Description
`clientTenantId`	integer	Yes	The client tenant ID.
`notificationId`	long	Yes	The XBert notification ID.

Fabric -- Duplicate Detection

Fabric_CheckForDuplicateBill

Checks for potential duplicate bills in the accounting system.

Safety	Read-only

Parameter	Type	Required	Description
`tenantId`	integer	Yes	The tenant ID.
`notificationId`	long	No	Notification ID to extract bill data from.
`invoiceNumber`	string	No	Invoice number for matching.
`supplierTaxNumber`	string	No	Supplier tax number for matching.
`supplierBusinessName`	string	No	Supplier business name for matching.
`transactionTotal`	decimal	No	Transaction total for matching.
`issueDate`	string	No	Issue date in `yyyy-MM-dd` format.

Fabric_CheckForDuplicateBankTransaction

Checks for potential duplicate bank transactions.

Safety	Read-only

Parameter	Type	Required	Description
`tenantId`	integer	Yes	The tenant ID.
`notificationId`	long	No	Notification ID to extract transaction data from.
`contactBusinessName`	string	No	Contact business name for matching.
`contactTaxNumber`	string	No	Contact tax number for matching.
`transactionTotal`	decimal	No	Transaction total for matching.
`transactionDate`	string	No	Transaction date in `yyyy-MM-dd` format.
`transactionReference`	string	No	Bank feed reference string (primary matching key).

Product -- Work Item Actions

Product_AddComment

Adds a comment to a notification or work item.

Safety	Destructive

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`tenantId`	integer	Yes	The tenant ID.
`comment`	string	Yes	The comment text.

Product_UpdateStatus

Updates the status of a notification or work item.

Safety	Destructive

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`tenantId`	integer	Yes	The tenant ID.
`statusTypeId`	integer	No	The new status type ID.

AutomationPlan -- Checkpoint Management

AutomationPlan_GetCheckpoint

Retrieves the current checkpoint state for an automation plan.

Safety	Read-only

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`tenantId`	integer	Yes	The tenant ID.

AutomationPlan_UpdateCheckpoint

Updates the checkpoint state for an automation plan step.

Safety	Destructive

Parameter	Type	Required	Description
`notificationId`	long	Yes	The notification ID.
`tenantId`	integer	Yes	The tenant ID.
`stepName`	string	Yes	The automation step name.
`resultJson`	string	Yes	JSON result data for this checkpoint step.

XBert MCP Server -- Example Prompts

These examples show how to use the XBert MCP server with an AI assistant for common accounting workflows. Each example lists the tools the assistant will use behind the scenes.

1. Financial Health Check

Prompt:

"Review the balance sheet and profit and loss for Acme Corp and flag any anomalies or concerns."

Tools used:

Data_FindSimilarClientTenants -- Resolves "Acme Corp" to a client tenant ID
Data_FinancialStatements (statement=balanceSheet) -- Retrieves the balance sheet
Data_FinancialStatements (statement=profitAndLoss) -- Retrieves the profit and loss statement
Data_LedgerHealthSummary -- Gets the overall ledger health score

What happens: The assistant retrieves the financial statements, analyses them for unusual balances, year-over-year changes, or data quality issues, and presents a summary with flagged items.

2. Aged Receivables Review

Prompt:

"Show me the aged receivables for Smith & Partners and identify any invoices overdue by more than 90 days."

Tools used:

Data_FindSimilarClientTenants -- Resolves the client name
Data_AgedReceivables -- Retrieves aged receivables data
Data_Invoices -- Retrieves invoice details for overdue items

What happens: The assistant retrieves the aged receivables report, filters for items over 90 days, and presents the overdue invoices with contact details and amounts.

3. BAS Preparation (Australia)

Prompt:

"Help me prepare the BAS summary for Johnson Trading for the current quarter."

Tools used:

Data_FindSimilarClientTenants -- Resolves the client name
Data_BASSummary -- Retrieves the BAS summary for the current quarter
Data_ReconciliationStatus -- Checks reconciliation is complete before lodging

What happens: The assistant retrieves the BAS summary with GST collected, GST paid, and PAYG withholding figures. It may also check for unreconciled transactions that could affect the accuracy of the BAS.

4. Task Creation and Assignment

Prompt:

"Create a task for Sarah to review the bank reconciliation for Greenfield Industries by end of next week."

Tools used:

Features_FindUserProfileByName -- Looks up Sarah's user profile ID
Data_FindSimilarClientTenants -- Resolves "Greenfield Industries" to a client tenant ID
Features_CreateClientTask -- Creates the task with title, assignee, and due date

What happens: The assistant finds Sarah's profile, resolves the client, and creates a task assigned to Sarah with the appropriate due date. The task appears in Sarah's work queue in XBert.

5. XBert Notification Review and Resolution

Prompt:

"Show me all unresolved XBert notifications for Pacific Traders and help me resolve the top priority ones."

Tools used:

Data_FindSimilarClientTenants -- Resolves the client name
Features_GetWork -- Retrieves unresolved XBert notifications filtered by priority
XBert_GetResolveData -- Gets resolve options for each priority notification
XBert_GetManualResolveInstructions -- Gets step-by-step instructions if automatic resolution is not available

What happens: The assistant retrieves unresolved XBert notifications, sorts by priority, and walks through each one. For each notification, it retrieves the resolution options and guides the user through the resolution process -- whether that is an automatic fix or a set of manual steps to follow in the accounting system.