How to build an MCP server for Sage X3
Short answer
An MCP server for Sage X3 exposes a few read-only tools (item lookup, order status, stock, BOM) that call SData or web services using an X3 service identity. It works with Claude, ChatGPT and any other MCP client.
Model Context Protocol gives AI clients a standard way to call tools. For Sage X3 it means you build the integration once and reuse it across assistants, rather than writing a new plugin for each product.
The server is small. Its job is translation: an AI-friendly tool such as get_work_order_status on one side, and an SData query or web service call against Syracuse on the other, with permission checks between them.
Most of the design work is in choosing tools, not code. X3 has hundreds of objects, and exposing them all is how pilots fail.
What teams use it for
Item and stock lookup
Return description, units, stock by site and lot, and open demand for one item.
Sales order status
Return order header, lines, delivery state and invoicing state for an order number.
Purchase order and receipt view
List open lines with expected dates and receipts so buyers can ask about supplier delivery.
Work order and BOM explosion
Return components, required quantities and shortages for a work order or item.
Customer and supplier master lookup
Fetch contact, payment terms and credit status for a business partner.
Sage X3 integration surface
- SData 2.0 REST on Syracuse, using query parameters such as where clauses, count and paging to fetch published representations. Names depend on version and folder.
- Published SOAP web services that wrap X3 subprograms, useful when SData lacks an object.
- Syracuse authentication options, which vary by version and may include basic, token or single sign-on; confirm with your administrator.
- Folder and endpoint parameters in URLs, which select the production folder and so matter for multi-company installs.
- Read replica views for aggregates, called only through fixed, parameterised queries.
How it works
- 1
Inventory the objects
List which SData representations and web services actually exist in your folder. Test each with a read-only user.
- 2
Design a short tool list
Start with five to eight tools. Give each a clear name, typed arguments and a one-line description the model can use.
- 3
Implement with an MCP SDK
Use a TypeScript or Python SDK. Each tool calls SData, trims the result, and handles paging and errors in plain language.
- 4
Pick the transport
stdio for local testing on one desktop, streamable HTTP behind a gateway for shared, authenticated use.
- 5
Handle identity and scope
Map the caller to an X3 user or role and filter every query by their allowed sites. Reject any tool not in their role.
- 6
Add audit and limits
Log each call, cap rows returned, rate-limit, and keep the server read-only until reviewed.
Example flows
Stock and demand question
Trigger: A user asks any MCP client how much of an item is available
- Client calls get_item_stock with the item code and site.
- Server queries SData for stock and open demand.
- Server returns on-hand, allocated and incoming quantities.
Result: The assistant answers from live figures and can show the call it made.
Work order shortage check
Trigger: Supervisor asks why a work order cannot start
- Client calls get_work_order_components.
- Server returns required versus available quantities.
- Client calls list_open_po_lines for the short items.
Result: The supervisor sees the missing parts and when supply is due.
Keeping data on-prem
The server is just a process, so it can live on the same network as Syracuse, even on the same host cluster. Pair it with an open-weight model client such as one served via vLLM or Ollama, and no X3 data leaves the building. For remote users, front the server with your existing reverse proxy and VPN rather than opening ports. In partner-hosted X3 you may only reach the API over a tunnel, so test latency early because MCP tools can chain several calls per question.
Security checklist
- Read-only tools first; any write tool needs a separate approval step and its own role.
- Never allow free-form SQL or arbitrary SData URLs from the model.
- Pass the end user's identity, not a shared admin, wherever possible.
- Cap rows and fields returned, and redact sensitive columns server-side.
- Write an immutable audit log of calls, arguments and the X3 user used.
Ways to get it done
Open-source or community MCP connector
Effort: Days to assess.
Check whether one exists for Sage X3 and review its code before trusting it. Availability varies.
Build your own over SData
Effort: Two to four weeks for a first set.
Best control; suits teams with X3 and API skills.
Netray with your X3 partner
Effort: A scoped pilot.
When you want tested tools, permissions and audit with on-prem models.
Pitfalls
- !Exposing a generic query tool that lets the model roam the whole schema.
- !Returning full records so the model drowns in fields it does not need.
- !Hard-coding one folder and then answering for the wrong company.
- !No paging, so large item or order lists time out.
- !Forgetting the session and licence cost of API users in your Sage licence terms.
Frequently asked questions
What is an MCP server in plain terms?
It is a small program that offers named tools to an AI client, such as get_item_stock. The client decides when to call them. You write the tools once and any compatible assistant can use them, which avoids rebuilding the integration for each AI product.
Should I use stdio or HTTP?
Use stdio for local development and single-user trials. Use HTTP with authentication for shared team use, running behind your gateway. HTTP adds deployment work but gives central logging, access control and one place to update.
Which Sage X3 data should I expose first?
Start with items, stock, sales order status, purchase order status and work orders. They answer most day-to-day questions and carry less risk than finance or pricing data. Add more only after reviewing logs from real use.
Can the same server work with ChatGPT and Claude?
Often yes, because both support MCP in some product tiers, though features differ by plan and change over time. The tool layer stays the same, so only client configuration varies. Check current documentation for each product.
Will it respect X3 user rights?
Only if you design it to. Pass the user's identity or role through, filter by site, and reject tools outside the role. A shared super-user account would bypass your X3 permission model.
Want MCP server working on your Sage X3?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment