MCP4Acumatica -- Tool Reference

Complete specification for all 51 tools available in the MCP4Acumatica (v0.53.0).

Tool annotations (0.53.0). Every tool carries MCP annotations and a human-readable title. All tools are readOnlyHint: true except the write tools (readOnlyHint: false, destructiveHint: true, idempotentHint: false) and acumatica_clear_cache (readOnlyHint: false, idempotentHint: true — it clears the server's own metadata cache, not Acumatica data). openWorldHint is false throughout. Claude treats these as hints; Microsoft 365 Copilot federated connectors require readOnlyHint and withhold unannotated tools.

Visible tool count. 51 tools are registered, but the write tool is hidden from tools/list while write tools are disabled (the default), so clients see 50.

The **Endpoint:** paths below show the default deployment values — the Default endpoint name and contract version 25.200.001. The base /entity/{name}/{version} is governed by the ACUMATICA_ENDPOINT_NAME (default Default) and ACUMATICA_ENDPOINT_VERSION env vars, so your instance's paths may differ.

Table of Contents

• Utility / Discovery Tools
• Write Tools
• Schema Knowledge Tools
• Documentation Tools
• Core
• Financial / Accounting
• Inventory & Warehouse
• Purchasing
• Projects
• Service & Field
• Sales & CRM
• Shipping & Fulfillment
• HR & Payroll
• CRM Activities

Utility / Discovery Tools

acumatica_describe_entity

Discover the fields, types, and sub-entities for any Acumatica entity. Use this before acumatica_list_entities to learn what fields are available for filtering, sorting, and selection. Schemas are cached for 24 hours — if an Acumatica admin just modified the entity (added a custom field, etc.), call acumatica_clear_cache with target=schema:EntityName first.

Endpoint: GET /entity/Default/25.200.001/{entityName}/$adHocSchema

acumatica_list_entities

List or search any Acumatica entity in the contract-based Default endpoint with OData filtering, sorting, and field selection. Always pass filterExpression to scope queries — do not retrieve all records from large entities.

Restrictions:

• Auth/role metadata entities (User, UserRole, Role, etc.) are intentionally blocked and return an error.
• expand accepts only single-level sub-entities — nested paths like Details/Tax are rejected.
• Some entities reject $select on certain fields and 500; the tool auto-retries without $select and returns the result with a warning if that happens.

Endpoint: GET /entity/Default/25.200.001/{entityName}?$filter=...&$top=...&$select=...&$orderby=...&$expand=...

Truncation semantics: When the result set hits the per-query max (ACUMATICA_MAX_RECORDS, default 1000, runtime-overridable via the admin console), the response is wrapped as { results, truncated: true, paginationSupported: false, actionRequired: "..." }. The model is instructed to stop and ask the user for a narrower filterExpression rather than calling the tool again.

acumatica_run_inquiry

Execute any configured Generic Inquiry (GI) in Acumatica. Use this for custom reports and cross-entity queries configured by your Acumatica administrator. Use acumatica_list_generic_inquiries to discover GI names and acumatica_describe_inquiry to get field schema before calling this tool.

Endpoint: GET /t/{Company}/api/odata/gi/{inquiryName}?$filter=...&$top=...&$select=...

Truncation semantics: Same as acumatica_list_entities — when results hit the max, the response includes truncated: true, paginationSupported: false, and actionRequired text telling the model to ask the user for a narrower filter rather than calling again.

Calculated columns are refused in filters (0.49.0): a $filter referencing a calculated GI column (an =… expression in the inquiry design) makes Acumatica return HTTP 200 with an empty body — not an error, not an empty list. For curated GIs the registry flags expression columns, and this tool refuses such a filter before contacting Acumatica, returning an invalid_filter envelope naming the offending columns and listing the stored filterableFields to rewrite against. Filter on stored columns (keys, dates, statuses, codes) and apply conditions on calculated columns to the returned rows client-side. See OData filtering.

GI opt-in gate (0.37.0): Instances accumulate many GIs built for human screens; exposing them all floods the model's context and degrades GI selection — and a parameterized GI exposed via OData returns silently wrong data (queried without its parameters, Acumatica returns default/unfiltered rows with no error), so curating which GIs the assistant can reach is a data-correctness safeguard, not just tidiness (full rationale + setup: Generic Inquiries). If your Acumatica administrator has configured the GI registry (the MCPGIs/MCPGIFields feed GIs), only inquiries explicitly flagged ExposedtoMCP are available — run_inquiry, describe_inquiry, and list_generic_inquiries all enforce it, and an unexposed GI returns a "not exposed to the AI assistant" error. When the registry is not configured, the gate is inactive: list_generic_inquiries returns no GIs (discovery is suppressed — the model isn't handed an uncurated menu), and a GI can only be run by exact name via run_inquiry / describe_inquiry. Exposed GIs may also carry curated descriptions and $metadata-accurate field types, surfaced by describe_inquiry/list_generic_inquiries. Independently of the gate, run_inquiry and describe_inquiry refuse any parameterized GI (querying/sampling one over OData returns silently wrong data). Fixed-width key values are trimmed in all GI output.

acumatica_list_generic_inquiries

List all Generic Inquiries (GIs) exposed via OData in Acumatica. Returns inquiry names. Use this to discover available GI names before calling acumatica_run_inquiry.

Endpoint: GET /t/{Company}/api/odata/gi (OData service document)

Returns: Array of { inquiryName, url } for each OData-exposed GI. Client-side name filtering is applied when titleFilter is provided.

acumatica_describe_inquiry

Returns the field schema for a Generic Inquiry (GI) exposed via OData. Field names and types are inferred from a single live sample row, so types may be approximate (a column that is null in the sample reports as unknown) and a GI that returns no rows yields an empty field list. Curated GIs (see the GI opt-in gate above) instead return authoritative $metadata names/types with curated descriptions, and mark calculated (expression) columns with calculated: true — those columns cannot be used in a run_inquiry filterExpression (Acumatica fails such filters with an empty response, so run_inquiry refuses them up front). Use this before calling acumatica_run_inquiry to know which fields are available for filtering and selection. For authoritative entity schemas (not GIs), use acumatica_describe_entity instead.

Endpoint: GET /t/{Company}/api/odata/gi/{inquiryName}?$top=1

Approach: Probes the GI via OData with $top=1 to retrieve a sample row and infers field names and data types from the response.

Returns: { inquiryName, fields: [{ fieldName, dataType }], sampleRow, note }.

Error handling:

• GI not found (404): returns descriptive error suggesting acumatica_list_generic_inquiries
• GI requires filters (400): returns guidance to use acumatica_run_inquiry with a filter
• Empty results: returns empty field list with a note

acumatica_clear_cache

Clear cached metadata (entity schemas, GI lists, GI field schemas). Use when Acumatica customizations have changed and cached schema data is stale. With no arguments, clears all cached metadata.

Caching details: Entity schemas are cached for 24 hours. GI lists, GI metadata, and GI field schemas are cached for 1 hour. Cache is stored in KV with cache: key prefix.

Returns: { cleared: [...] } listing the cache keys that were removed.

Write Tools

Write tools mutate Acumatica data. They are disabled by default and must be explicitly enabled by an administrator at /docs/admin/settings (toggle "Enable Write Tools"). While disabled, write tools are hidden from tools/list (since 0.53.0), so clients don't see them at all; the server also refuses any call to one. Enabling takes effect on the next MCP session (the tool list is built once per session), and clients that cache the tool list may need a disconnect/reconnect. All write tools use a two-phase confirmation pattern to prevent accidental mutations:

1. Call the tool without confirm (or with any value other than 'true') to get a dry-run preview. The preview shows exactly what would be written in Acumatica's {value: X} wire format -- no data is changed.
2. Call again with confirm: 'true' to commit the change.

Every mutation attempt (dry-run and committed) is logged to the R2 audit trail with the redacted payload, entity, record key, and dryRun flag. The log appears in the admin console under /docs/admin.

acumatica_create_or_update_customer

Create a new Customer or update an existing one. Uses PUT-as-upsert: if CustomerID is provided the existing record is updated; if omitted Acumatica assigns an auto-number ID and a new record is created.

Allowed top-level fields: CustomerID, CustomerName, CustomerClass, Status, Email, Phone1, MainContact

MainContact accepts a nested object whose inner fields are themselves allowlisted: Email, Phone1, Address1, Address2, City, State, PostalCode, Country. Any other nested field is rejected before anything is sent to Acumatica.

Examples:

Create a new customer (Acumatica assigns the ID):

{ "CustomerName": "Acme Corp", "CustomerClass": "DEFAULT", "Email": "accounts@acme.com" }

Update an existing customer's status:

{ "CustomerID": "C000123", "Status": "Inactive" }

Returns (dry-run): { dryRun: true, willWrite: <wrapped-payload>, target: "PUT Customer", note: "..." }

Returns (committed): { action: "upsert", entity: "Customer", recordKey: "<CustomerID>", result: <unwrapped-response> }

Schema Knowledge Tools

Offline schema discovery for building integrations and customizations — answered from an index built from your instance's own swagger.json, with no record query. See Schema Knowledge for how the index is built. The three index-backed tools appear only when the schema index is present; acumatica_explain_gi_xml is always available.

acumatica_search_schema

Find entities by name/keyword and/or locate which entities contain a given field.

* Provide at least one of query / field.

Returns: { results: [{ name, tag, fieldCount, matchedOn }], resultCount, note }.

acumatica_get_schema_entity

Full offline schema for one entity: fields (name + type), available actions, and expandable sub-entities ($expand targets).

Returns: { name, tag, fields, actions, subCollections, expandHint }. For the authoritative live schema (incl. just-added custom fields), use acumatica_describe_entity.

acumatica_list_schema_entities

Browse the entity catalog, optionally filtered by a name/module prefix.

Returns: { entities: [{ name, tag, fieldCount }], count }.

acumatica_explain_gi_xml

Summarize the structure of a pasted Generic Inquiry definition XML (from SM208000): tables, relations/joins, parameters, filters, grouping/sorting, output columns. A reading aid that parses the XML you provide — it does not query Acumatica.

Returns: { root, title?, sections, otherElements, note }.

Documentation Tools

Search + retrieval over the official Acumatica documentation (user guides, form/screen reference, release notes) for your instance's release — answered from an index the operator builds from their own licensed documentation download, with no tenant data access. See Documentation Tools for setup. Both tools appear only when the documentation index is present, and their output bypasses sensitive-field redaction (vendor documentation, not tenant records).

acumatica_search_docs

Search the documentation by section heading and Form ID (not body text — query with feature terminology as the docs would title it, not full sentences).

* Provide at least one of query / formId.

Returns: { results: [{ chunkId, guide, path, formId?, matchedOn }], resultCount, release, note }.

acumatica_get_doc_section

Read documentation text — one section by chunkId, or a screen's full reference by Form ID.

Returns (chunkId): { chunkId, guide, path, formId?, text, prev?, next?, release } — prev/next allow browsing adjacent sections. Returns (Form ID): { formId, sectionCount, sections: [{ chunkId, path, text }], release } plus truncated/remainingSections when a large screen exceeds the size cap.

Core

acumatica_get_customer

Retrieve a customer record by Customer ID.

Endpoint: GET /entity/Default/25.200.001/Customer/{customerID} Expands: CreditVerificationRules, MainContact, PrimaryContact, BillingContact

Returns: Customer name, status, billing/shipping addresses, primary contact, credit terms, and balance.

acumatica_get_vendor

Retrieve a vendor record by Vendor ID.

Endpoint: GET /entity/Default/25.200.001/Vendor/{vendorID} Expands: MainContact, PrimaryContact

Returns: Vendor name, status, payment terms, tax info, and primary contact.

acumatica_get_sales_order

Retrieve a sales order by order type and order number.

Endpoint: GET /entity/Default/25.200.001/SalesOrder/{orderType}/{orderNbr} Expands: Details

Returns: Header info, line items, totals, shipping details, and status.

Financial / Accounting

acumatica_get_invoice

Retrieve an AR invoice by type and reference number.

Endpoint: GET /entity/Default/25.200.001/Invoice/{type}/{referenceNbr} Expands: Details, TaxDetails

Returns: Customer, amounts, balance, line items, tax details, due date, and status.

acumatica_get_bill

Retrieve an AP bill by type and reference number.

Endpoint: GET /entity/Default/25.200.001/Bill/{type}/{referenceNbr} Expands: Details, TaxDetails

Returns: Vendor, amounts, balance, line items with PO linkage, tax details, due date, and status.

acumatica_get_journal_transaction

Retrieve a GL journal transaction batch by batch number.

Endpoint: GET /entity/Default/25.200.001/JournalTransaction/{batchNbr}

Returns: Module, ledger, post period, and detail lines with account, debit/credit amounts.

acumatica_get_payment

Retrieve an AR payment by type and reference number.

Endpoint: GET /entity/Default/25.200.001/Payment/{type}/{referenceNbr} Expands: DocumentsToApply, OrdersToApply

Returns: Customer, payment amount, method, applied documents/orders, available balance, and status.

acumatica_get_account

Retrieve a GL account from the chart of accounts.

Endpoint: GET /entity/Default/25.200.001/Account/{accountCD}

Returns: Account type, class, group, description, currency, and active status.

acumatica_get_check

Retrieve an AP check (vendor payment) by type and reference number.

Endpoint: GET /entity/Default/25.200.001/Check/{type}/{referenceNbr} Expands: Details, History

Returns: Vendor, payment amount, method, cash account, unapplied balance, and status.

Inventory & Warehouse

acumatica_get_stock_item

Retrieve a stock item by inventory ID.

Endpoint: GET /entity/Default/25.200.001/StockItem/{inventoryID} Expands: WarehouseDetails, VendorDetails

Returns: Description, item class, pricing (default, MSRP, cost), UOMs, warehouse details with qty on hand, and vendor details.

acumatica_get_non_stock_item

Retrieve a non-stock item (service, labor, expense) by inventory ID.

Endpoint: GET /entity/Default/25.200.001/NonStockItem/{inventoryID}

Returns: Description, item class, pricing, UOMs, and posting settings.

acumatica_get_inventory_quantity_available

Retrieve real-time available quantity for an inventory item across all warehouses.

Endpoint: GET /entity/Default/25.200.001/InventoryQuantityAvailable/{inventoryID} Expands: Results

Returns: On-hand, available, and allocated quantities.

acumatica_get_inventory_summary

Retrieve aggregated inventory balances for an item, optionally filtered by warehouse.

Endpoint: GET /entity/Default/25.200.001/InventorySummaryInquiry/{inventoryID} (with optional warehouse filter) Expands: Results

Returns: Summary rows with on-hand, available, and other quantity breakdowns.

acumatica_get_warehouse

Retrieve a warehouse by ID.

Endpoint: GET /entity/Default/25.200.001/Warehouse/{warehouseID} Expands: Locations

Returns: Description, active status, default locations, and all warehouse locations.

acumatica_get_item_class

Retrieve an item class by class ID.

Endpoint: GET /entity/Default/25.200.001/ItemClass/{classID}

Returns: Item type, default UOMs, warehouse, valuation method, posting class, and availability calculation rule.

Purchasing

acumatica_get_purchase_order

Retrieve a purchase order by type and order number.

Endpoint: GET /entity/Default/25.200.001/PurchaseOrder/{type}/{orderNbr} Expands: Details

Returns: Vendor, line items with quantities and costs, totals, terms, status, and promised date.

acumatica_get_purchase_receipt

Retrieve a purchase receipt by type and receipt number.

Endpoint: GET /entity/Default/25.200.001/PurchaseReceipt/{type}/{receiptNbr} Expands: Details

Returns: Vendor, line items with received quantities and costs, linked PO references, and warehouse.

Projects

acumatica_get_project

Retrieve a project by project ID.

Endpoint: GET /entity/Default/25.200.001/Project/{projectID}

Returns: Description, status, customer, template, financials (assets, liabilities, income, expenses).

acumatica_get_project_task

Retrieve a project task by project ID and task ID.

Endpoint: GET /entity/Default/25.200.001/ProjectTask/{projectID}/{projectTaskID}

Returns: Description, status, and whether it is the default task.

acumatica_get_project_budget

Retrieve a project budget line by project, task, and account group.

Endpoint: GET /entity/Default/25.200.001/ProjectBudget/{projectID}/{projectTaskID}/{accountGroup}

Returns: Original/revised budgeted amounts, actuals, committed amounts, and completion percentage.

acumatica_get_project_transaction

Retrieve a project transaction by module and reference number.

Endpoint: GET /entity/Default/25.200.001/ProjectTransaction/{module}/{referenceNbr} Expands: Details

Returns: Detail lines with account, amount, project/task, employee, and quantities.

Service & Field

acumatica_get_case

Retrieve a support case by case ID.

Endpoint: GET /entity/Default/25.200.001/Case/{caseID}

Returns: Subject, status, priority, severity, business account, contact, owner, SLA, time spent, and resolution details.

acumatica_get_service_order

Retrieve a field service order by type and number.

Endpoint: GET /entity/Default/25.200.001/ServiceOrder/{serviceOrderType}/{serviceOrderNbr} Expands: Details, Appointments

Returns: Customer, status, priority, estimated/actual durations, totals, appointments, and line items.

acumatica_get_appointment

Retrieve a field service appointment by type and number.

Endpoint: GET /entity/Default/25.200.001/Appointment/{serviceOrderType}/{appointmentNbr} Expands: Details, Staff, Logs

Returns: Scheduled/actual dates and durations, customer, staff, services, cost, profit, and status.

Sales & CRM

acumatica_get_contact

Retrieve a CRM contact by contact ID.

Endpoint: GET /entity/Default/25.200.001/Contact/{contactID}

Returns: Name, email, phone, job title, company, business account, address, status, owner, and source.

acumatica_get_business_account

Retrieve a business account (prospect, customer, or vendor) by ID.

Endpoint: GET /entity/Default/25.200.001/BusinessAccount/{businessAccountID} Expands: MainContact

Returns: Name, type, status, class, main address, main contact, parent account, and owner.

acumatica_get_opportunity

Retrieve a sales opportunity by ID.

Endpoint: GET /entity/Default/25.200.001/Opportunity/{opportunityID} Expands: Products, TaxDetails

Returns: Subject, stage, status, amount, discount, total, business account, contact, products, source, and estimation date.

acumatica_get_lead

Retrieve a marketing lead by lead ID.

Endpoint: GET /entity/Default/25.200.001/Lead/{leadID}

Returns: Name, email, phone, company, status, source, class, owner, address, and qualification date.

acumatica_get_salesperson

Retrieve a salesperson by ID.

Endpoint: GET /entity/Default/25.200.001/Salesperson/{salespersonID}

Returns: Name, active status, default commission percentage, and sales subaccount.

Shipping & Fulfillment

acumatica_get_shipment

Retrieve a shipment by shipment number.

Endpoint: GET /entity/Default/25.200.001/Shipment/{shipmentNbr} Expands: Details, Packages, Orders

Returns: Customer, warehouse, ship via, shipped quantities/weight/volume, packages with tracking numbers, line items, and freight details.

acumatica_get_sales_invoice

Retrieve a sales invoice by type and reference number.

Endpoint: GET /entity/Default/25.200.001/SalesInvoice/{type}/{referenceNbr} Expands: Details, TaxDetails

Returns: Customer, amounts, balance, line items with SO/shipment linkage, tax details, and due date.

HR & Payroll

acumatica_get_employee

Retrieve an employee by employee ID.

Endpoint: GET /entity/Default/25.200.001/Employee/{employeeID} Expands: ContactInfo, EmployeeSettings, FinancialSettings

Returns: Name, status, contact info, employee settings, and financial settings.

acumatica_get_expense_claim

Retrieve an expense claim by reference number.

Endpoint: GET /entity/Default/25.200.001/ExpenseClaim/{refNbr} Expands: Details, TaxDetails

Returns: Claimant, date, total, line items with amounts, tax details, approval status, and customer/department.

acumatica_get_time_entry

Retrieve a time entry by ID.

Endpoint: GET /entity/Default/25.200.001/TimeEntry/{timeEntryID}

Returns: Employee, date, project/task, time spent, billable time, overtime, earning type, cost rate, and approval status.

CRM Activities

acumatica_get_email

Retrieve a CRM email activity by note ID.

Endpoint: GET /entity/Default/25.200.001/Email/{noteID}

Returns: Subject, from/to/cc/bcc, body, mail status, related entity, and timestamps.

acumatica_get_event

Retrieve a CRM event by note ID.

Endpoint: GET /entity/Default/25.200.001/Event/{noteID} Expands: Attendees

Returns: Summary, start/end dates, location, priority, category, attendees, related entity, and show-as status.

acumatica_get_activity

Retrieve a CRM activity by note ID.

Endpoint: GET /entity/Default/25.200.001/Activity/{noteID}

Returns: Summary, type, status, date, owner, related entity, and body.

acumatica_get_task

Retrieve a CRM task by note ID.

Endpoint: GET /entity/Default/25.200.001/Task/{noteID}

Returns: Summary, status, priority, due date, completion percentage, related activities/tasks, and owner.