How to build an MCP server for Acumatica
Short answer
An Acumatica MCP server is a small service that exposes named, read-only tools backed by the REST API and OData Generic Inquiries, authenticates through an OAuth Connected Application, and serves any MCP client over stdio or HTTP. Design the tools around questions users ask, not around entities.
Model Context Protocol gives AI clients a standard way to call tools and read resources. For Acumatica, an MCP server turns a REST API with hundreds of entities into a handful of purposeful operations: look up an order, check stock, list late POs.
The value is reuse. One server serves Claude, ChatGPT, IDE assistants and your own agents. Without it, every new AI feature rebuilds the same authentication, pagination and payload shaping.
This page is the engineering view: what to expose, how to authenticate, how to deploy, and what to watch.
What teams use it for
Order and shipment status lookup
Customer service asks for an order's status, lines, shipments and invoice state in one tool call, without opening four screens.
Item availability by warehouse
A stock tool returns on-hand, allocated and on-order by warehouse and location for an inventory ID, with lot or serial counts where tracked.
Bill of material and routing explorer
Engineers ask for a multi-level BOM, where-used and operations for a revision, all through a Generic Inquiry backed tool.
Vendor performance view
A tool summarising on-time receipt rate, price changes and open PO value per vendor for buyers prepping a review.
Developer assistant for customizations
A resource exposes the endpoint schema and customization notes so a coding assistant writes correct REST calls instead of guessing field names.
Governed draft creation
A write tool that creates an unreleased sales order or purchase requisition for approval, enabled only after the read tools are proven.
Acumatica integration surface
- Contract-based REST API at /entity/Default/<version>/ with $filter, $select, $expand, $top and $skip; you can add custom endpoints in Web Service Endpoints (SM207060).
- Generic Inquiries (SM208000) exposed via OData, which are the best backing for joined read tools like stock by location.
- Connected Applications (SM303010) for OAuth 2.0 clients with defined scopes; the exact scope names depend on version.
- Tenant and branch context passed at login; multi-tenant instances need the tenant name in every authentication request.
- Direct SQL Server access exists on-prem but is not supported for writes, and reading it bypasses Acumatica role checks, so avoid it for the server's main path.
How it works
- 1
List the questions, then the tools
Interview users and write 10 to 15 real questions. Group them into five to eight tools with typed parameters, such as get_sales_order(order_nbr, order_type).
- 2
Create the Acumatica identity
Make an integration user with a read role, register a Connected Application and record the client ID and secret in a vault.
- 3
Implement with an MCP SDK
Use the Python or TypeScript SDK. Each tool validates input, builds a bounded query (always $top), calls Acumatica and returns trimmed JSON with units.
- 4
Choose transport
Stdio for local single-user use such as a developer's desktop. Streamable HTTP behind your gateway for shared use, with TLS and per-user auth.
- 5
Handle sessions and limits
Reuse tokens, log out idle sessions and queue calls. Acumatica licenses limit concurrent requests, and leaked sessions block real users.
- 6
Add audit and test
Log tool, caller, arguments and row counts. Write tests against a sandbox tenant and rerun them when upgrading Acumatica.
Example flows
Stock check from a chat client
Trigger: User asks: do we have 200 of part 4471-B in Chicago?
- Client calls stock_by_warehouse(inventory_id=4471-B).
- Server queries the stock inquiry via OData, filtered to the item.
- It returns on-hand, available and on-order per warehouse.
- Client answers with the Chicago quantity and the next receipt date.
Result: A sourced answer in seconds, with the tool result visible for verification.
Draft requisition with approval
Trigger: Planner approves a proposed replenishment
- Client calls create_draft_requisition with item, quantity and need date.
- Server checks the role allows drafts and quantity is under a limit.
- It posts an unreleased document through the REST API.
- Server returns the reference number for review in Acumatica.
Result: A draft waiting for human release, with no direct impact on the ledger.
Keeping data on-prem
The server is a plain process, so it deploys next to an on-prem Acumatica on a VM or container host, reaches the IIS endpoint over the internal network and exposes itself only to internal clients or through a VPN. Pair it with a locally hosted model and no data leaves the site. For cloud-hosted Acumatica, run the server in your own cloud account and restrict inbound access to your identity provider. Keep secrets in a vault, and avoid shipping Acumatica credentials to desktop clients.
Security checklist
- Scope the integration role to the screens each tool needs and nothing more.
- Keep write tools off by default and enable per environment.
- Enforce server-side row limits and field allow-lists regardless of what the client requests.
- Authenticate users to the MCP server, then map them to roles, rather than sharing one identity.
- Treat all text returned from Acumatica as untrusted when it goes back to a model.
Ways to get it done
Use a community or marketplace MCP server
Effort: Days
Fits quick trials; I am not aware of an official Acumatica one, so audit permissions and maintenance before use.
Build your own
Effort: 2 to 4 weeks for read-only tools
Fits teams with API and OAuth experience wanting control over tool design.
Netray-built with hardening
Effort: A few weeks for a scoped build
Fits those needing governance, audit and private deployment around the server.
Pitfalls
- !Mirroring every entity as a tool; models choose badly from large menus.
- !Unbounded queries that page through hundreds of thousands of stock records.
- !Ignoring endpoint version drift, which breaks field names after upgrades.
- !Sharing one session across users so audit shows only the service account.
- !Forgetting to log out API sessions, consuming licensed concurrency.
Frequently asked questions
What is an MCP server for an ERP?
It is a service that exposes your ERP's functions as named tools to AI clients through the Model Context Protocol. The client decides when to call them; the server controls what each can do, handling authentication, limits and logging.
Which Acumatica API should the server use?
Use OData Generic Inquiries for joined reads and the contract-based REST API for entity lookups and draft writes. Avoid the legacy screen-based SOAP API for new work, and avoid direct SQL for anything user-facing.
Stdio or HTTP transport?
Stdio suits one developer running the server locally. HTTP suits shared deployments with central auth, logging and rate limits. Most companies end up on HTTP once more than a few people use it.
Does it work with ChatGPT as well as Claude?
Any client that supports MCP can use it, and support in ChatGPT and other tools has been growing. Check each client's current connector rules, since remote server requirements differ.
How do I stop it changing data?
Give the Acumatica user read-only rights, expose only read tools and keep write tools disabled. If you add writes, limit them to unreleased drafts and require human approval before release.
Want MCP server working on your Acumatica?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment