How to build an MCP server for Oracle NetSuite
Short answer
An MCP server for NetSuite is a small service that publishes a handful of typed tools, each backed by a fixed SuiteQL query or RESTlet, and authenticates to NetSuite with a dedicated role. Ship read-only tools first, use HTTP transport for shared use, and log every call.
Model Context Protocol gives AI clients a standard way to discover and call tools. For NetSuite that means you write the integration once, then Claude, ChatGPT and in-house assistants can all use it. The alternative is a separate plugin per model vendor, each with its own auth and its own gaps.
The craft is in the tool design. A server that exposes one generic run_query tool is easy to build and hard to defend. A server that exposes ten well-named tools with fixed parameters is slower to write and much easier to secure, test and explain to an auditor.
Oracle may offer its own MCP-style capability in your release, and you should check that first. This page covers the design if you build your own, or want to extend what Oracle provides with plant-specific tools.
What teams use it for
Item availability tool
Given an item and optional location, return on hand, committed, on order and next receipt, so assistants stop guessing at inventory.
Order status tool
Given a sales order number, return fulfilment, shipment and invoice state in one structured result.
BOM and where-used tool
Return the assembly structure with component quantities, which is the question planners ask most.
Vendor performance tool
Return on-time receipt percentage and open lines per vendor over a date window.
Transaction chain tool
Given any transaction, return the linked requisition, PO, receipt and bill so an assistant can explain a trail.
Draft creation tool, later
Once reads are trusted, expose a tool that creates a draft journal or vendor return for a human to approve.
Oracle NetSuite integration surface
- SuiteQL through the REST Web Services query endpoint is the main read backend, with paging for large results.
- RESTlets (SuiteScript 2.x) wrap logic that needs several lookups, or that must run under governance controls.
- OAuth 2.0 or token-based authentication on an integration record, mapped to a dedicated role, authenticates the server to NetSuite.
- Saved searches can be run from a RESTlet when you want admins to maintain the query without a code change.
- NetSuite governance and request concurrency limits apply per account and integration, so build caching and backoff into the server.
How it works
- 1
List the questions first
Collect the 15 most common questions users ask about orders, items and vendors. Group them into candidate tools.
- 2
Write each tool as a contract
Define name, description, input schema and output schema. Write descriptions for the model, mentioning units, status codes and what is not returned.
- 3
Back each tool with a fixed query
Use parameterised SuiteQL or a RESTlet. Validate inputs, cap rows, and select only whitelisted columns.
- 4
Choose transport
Use stdio for local developer testing. Use streamable HTTP behind your gateway for shared use, with authentication on every request.
- 5
Map identity to a NetSuite role
Either use a single least-privilege service role, or map each calling user to a role through your identity provider so NetSuite restrictions apply per person.
- 6
Add audit, caching and backoff
Log user, tool, parameters, duration and row count. Cache slow-changing lookups like the item master, and retry politely on concurrency errors.
- 7
Test with several clients
Try Claude, ChatGPT-compatible clients and an open-source client, and check that descriptions guide each model to the right tool.
Example flows
Planner asks about a shortage
Trigger: A planner asks an MCP client why work order 4821 is late.
- The client calls the work order tool and sees a missing component.
- It calls item availability for that component.
- It calls the vendor tool for the open PO line.
- It answers with the shortage, the PO and the expected date.
Result: Three tool calls replace three NetSuite screens and an email.
Customer service checks an order
Trigger: A rep asks for the shipping state of a customer's order.
- The client calls the order status tool with the order number.
- The server runs a fixed query joining the order, fulfilment and invoice.
- It returns only customer-safe fields.
Result: The rep answers in seconds without access to pricing or margin data.
Keeping data on-prem
The MCP server is plain code, so you can run it on a server in your own data center or private cloud and have it call NetSuite outbound over TLS. Pair it with an open-weight model on your own GPUs and the whole assistant path, apart from NetSuite itself, stays inside your network. Put the server behind your gateway, allow-list egress to your NetSuite account domain, and keep logs in your own SIEM. If the plant network is segmented, deploy the server in the IT zone and let clients in the plant reach it through a controlled rule.
Security checklist
- Use a least-privilege NetSuite role for the server, and prefer per-user role mapping for shared deployments.
- Expose no free-form SQL tool, and parameterise every query.
- Require authentication on HTTP transport, and never expose the server to the public internet.
- Mask or omit sensitive fields such as bank accounts, tax IDs and pay data at the tool level.
- Keep an immutable audit log and review unusual call patterns.
Ways to get it done
Oracle-provided connector, if your release has it
Effort: Configuration and role design.
Good as a baseline with fewer moving parts to maintain.
Custom server with the official MCP SDKs
Effort: Two to six weeks depending on tool count.
Best when you need plant-specific tools and control over every query.
Partner-built with Netray
Effort: A short build, then ongoing tool additions.
Fits teams wanting tools, masking, evaluation and a private model path delivered together.
Pitfalls
- !One generic query tool that lets a model explore the schema freely.
- !Vague tool descriptions, so the model picks the wrong tool or invents parameters.
- !Large unpaged results that blow the context window and your governance budget.
- !Sharing one service token for everyone, which hides who asked what.
- !Forgetting multi-subsidiary visibility rules in OneWorld.
Frequently asked questions
Should the first version have write tools?
No. Ship read-only tools, measure answer quality for a few weeks, and then add draft-creating tools. Anything that writes should create a record in an unapproved state so a NetSuite user reviews it before it affects the books.
stdio or HTTP transport?
Use stdio for a developer testing on their own machine. For anything shared across users, use HTTP with authentication behind a gateway, so you can enforce identity, rate limits and logging in one place rather than on each laptop.
SuiteQL or saved searches as the backend?
SuiteQL is easier to parameterise and join. Saved searches are useful when admins want to change criteria without a deployment, usually exposed through a RESTlet. Many servers use both, chosen per tool.
Will it work with ChatGPT and not just Claude?
MCP is an open protocol with growing client support, including from several vendors and open-source tools. Support varies by product and plan, so test the clients you plan to use. The server itself does not depend on a particular model.
How do we handle NetSuite rate limits?
Cache stable lookups, cap rows per call, queue bursts, and retry with backoff on concurrency errors. Use a separate integration record for the MCP server so its traffic is visible and does not starve other integrations.
Want MCP server working on your Oracle NetSuite?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment