# How to build an MCP server for Acumatica > Source: https://netray.co/integrations/acumatica-mcp-server > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: Integrations ## 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. ## System Acumatica ## Capability mcp-server ## Intro 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. ## Use Cases ### Order and shipment status lookup **Description:** 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 **Description:** 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 **Description:** Engineers ask for a multi-level BOM, where-used and operations for a revision, all through a Generic Inquiry backed tool. ### Vendor performance view **Description:** A tool summarising on-time receipt rate, price changes and open PO value per vendor for buyers prepping a review. ### Developer assistant for customizations **Description:** 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 **Description:** A write tool that creates an unreleased sales order or purchase requisition for approval, enabled only after the read tools are proven. ## System Surface - Contract-based REST API at /entity/Default// 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 ### List the questions, then the tools **Detail:** 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). ### Create the Acumatica identity **Detail:** Make an integration user with a read role, register a Connected Application and record the client ID and secret in a vault. ### Implement with an MCP SDK **Detail:** Use the Python or TypeScript SDK. Each tool validates input, builds a bounded query (always $top), calls Acumatica and returns trimmed JSON with units. ### Choose transport **Detail:** 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. ### Handle sessions and limits **Detail:** Reuse tokens, log out idle sessions and queue calls. Acumatica licenses limit concurrent requests, and leaked sessions block real users. ### Add audit and test **Detail:** 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? **Steps:** - 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 **Steps:** - 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. ## 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 - 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. ## Options ### Use a community or marketplace MCP server **Fit:** Fits quick trials; I am not aware of an official Acumatica one, so audit permissions and maintenance before use. **Effort:** Days ### Build your own **Fit:** Fits teams with API and OAuth experience wanting control over tool design. **Effort:** 2 to 4 weeks for read-only tools ### Netray-built with hardening **Fit:** Fits those needing governance, audit and private deployment around the server. **Effort:** A few weeks for a scoped build ## 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. ## Faq ### What is an MCP server for an ERP? **Answer:** 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? **Answer:** 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? **Answer:** 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? **Answer:** 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? **Answer:** 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. ## Search terms acumatica mcp server, mcp server for acumatica, acumatica model context protocol, acumatica mcp, build mcp server erp, acumatica rest api mcp, acumatica oauth mcp, acumatica ai tools, connect ai to acumatica, acumatica mcp claude chatgpt --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json