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 assessmentTry it here, free
Acumatica Sales Order REST JSON Template
Generate the PUT request URL and JSON body to create a sales order with two lines through Acumatica's contract-based REST API.
Keep exploring
Free tools
- Acumatica Sales Order REST JSON TemplateGenerate the PUT request URL and JSON body to create a sales order with two lines through Acumatica's contract-based REST API.
- Acumatica REST API Python Script GeneratorProduce a ready-to-run Python script for the Acumatica contract-based REST API: login, PUT a record, then logout.
- Acumatica REST API URL BuilderGenerate contract-based REST URLs and the login call for any Acumatica entity, with $filter, $select, $expand, $top and $skip filled in for you.
ERP fixes and how-tos
- Acumatica REST API 401 Unauthorized and API Login Limit: How to FixFix Acumatica REST API 401 errors and API login limit failures: correct auth body, tenant name, OAuth connected app, and always log out to free API sessions.
- Acumatica Manufacturing Data Collection: Labor and Production EntryHow shop floor data collection works in Acumatica Manufacturing: clock, labor, move and material entry, who should enter what and how to keep data clean.
- Acumatica Manufacturing: Scheduling, Kiosk and EstimatingHow Acumatica Manufacturing handles production scheduling, the schedule board, shop floor kiosk entry and estimating, and what to set up first.
AI on your ERP
- AI for Acumatica Manufacturing Edition, Built on Your Own DataAdd AI to Acumatica Manufacturing Edition without giving up control of your shop and cost data. Private LLMs and agents grounded in your Acumatica instance.
- AI for Acumatica Inventory and Purchasing: Stock, Reorder and Vendor Questions AnsweredAI for Acumatica inventory and purchasing: reorder risk, receipts, vendor lead times and stock questions answered in plain English via the REST API, read-only.
Integrations
- How to use Claude with AcumaticaUse Claude with Acumatica through MCP connectors, the Anthropic API, AWS Bedrock or Vertex AI, plus the on-prem alternative when data must stay inside.
- How to use ChatGPT with AcumaticaConnect ChatGPT to Acumatica: custom GPT actions over the REST API, exports versus live access, enterprise data controls and when a private model is better.