Skip to content
Services ⌄
NetSuite AI readinessNetSuite developmentSAP Business ByDesignDocXange: managed EDIAI & automationsTechnology leadership & IT
NetSuite AISuiteAppsLearnAbout usLet’s talk ↗

← Learn/Guide

Set up the NetSuite AI Connector safely

Connect Claude or ChatGPT to NetSuite with the AI Connector and a read-only role: permissions, client controls, the execution log and two tests to try.

Skip to setup9 steps · 33 min to read the setup

By Jeffrey Hansbury, President and CEO, YTBE Inc. · Nov. 11, 2026

Share
Sarah Smith asks an AI assistant which open Sales orders are over $5,000. Her role, Analyst, can view Sales orders, so the three that match come back as an answer table totalling $25,700. Her request to raise a credit limit is refused: the role can view records, not edit them. She checks the answer against the records.

By Jeffrey Hansbury, President and CEO, YTBE Inc.
Nov. 11, 2026

  • 33 min to read the setup
  • 58 min with Part 4 and reference
  • 4 parts, 9 steps, Part 4 optional

By Jeffrey Hansbury, President and CEO, YTBE Inc. · Nov. 11, 2026 · 58 min read

Free download

Quick setup card

The nine steps and the common gotchas on two printable pages. Keep it next to you while you set up.

Download the PDF

PDF · 2 pages · US Letter

Last tested in a NetSuite sandbox on November 10, 2026. Menus and tool lists change, so check the date. Where a claim comes from Oracle or a client's documentation, the page is linked. Where it comes from our sandbox, we say so.

Every business has questions they need answered. Most of the time the data exists and the reports are written, but it's time-consuming to find the right sources, download them, join them together, and analyze the result. AI assistants connected to NetSuite can help. In this article we will learn how to connect them, what they are good at, and the challenges and limitations you need to be aware of.

Three examples:

1. Solving problems as they come up with a simple prompt. A customer accidentally sent over hundreds of orders. Some of them included an order for a particular SKU and every time they ordered that SKU they meant to order 3 units of another SKU with it. You have to get the mistake corrected quickly so the orders get out on time. You could create a report to find all the relevant orders and lines and then generate a CSV file to add the new lines and units or you can prompt AI to find the orders and generate the CSV file for you. With a simple prompt you get exactly what you need and a moment later the customer's request is solved.

2. Auditing records. An unexpected change took place on a batch of sales orders. Quantities were unexpectedly cut on some of the lines and you don't know what happened. With a simple prompt to your AI agent the system notes and logs are checked and you discover a new integration made the change. The setup is checked and you discover a rule is misallocating your inventory. Troubleshooting something like this used to take hours but now the answer is found quickly and the problem gets solved.

3. Analyzing business metrics. You've noticed a sudden surge in tariff expenses and you are not sure why. Suddenly you are paying double what you were last month. A simple prompt and you have the answer. A newly launched item is classified under a more expensive HTS code and is driving the extra cost. A quick check of the item's margin and you decide you need to increase the sell price to cover the difference.

One question, one read-only role, and an answer you still check yourself.

In each case a simple prompt and you get the answers you need. What used to take hours now takes minutes. Finding that needle in a haystack suddenly got a lot easier.

The rest of this article teaches you how to get there. We will go through the setup, some exercises, some ways to improve it (context, custom tools, several accounts, the other Oracle plugins, CraftQL and Lexicon), then troubleshooting and a security checklist.

Start in a sandbox first with a small team to test it out.

One honest note before we start. We built this guide from Oracle's help pages and the AI clients' documentation, then ran every step in a sandbox. The screenshots come from that run. The example answers use a fictional company in place of our sandbox data.

At a glance

ItemDetails
Who does whatAn administrator does Part 1 (Steps 1 to 5). Part 2 (Steps 6 to 9) connects one AI client, Claude or ChatGPT, and sets its controls.
Role ruleNever use the Administrator role, or any role with full access to NetSuite features. Oracle says the connector does not run under it (Oracle). Build a separate role in Step 4.
TimeAllow an extra hour to test the setup before connecting to production.
CostOracle says the connector is free to use, though you may need a paid subscription to your AI assistant.
End resultOne person, one read-only role, one AI client connected, a log to check it by, and two questions to try.
Quick cardQuick setup card (PDF): the nine steps and the common gotchas on two pages.

The short version

  1. Start in a sandbox.
  2. Turn on Server SuiteScript, REST Web Services and OAuth 2.0 (Setup > Company > Enable Features, SuiteCloud tab).
  3. Install the free MCP Standard Tools SuiteApp.
  4. Build a read-only role: MCP Server Connection and Log in using OAuth 2.0 Access Tokens at Full, then View on only the records it needs.
  5. Give the role to one person.
  6. Connect Claude (Settings > Customize > Connectors), or
  7. connect ChatGPT (Settings > Integrations > Plugins), signing in with the read-only role.
  8. In Claude, block the write tools and set the read-only tools to need approval. In ChatGPT, switch the plugin's Write tools off.
  9. Ask a real question, check the answer against a report you trust, then check the Execution Log.

What you need

You needWhySource
A NetSuite account, ideally a sandboxWhen experimenting with a new feature, we always recommend trying it out in a sandbox first. With an active sandbox license, Oracle says you can request a refresh whenever you need to, so refresh before you start testing for a more accurate experience.Our advice. Oracle: Refreshing Sandbox Accounts. Oracle's connector page describes log retention for sandbox accounts, so sandboxes are supported.
An administrator for steps 1 to 5Administrator access is required for enabling features, installing the SuiteApp, and configuring users and roles.Oracle: Required Features and Permissions
Three features: Server SuiteScript, OAuth 2.0, and REST Web ServicesThe first two are required for the connector. REST Web Services is needed for the standard tools SuiteApp.Oracle: Installing the MCP Standard Tools SuiteApp
The MCP Standard Tools SuiteAppIt supplies the default tools. It is free, and managed by Oracle, so it updates itself.Oracle: AI Connector Service FAQ
A supported AI client (for example, Claude or ChatGPT)Oracle lists remote MCP, protocol version 2025-06-18, Streamable HTTP and OAuth 2.0 with PKCE. Claude (Pro or higher) and ChatGPT are named as supported; ChatGPT needs Developer Mode on some plans.Oracle FAQ
Your account IDFind it at Setup› then Company› then Company Information. Needed for the address of a custom connector (see Connector URLs in Part 2). Claude's and ChatGPT's built-in NetSuite connectors set the address for you and ask for the account when you sign in.Oracle: Connecting AI Clients
Paid plan for your AI clientThe connector is a free NetSuite feature, but you may need a paid plan for your AI client of choice. Claude: Oracle names Claude Pro or higher. Anthropic lists custom connectors on Free (limited to one), Pro, Max, Ultra, Team and Enterprise; on Team and Enterprise only an Owner can add one for the organization. ChatGPT: Oracle says it is supported, and that some plans need Developer Mode. Check your own workspace's admin settings for what your plan allows.Oracle FAQ, Anthropic: custom connectors

Warning

There's also a restriction for healthcare data: Oracle has not assessed the service for HIPAA compliance. Don't use it to store, process, or transmit electronic protected health information unless you've independently confirmed that doing so meets your HIPAA obligations and applicable law (Oracle FAQ).

Film

The film runs in nine short chapters, from overview to recap. The article covers the same ground in nine steps, with the detail.

Watch on YouTube

Part 1Set up NetSuite (administrator)

Steps 1 to 5. An administrator does these once.

1Start in a sandbox

Work through this guide in a sandbox account first. This is our recommendation, not an Oracle requirement. Allow an extra hour to test the setup before connecting to production.

You're giving an outside application access to your NetSuite records. A sandbox lets you check which records it can reach and what it can change, so you can catch permission mistakes before they affect live data.

Sign in to your NetSuite sandbox as an administrator and copy its account ID from the URL. Include the sandbox suffix. You'll need the full ID if you add a custom connector later.

Your account ID is everything before .app.netsuite.com in the address bar.

2Turn on the features

  1. Go to Setup› then Company› then Enable Features.
  2. Open the SuiteCloud subtab.
  3. Under SuiteScript, check Server SuiteScript.
  4. Under SuiteTalk (Web Services), check REST Web Services.
  5. Also on this subtab, check OAuth 2.0.
  6. Click Save.

Oracle's Required Features and Permissions lists Server SuiteScript and OAuth 2.0 as requirements. Its installation guide shows where to enable Server SuiteScript and REST Web Services.

Enable Features, SuiteCloud subtab: check Server SuiteScript, REST Web Services and OAuth 2.0.

You should now see

all three boxes checked after you save and reopen the page.

3Install the MCP Standard Tools SuiteApp

  1. Open Customization› then SuiteCloud Development› then SuiteApp Marketplace. This is the SuiteApps tab referred to in Oracle's instructions.
  2. In Search SuiteApps, type MCP Standard Tools.
  3. Click the MCP Standard Tools icon, then Install at the top right.
  4. Wait for the install to finish.

Oracle updates this SuiteApp automatically and warns that updates can change how its tools work. If you build a workflow around a particular tool, check that it still works after an update (Oracle installation guide).

Warning

Some tools can also create and update records, depending on the connected role's permissions. That's why Step 4 sets up a read-only role before you connect your AI assistant (Oracle tool list).

Customization > SuiteCloud Development > SuiteApp Marketplace.
Search for MCP Standard Tools and open the Oracle NetSuite listing.
The MCP Standard Tools listing from Oracle NetSuite. Click Install.

You should now see

the SuiteApp as installed. Oracle also has a page for checking an install: Viewing SuiteApp Installation or Uninstallation Status.

4Build the read-only role

Warning

do not use the Administrator role. Oracle says the NetSuite AI Connector Service cannot run if you log in with the Administrator role, or with any role that has full permissions to NetSuite features. That means a role with full access across NetSuite, like Administrator. The two Setup permissions at Full in this step are fine: our role with them connected in our sandbox. The reason Oracle gives is to limit the damage if the outside AI client is compromised (Oracle: Required Features and Permissions, Oracle FAQ). Build a new role, as below, and sign in with it. Cloning Administrator will not work either.

This role controls which records the assistant can access and what it can do with them. Take time to check its permissions before you connect.

Create a new role (Setup› then Users/Roles› then Manage Roles› then New), give it a plain name such as "AI Analyst (read-only)", and then:

  1. Setup permissions: open the Permissions tab, Setup subtab. Add these two permissions: MCP Server Connection and Log in using OAuth 2.0 Access Tokens, both at Full. Choose the permission with OAuth 2.0 in its name. Be careful: there is a similarly named Log in using Access Tokens (that is not the one you want). You'll set record permissions to View in the next step to limit the role's access (Oracle, Required Features and Permissions).
  2. Record permissions: give the role access only to the records and reports the assistant needs, and set those permissions to View. This is how we recommend keeping the connection read-only. Oracle's tools follow the connected role's permissions, so a tool cannot edit a record if the role cannot edit it (Oracle: Available Tools).
  3. Limiting tools: leave REST Web Services off this role for now. Oracle lists Full access to this permission as a requirement for ns_createRecord, so that tool should not appear (Oracle: Available Tools; a tool shows only if the role holds all of its permissions, Oracle: Installing the SuiteApp). Other tools that can change records may still appear. Oracle does not list permissions for all of them, so you'll check the tool list in Step 9.

    Seeing a tool in the list does not mean it can change your data. With record permissions set to View, the role can read those records but cannot create, edit, or delete them.

    In our test this worked in Claude: with REST Web Services off, ns_createRecord left the tool list. ChatGPT kept listing it (33 tools) until we switched off Write tools for the plugin in the workspace settings (Step 7), which brought the list down to 26. These counts come from separate captures: 33 with REST Web Services off, 26 with Write tools also off, so they will not add up exactly against the 34 in Step 7.

    Customization› then Scripting› then Custom Tools shows why. The standard tools come in toolsets, and the Record Tools toolset needs REST Web Services - Full. It holds the create, update and transform tools, and also ns_getRecord and the record metadata tools, so leaving the permission off removes all of them. The assistant then reads records through SuiteQL, saved searches and reports instead. The page also has Deactivate, but it switches off a whole toolset for the whole account, not one tool or one role.

    Record Tools needs REST Web Services - Full. It includes ns_createRecord, ns_updateRecord and ns_transformRecord, and also read tools such as ns_getRecord. Deactivate works on the whole toolset.
  4. Subsidiary, department and location access: use NetSuite's role restrictions to limit access by subsidiary, department or location, as needed. Then test those restrictions by asking the assistant for a record the role should not be able to access. Confirm that it cannot retrieve it. Oracle's AI Connector documentation does not cover this setup.

    If you run OneWorld, set the role's Subsidiary Restrictions on purpose, listing the subsidiaries the role may see (Oracle: Restricting Role Access to Subsidiaries). The assistant sees only what the role sees. In our reading, nothing in the setup warns you when a subsidiary is missing from the role, so a total can look complete and still leave one entity out. When a number looks low, check the subsidiary list first. Letting the role view records of other subsidiaries is a separate option on the role, Allow Cross-Subsidiary Record Viewing, which Oracle describes as view-only and which has side effects of its own (Oracle: Cross-Subsidiary Record Viewing). Treat it as a deliberate expansion for a stated need. Do not switch it on by default.

  5. Change history (optional): if you want the assistant to answer audit questions like Try it B, add System Notes for Analytics and REST on the Lists subtab at View. In our sandbox test, without it system notes queries returned only part of the history, with no error, and changes made by scripts and integrations were left out. The permission lets the role read the change history of every record it can see, so add it only if you need it.

Two rules from Oracle shape this role. The connector does not run for the Administrator role or any role with full access to NetSuite features, which Oracle says is to limit the damage if the outside client is compromised. And Oracle advises separate roles for different tools and risk levels, rather than reusing a broad operational role (Oracle: Risks, Controls and Mitigation). Start with one narrow analyst role. Add others later.

Setup > Users/Roles > Manage Roles > New.
Setup subtab: add MCP Server Connection and Log in using OAuth 2.0 Access Tokens.
Transactions subtab: each permission added at View.

Check that the role is saved with only the two permissions you added under Permissions› then Setup. Under Transactions, Reports, and Lists, each permission you added should be at View, none at Create, Edit or Full.

5Give the role to one person

Go to Setup› then Users/Roles› then Manage Users and edit your user record. On the Access tab, add the role you just created.

Oracle disables MCP access by default. An administrator must give the role permission to connect, and each user must authorize the AI client they use (Oracle: Risks, Controls and Mitigation).

You can keep your existing roles, including Administrator. When you connect in Step 6 or 7, choose the read-only role you just created. That role's permissions control what the assistant can access.

If you plan a pilot with several people, resist adding them all now. One person, one role, one week, then widen it.

On the employee record's Access tab, add AI Analyst (read-only) alongside your existing roles. Choose this role when connecting your AI assistant. The example uses a fictional test user with both Administrator and AI Analyst to show how an administrator can test the read-only connection.

You should now see

that user can choose the new role from the role switcher after signing in.

Your data and the AI provider

Read this before you connect. It is short, and the people who approve the project will ask for it.

  • What leaves NetSuite. The tool results the role can read: the rows, fields and report figures that come back for each question, plus what you type. A narrower role sends less (Oracle FAQ). The assistant then holds those results in the conversation.
  • Where it is processed. In the AI provider's service, under the provider's terms, not in NetSuite. Oracle's risks page describes the client as an outside party (Oracle: Risks, Controls and Mitigation).
  • Training and retention. These are set by the provider and depend on the plan. Anthropic says it does not use inputs or outputs from its commercial products, such as Claude for Work and the API, to train its models by default, with exceptions such as feedback you submit (Anthropic: commercial products). For consumer plans, Free, Pro and Max, it depends on your model improvement setting (Anthropic: consumer products); retention is covered on Anthropic's retention page. For ChatGPT, read the data controls for your plan with your workspace admin; we have not linked a plan table here.
  • Workspace admin controls. On Claude Team and Enterprise, an Owner decides which connectors the organization has (Anthropic: custom connectors). On ChatGPT Business, the workspace admin manages the NetSuite plugin (Step 7).
  • Prompt injection. Text the assistant reads, such as a memo field, an email or a web page, can contain instructions meant for the model. Oracle says prompt injection and hallucination are weaknesses of language models that NetSuite cannot remove, and advises treating retrieved content as possibly hostile (Oracle: Risks, Controls and Mitigation).
  • Compliance. Whether this meets your regulatory, contractual or client obligations is your call, and a review by your own compliance team is the right step. Oracle points out that regulations where you operate may limit how you use MCP (same page), and the HIPAA warning above applies.

The security checklist repeats the controls.

Part 2Connect the AI client

Steps 6 to 9. Pick the client you use.

  • Claude: Step 6, then Step 8 (shared controls, then In Claude), then Step 9.
  • ChatGPT: Step 7, then Step 8 (shared controls, then In ChatGPT), then Step 9.

Connector URLs

Claude's NetSuite connector and ChatGPT's NetSuite plugin set the address for you. Both connect to the standard tools (https://<host>/services/mcp/v1/suiteapp/com.netsuite.mcpstandardtools ChatGPT uses the shared host mcp.netsuite.com), and you pick the account and the role when you sign in. You never type a URL for them.

A custom connector is different: you give it the address yourself. Oracle's pages give two forms:

https://<accountid>.suitetalk.api.netsuite.com/services/mcp/v1/all
https://<accountid>.suitetalk.api.netsuite.com/services/mcp/v1/suiteapp/<applicationid>

The first URL gives the assistant access to all tools available to your role, including custom tools. The second limits it to the tools from one SuiteApp, named by its application ID. The built-in connectors give you the standard tools only.

For custom tools, our recommendation is to add each one with its own custom connector at its /suiteapp/<applicationid> address, the way the CraftQL and Lexicon sections in Part 4 do. That keeps each set of tools separate, so you can switch it on per chat and set its permissions on its own. Using the /all address in a single custom connector is also an option: it includes every tool the role can see, including custom tools you add later. Oracle's FAQ notes that leaving off /all can make a custom connection appear disconnected, so if you see that with a /suiteapp/ address, check the address first. (Oracle FAQ, connection instructions)

For a custom connector, use your sandbox's account ID in the URL. It has a different ID from your production account. To connect sandbox and production at the same time, see Sandbox and production at the same time in Part 4.

Finding the account ID and forming the address. Go to Setup› then Company› then Company Information. The account ID is on that page, and so is a Company URLs subtab that lists the account's own domain. Oracle says each account, production and sandbox, has its own account-specific domain, and that you should not construct it yourself: copy it from the Company URLs subtab (Oracle: URLs for Account-Specific Domains). Oracle's own example is a production account 123456, whose domain starts 123456.suitetalk.api.netsuite.com. A sandbox ID such as 123456_SB1 has its underscore turned into a hyphen and its letters lowercased, so that domain starts 123456-sb1.suitetalk.api.netsuite.com. Put that domain in front of /services/mcp/v1/all or the /suiteapp/<applicationid> path. If your ID looks different from these examples, copy it from the page.

Check which account you are on before you trust an answer. Do not settle it by asking the assistant, which can state the wrong account with confidence. Check the configuration instead:

  1. In the client, open the connector's settings and read the address or the connected account (Claude: Customize› then Connectors; ChatGPT: the plugin's Manage page, where the first account is marked Primary).
  2. In NetSuite, log in to the account you meant and open Setup› then Integration› then Manage Integrations. The integration record for your client should be there, with fresh rows in its Execution Log after you ask a question. If the rows appear in the other account, the client is connected to the other account.
  3. Compare the account ID on Company Information with the one in the address.

6Connect Claude

These are the clicks in Claude today. Oracle's page describes the same job with older menu names (Oracle: Connecting AI Clients).

  1. Sign in to claude.ai. Open your account menu at the bottom left (your name) and choose Settings.
In Claude, open your account menu (bottom left) and choose Settings.
  1. In the left column choose Customize, then the Connectors tab at the top.
Settings > Customize > Connectors. Leave Add alone for now; it is for custom connectors.
  1. Type netsuite in the search box. Find NetSuite (Connector, by Oracle NetSuite) and click Connect. If it is not under Yours, look under Discover.
Search for netsuite and click Connect on the NetSuite connector by Oracle NetSuite.
  1. On the NetSuite connector, click Connect again. Claude sets the address for you, so there is no URL to paste.
"You're not connected to NetSuite yet." Click Connect.
  1. A NetSuite sign-in opens. Sign in, pick the account and choose your read-only role and allow access. A pop-up confirms it.
Signed in as Administrator, NetSuite refuses the connection. Choose another role and pick AI Analyst (read-only).
Choose another role, then pick AI Analyst (read-only).
NetSuite confirms the role. Review the access it grants and click Continue.

The consent page also says you can review and revoke the consent at any time in your settings, so you can withdraw the connection later from the NetSuite side.

The NetSuite connector can only be added once. To reach a second account, such as production next to your sandbox, add it as a custom connector (Settings› then Customize› then Connectors› then Add› then Add custom connector); see Sandbox and production at the same time in Part 4 (Anthropic: custom connectors).

Team and Enterprise

On a Team or Enterprise plan the owner adds connectors for the organization under Organization settings› then Connectors, and members then find them under Settings› then Customize› then Connectors and click Connect. Because each person connects individually, Claude only reaches what that person's NetSuite role allows (Anthropic).

You should now see

NetSuite listed under Yours as connected. Switching it on for a chat is optional: in a new chat you can turn it on under +› then Connectors, but if you ask a question that needs NetSuite, Claude asks whether you want to use the connector.

7Or connect ChatGPT

These are the clicks in ChatGPT today. Oracle's page calls the same place Apps (Oracle: Connecting AI Clients).

  1. In ChatGPT, open your account menu at the bottom left and choose Settings.
In ChatGPT, open your account menu at the bottom left and choose Settings.
  1. Under Integrations, choose Plugins, then click Browse directory.
Settings > Integrations > Plugins, then Browse directory.
  1. Type netsuite in the search box. Several Oracle NetSuite plugins come up. Pick the one named just NetSuite (Oracle NetSuite, "Connect...") and click its +. The others, such as NetSuite AI Companion, Finance Analyst, SuiteSkills and SuiteCloud, are separate plugins.
Search for netsuite and click + on the plugin named NetSuite.

What the other Oracle plugins do is covered in The other NetSuite plugins in Part 4.

  1. On the NetSuite plugin page (By Oracle NetSuite, "Connect ChatGPT to NetSuite"), click Install plugin, then Sign in to NetSuite when asked.
The NetSuite plugin by Oracle NetSuite. Click Install plugin.
  1. Sign in, select the correct non-administrator role and click Continue. If you signed in as Administrator, NetSuite refuses; click Choose another role and pick the read-only role.
As Administrator, NetSuite refuses the connection. Select AI Analyst (read-only).
  1. NetSuite shows the role ChatGPT will act as. Check it says your read-only role, then click Allow.
Check the role, AI Analyst (read-only), then click Allow.

On a Business or Enterprise workspace, admins decide who can use each plugin and, where supported, whether its read and write actions are allowed. A custom connection to your own MCP server, as opposed to Oracle's plugin, needs Developer Mode (OpenAI: Plugin controls).

ChatGPT asks for confirmation before write actions by default, but a user can tell it to remember the approval for that tool for the rest of the conversation. Keep the NetSuite role read-only rather than relying on confirmation prompts to prevent changes (OpenAI custom MCP documentation).

Oracle also notes that each new ChatGPT connection may need a new NetSuite integration record because its callback URL can change (Oracle FAQ).

You should now see

"NetSuite plugin installed", with Manage and Try in chat on the plugin page. Click Try in chat to start a conversation that can use NetSuite under the read-only role.

NetSuite plugin installed. Try in chat opens a conversation that can use it.

Business workspace controls

On a ChatGPT Business workspace, an admin can also manage the plugin for everyone: click ... next to Manage and choose Manage for workspace. Each person still signs in to NetSuite with their own role, so the role stays the limit.

Workspace admins: ... > Manage for workspace.

The workspace page shows how the plugin is set up, and three settings are worth a look before you roll it out:

  • URL. The plugin connects to https://mcp.netsuite.com/services/mcp/v1/suiteapp/com.netsuite.mcpstandardtools There is no account ID in it; the account is chosen when each person signs in. It is also the standard-tools address, not /all, so custom tools you build later do not show up through this plugin.
  • Tools and New tools. Tools lists every tool the plugin offers (34 in our capture), split into Read tools (27) and Write tools (7). For a read-only setup, switch Write tools off and click Save changes. New tools is set to Enable all new tools; change it if you would rather review new tools before people can use them.
  • Sites. Allow site visitors to use this plugin is on by default. Visitors use their own connected accounts and permissions, but switch it off if you have no reason for it.
Workspace settings for the NetSuite plugin: the URL it uses, the tool list, the new-tools rule and the Sites switch.
Tools: switch Write tools off (0 of 7) and click Save changes. Read tools stay on.

ChatGPT also lets one plugin hold more than one NetSuite account, which helps when you want sandbox and production side by side; see Sandbox and production at the same time in Part 4.

8Set the controls on the client side

The NetSuite role controls which records the assistant can read or change. Claude's settings control which tools it can use and when it asks for approval.

Oracle recommends using both. It advises setting your AI application to ask before high-impact actions (Oracle: Risks, Controls and Mitigation).

Both clients: two locks

Two separate locks. Your approval cannot grant what the role does not allow.

In Claude

Anthropic's help page gives this advice for Claude:

  • Choose Allow always only for tools you trust to run without your review. While you're learning, approve each call separately.
  • In a chat, use the + menu at the lower left, then Connectors. Switch off connectors you don't need for the conversation, including any that can change data. Anthropic's page calls this the Search and tools menu.
  • Before using Research mode, disable tools that can change data. Research can run connector tools without asking each time.
  • Team and Enterprise owners control who can add connectors. They can also remove a connector for the whole organization under Organization settings› then Connectors.
  • Only connect to servers you trust, and watch for hidden instructions in files, web pages and tool results (this is known as prompt injection).

That advice comes from Anthropic's custom connectors guide. The tool settings below are shown in our screenshots of the web experience and are not covered in that guide.

In Claude, open Settings› then Customize› then Connectors› then NetSuite› then Tool permissions. Claude sorts the NetSuite tools into three groups: Interactive tools, Read-only tools and Write/delete tools. You can set each group or individual tool to Always allow, Needs approval or Block. Our setup is shown below: Read-only tools at Needs approval, the other two groups at Block.

Claude, Tool permissions for NetSuiteSet these three groups

SettingValueReason
Write/delete tools 4 toolsBlockThese can change data: ns_attachFile, ns_detachFile, ns_executeRecordAction, ns_uploadFile.
Interactive tools 5 toolsBlockIn-chat apps, and two of them can upload files, so treat the group as write-capable.
Read-only tools 17 toolsNeeds approvalReports, searches and queries. You see each call before it runs.

These settings control which tools Claude can use. The NetSuite role controls what those tools can read or change. Blocking their use in Claude can act as an additional layer of protection against accidental changes in addition to the protections provided by the recommended read-only role settings.

The page also warns that Auto mode may run tools without asking, even when they're set to Needs approval. An automated check decides which actions are too risky to allow. Keep the NetSuite role read-only so that preventing changes does not depend on Claude asking first.

Seven standard tools can change data. Claude puts four of them in a Write/delete tools group: ns_attachFile, ns_detachFile, ns_executeRecordAction and ns_uploadFile. The record tools ns_createRecord, ns_transformRecord and ns_updateRecord need the REST Web Services permission, so with the role from Step 4 they do not appear at all. Interactive tools are the in-chat apps (ns_fileCabinet_app, ns_getFileApp, ns_prompt_library_app, ns_report_filters_app and ns_uploadFileApp). Two of these can also write: Oracle says ns_uploadFileApp uploads files to a File Cabinet folder and ns_fileCabinet_app can upload files, so treat the Interactive group as write-capable too (Oracle: Available MCP Apps). For this read-only setup we set Write/delete tools and Interactive tools to Block, and left Read-only tools at Needs approval, as the Tool permissions screenshot below shows. What ns_executeRecordAction can change depends on the action it runs (Oracle: Available Tools).

With Interactive tools and Write/delete tools set to Block, Claude lists only the tools that read data: reports and saved searches, SuiteQL, files and folders, and accounting setup.
Tool permissions in our read-only setup: Interactive tools and Write/delete tools blocked, Read-only tools set to Needs approval.

Refresh or remove the connector. The ... menu next to Disconnect on the same page has two more controls:

  • Refresh tools list updates the tools Claude can see. For a custom connector, use it after you add a tool, then check the permissions for any new tools.
  • Remove deletes the connector from Claude. Disconnect signs you out of NetSuite but keeps the connector and its settings.
Claude: ... next to Disconnect, with Refresh tools list and Remove.

On an individual Claude plan, these settings apply only to you. Team and Enterprise owners can manage connectors for everyone under Organization settings› then Connectors, as covered in Step 6.

When Claude asks to run a NetSuite tool, check its name and the information it will send. Choose Allow once while you're testing. If you have two NetSuite connections, expand Choosing which NetSuite environment to query to check which account Claude selected.
Claude's answer includes a table with a total row, four findings, and a note saying it checked the totals. We've replaced the company name and figures with fictional examples.

You should now see

a chat where NetSuite is switched on, Interactive and Write/delete tools are Blocked, Read-only tools need approval, and nothing is set to "Allow always".

Four places to block a tool

There is more than one place to switch a tool off. They work at different levels, so use them together:

WhereWhat it controlsWho it affects
The NetSuite role (Step 4)Which records any tool can read or change, and which toolsets appear at allEveryone who connects with that role
Customization› then Scripting› then Custom Tools in NetSuiteDeactivate switches off a whole toolset, such as Record ToolsEvery user and every AI client in the account
Claude Tool permissions (Step 8)Block, Needs approval or Always allow, per group or per toolYou, or your organization's connector on a Team or Enterprise plan
ChatGPT workspace Tools (Step 7)Read tools and Write tools on or off for the pluginEveryone in the ChatGPT workspace

None of the NetSuite-side controls work per tool, so the per-tool choices live in Claude and ChatGPT. The role still decides what any tool can actually change.

In ChatGPT

ChatGPT answered without asking for approval. We asked it to compare year-over-year sales for the top 10 items, just as we had in Claude. It called the NetSuite tools and returned the results.

OpenAI documents confirmation prompts for write actions by default, so a read may run without one (see Step 7). Keep the NetSuite role read-only rather than relying on a prompt.

  • The read-only role limits what the assistant can do on every call. Set it up as described in Step 4.
  • In a Business workspace, open the plugin's Tools setting and disable tools you don't want it to use. Set New tools so tools added later aren't automatically enabled for everyone. See Step 7.
ChatGPT, same question: no approval prompt before it used the NetSuite tools.
The answer includes a table, a chart, key findings and an explanation of how it got the results. We've replaced the company name and figures with fictional examples.

9Check the log, then read the tool list

In NetSuite, open Setup› then Integration› then Manage Integrations. Oracle says the first Claude connection automatically creates an integration record with these settings:

  • Public Client checked
  • A Redirect URI
  • Authorization Code Grant checked
  • NetSuite AI Connector Service scope enabled

You can change State to disable the integration and stop its access. Concurrency Limit controls how many requests it can run at once. NetSuite shares its overall capacity across integrations. Requests that exceed the limit receive a “Too Many Requests” error. An assistant can send several requests for one question, so a busy month-end close, or other integrations drawing on the same capacity, can leave it short. Oracle's advice is a single account-wide limit rather than a separate limit for each integration, so change this record's value only if you have a reason (Oracle: Concurrency Limit per Integration, Oracle FAQ).

For other clients, an integration record created during a SuiteApp installation may remain pending until an administrator enables it (Oracle connection instructions, Oracle FAQ).

Setup > Integration > Manage Integrations. NetSuite created one integration record for each AI client you connected.

On the integration record, open Execution Log› then AI Connector Service (MCP). Each entry shows when the request ran, how long it took, its status, the user's email, the HTTP status and the URL path. In our sandbox each row also had a Method column (such as tools/call) and the Name of the tool that ran.

Oracle keeps these logs for 21 days in production and 7 days in a sandbox. Export any entries you need to keep longer.

One log row is one request. A successful request is not a verified answer.

Now check the tools, as promised in Step 4. Ask the assistant: “List the NetSuite tools you can use.” Compare its answer with the seven write tools and the two upload apps listed in Step 8. In Claude, tools in a Blocked group no longer appear, so none of them should; in ChatGPT, the list reflects the Write tools switch. If any appear unexpectedly, check the tool settings in your AI application and confirm that the NetSuite role is still read-only before continuing. A tool appearing in the list does not mean the role can use it to change records.

Claude, captured before we set the groups to Block: with REST Web Services left off the role, ns_createRecord is not in the list (it would sit between ns_attachFile and ns_detachFile). Other tools that can change data, such as ns_attachFile, ns_detachFile and ns_executeRecordAction, still appeared, which is why you check the list and then Block the groups in Step 8.
ChatGPT kept listing ns_createRecord after the permission change. With Write tools switched off in the workspace (Step 7), it reports 26 tools and the create and update tools are gone.
A new connection (Claude AI): NetSuite created the record itself (Created By: -System-), and the log shows the connection starting with initialize, tools/list and prompts/list, before any question is asked.
After a question (ChatGPT): in our sandbox each row also showed the MCP method (such as tools/call) and the name of the tool that ran (such as ns_runCustomSuiteQL), so you can see which tool the assistant called, when, and whether it succeeded. The log does not show the query text or the data returned.

You should now see

an integration record in the Enabled state, a log entry for your connection, and a tool list with no write tools you did not choose.

Turning it off

There are four different switches, and they do different things. Use the one that matches the problem.

ActionWhereWhat it does
Disconnect in the clientClaude: Customize› then Connectors. ChatGPT: the plugin's Manage pageEnds that client's connection for that person. Anthropic says you can revoke permissions by disconnecting the connector in Claude's settings (Anthropic: custom connectors). The role and the integration record are unchanged.
Revoke the authorizationThe client's connected-services or consent settings, then NetSuiteWithdraws the consent the person gave. Oracle's risk page lists revoking AI agent consent as a procedure to document (Oracle: Risks, Controls and Mitigation).
Change or remove the roleSetup› then Users/Roles› then Manage RolesRemoving MCP Server Connection from the role stops that role at NetSuite, whatever the client does. Oracle lists removing MCP permissions in the same procedure.
Set the integration record State to disabledSetup› then Integration› then Manage IntegrationsStops that integration's access. Per Oracle, an enabled record can be disabled but cannot go back to pending (Oracle connection instructions).

For an incident, start with the role or the record: they act at NetSuite and do not depend on anyone's client being open. Then disconnect clients so nobody keeps a stale connection.

Setup is done. Time to ask something real.

Part 3Try it

Do them in your sandbox.

Here are two examples. The questions follow Oracle's advice: be specific, name the tool or report if you know it, request actual account data, and ask for links to the records (Oracle: Best Practices).

The example answers come from our sandbox, with the company name and figures replaced by fictional examples. Your answers will depend on your data.

Try itA: a decision question

Pick something you would genuinely use. Type:

Prompt to paste

Using real data from this NetSuite account, find the items that sold more than 500 units last quarter and have less than three weeks of stock on hand. Rank them by how urgently I should reorder, show the numbers you used, and link each item. If a saved search or report already answers this, use that before writing your own query.

A good answer has four marks.

  1. 1Shows its tool callsIt shows its tool calls, so you can see the order of work: probably a metadata lookup for the item and inventory fields, then a read-only SuiteQL query.
  2. 2Ranked table with numbersIt returns a ranked table with the numbers behind the ranking.
  3. 3States its assumptionsIt states its assumptions, for instance what "three weeks of stock" meant and which date range it used.
  4. 4Links each rowAnd it links each row.
The work behind the ranking, so you know what to check.

Check the answer against a report you trust, or open an item and verify a row yourself. Oracle recommends reviewing both the steps and the result because AI can invent information.

Where a suitable report or saved search exists, use ns_runReport or ns_runSavedSearch before ns_runCustomSuiteQL. For financial reporting, Oracle advises using NetSuite's standard reports rather than SuiteQL or newly generated reports. The standard reports apply business rules that SuiteQL cannot reproduce (Oracle: Best Practices).

Use the assistant for operational questions. Check the books against your financial statements.

Claude looked for an existing saved search or report first (reorder, inventory, low stock, sales by item), then wrote its own SuiteQL query when none fit. It also says how it read "last quarter" and what it counted as sales, so you can check its assumptions.
The answer ranks each item by reorder urgency, shows the numbers behind it, explains the calculation and lists the assumptions to confirm. We've replaced the company name and figures with fictional examples.

Try itB: an audit of one record

Pick a customer, item or sales order in your sandbox that someone has edited. Type:

Prompt to paste

For [record name], show every change since August: who changed it, when, which field, the old value and the new value. Use system notes. If you cannot see them, tell me which tool or permission stopped you.

NetSuite's system notes record changes to your data, including when a change happened, who made it, their role, the field changed, and its old and new values. (Oracle: Viewing System Notes)

Ask for a short timeline showing those details for each change.

Warning

this is where a read-only role can mislead you. To see the full change history, including changes made by scripts and integrations, the role needs the System Notes for Analytics and REST permission (Lists subtab, at least View; see Step 4). In our sandbox test, without it system notes queries still ran with no error, but those changes were missing. Test it on a record you know was changed. An empty result does not mean nothing changed.

Boundary tests: is the role doing its job?

Before you let anyone else use it, run these four checks. Each reuses something from earlier steps.

  1. A permitted read works. Try it A returns real rows from a record type the role holds.
  2. An edit is refused. Ask the assistant to change a field on a test record. It should fail, or no write tool should exist (Step 4 and Step 9). Then open the record in NetSuite and confirm nothing changed.
  3. A record type outside the role is not returned. Ask for something the role does not hold, such as a payroll or compensation record. Nothing should come back, and an explanation that the role cannot see it is the right answer.
  4. The account is the one you meant. Do the check from Connector URLs: the configured account, and the Execution Log rows in the account you meant.

If any check fails, fix the role before you go on.

Part 4OptionalGoing further

Optional. Read it when you want more than the basics: context, custom tools, several accounts, plugins, CraftQL and Lexicon.

Give it context: AI Descriptions

The assistant needs context to understand your custom fields. A name like “Routing Confirmed” doesn't explain what your team means by it.

Use AI Description to explain what a custom record type, custom field or custom transaction type is for and how your team uses it. Write a short description, click Optimize for AI, review the result and click Save.

Oracle says these descriptions help both the NetSuite AI Connector and Ask Oracle understand your customizations. Check the optimized text carefully before saving, since it can contain errors. (Oracle instructions, writing guidelines)

We've found descriptions more useful when they explain blank or unexpected values, as well as what the field is for.

The AI Description tells the assistant what the record is for and how to use it. Optimize for AI suggests a rewrite. Vendor Lead Time is a fictional example record.
Each field can carry its own AI Description too. Here the Item field says what it points to.

Give it your own tools: custom tools

The standard tools cover records, reports, saved searches and SuiteQL. If your team has a repeatable job that does not fit those, you can add a tool. A custom tool is a SuiteScript 2.1 script, a JSON schema that names and describes each tool and its inputs, and an SDF object that sets where the files live, how the tool is exposed and which permissions a user needs to see it. Tools are grouped into a toolset. You build it in a SuiteCloud project, as a SuiteApp project or an account customization project, deploy it, and it appears in the client's tool list. You manage them under Customization› then Scripting› then Custom Tools (Oracle: Creating Custom Tools).

Customization > Scripting > Custom Tools: the standard toolsets from MCP Standard Tools, and your own toolset in the same list.

Customization > Scripting > Custom Tools. Your own toolset appears in the same list as the standard ones (the last row is a placeholder).

An animated illustration of a custom toolset called Reorder Tools in the Custom Tools list next to the standard toolsets, expanded to show its permission, two tools and the Deactivate button.

Illustration with a fictional toolset ("Reorder Tools" from Company, Corp.). Your own toolset will show your own tools and permissions.

Oracle limits what connector tools can do. They use the signed-in user's permissions and cannot switch roles, call Suitelets, run scripts with elevated privileges or make HTTP requests to outside destinations.

Oracle also warns that tool descriptions can contain malicious instructions, and that a tool's description or behavior can change after you approve it. Review custom tools as carefully as code, and check them again when they change. (Oracle's security guidance)

Different accounts, different roles, different toolsets

This is where a pilot turns into a rollout, so it is worth being explicit.

  • Use a separate connection for each account and role. The URL identifies the NetSuite account (with the built-in connectors you choose the account at sign-in); the role you choose at sign-in sets its permissions. Give each connection a clear name, such as "NetSuite Sandbox, Analyst" or "NetSuite Production, Analyst." Or include MCP in the name of the role to make it clear that's what it's used for.
  • Choose which tools the connection includes. Use /suiteapp/<applicationid> for tools from a single SuiteApp, or /all for every tool available to the role. (Oracle connection instructions)
  • Use roles to limit the available tools. A tool appears only when the role has all the permissions it requires. Oracle recommends separate roles for different business functions and levels of risk.
  • Expect one integration record per connection. In ChatGPT and Claude you choose the NetSuite role when you sign in. For custom tools, Oracle requires a separate integration record for each new connection, and each record's execution log shows the calls for that integration. In Claude, add a custom connector to include more tools: /all for tools across the account, or /suiteapp/<applicationid> for one SuiteApp. The connected role still controls which tools and records you can access (Oracle connection guide).
  • Use individual sign-ins. The log records who made each request. If everyone shares a login, you cannot tell who did what.

For consultants and anyone running many accounts, keep a short register. One row per connection:

  • Name: client, environment, role, for example "Client A, Sandbox, Analyst".
  • Owner: the named person responsible for the connection.
  • Approved role: which role it uses and who approved it.
  • Review date: when you last checked the role's permissions and the Execution Log.
  • Re-authorization: sign-ins can lapse. Note when you last signed in again, and expect to repeat it.
  • Offboarding: when a person or an engagement ends, disconnect the client and remove the role from the user (see Turning it off in Step 9).

Never store passwords, tokens or client secrets in the register. Sign-ins happen in the browser, and the register only records who, what and when.

Sandbox and production at the same time

Use the sandbox for testing and production for questions about live data. In Claude, you can add the NetSuite connector only once. To connect a second account, add a custom connector:

  1. Connect the first account (usually the sandbox) with the NetSuite connector, as in Step 6.
  2. For the second account, go to account menu› then Settings› then Customize› then Connectors› then Add› then Add custom connector.
  3. Give it a name you can tell apart, for example "NetSuite Production, Analyst".
  4. Paste that account's URL: https://<accountid>.suitetalk.api.netsuite.com/services/mcp/v1/all with the production account ID.
  5. Click Continue, then sign in to that account and choose its read-only role.

Each connection is one account and one role, so both appear in your connectors list and you switch on the one you mean in each chat. Keep production on the same read-only role design you tested in the sandbox, and switch on only one NetSuite connector per conversation so an answer cannot come from the wrong account. The same approach works for a second company (another NetSuite tenant).

Add custom connector: give the second account its own name and paste its URL.

In ChatGPT it is simpler. Open the NetSuite plugin, click Manage, and under Connected accounts choose Connect another account. Sign in to the second account and pick its read-only role. The first account is marked Primary. Before you trust an answer, check which account the conversation used.

ChatGPT: Manage > Connected accounts > Connect another account.

The other NetSuite plugins

Search for “NetSuite” in ChatGPT's plugin directory or under Settings› then Customize› then Connectors› then Discover in Claude. You'll find several options, but they serve different purposes.

  • NetSuite (the one this guide installs) is the connector. It gives the assistant tools and data access, limited by the role you sign in with.
  • Oracle's other plugins contain skills: instructions for specific jobs. They guide the assistant's work but don't give it any access to NetSuite. They use the connector and the permissions of your connected role. (Oracle: AI Agent Plug-ins)
PluginWhat it addsFor
NetSuite AI CompanionTool-selection order, output formatting, NetSuite domain knowledge, multi-subsidiary and currency handling, SuiteQL safety guardrailsBusiness users
NetSuite Finance AnalystFinance analysis on live data: reporting, period close, variance, aging and reconciliation reviews, cash reportingFinance users
NetSuite SuiteCloudSuiteScript, SDF, UIF, security and permissions, SAFE Guide practicesDevelopers (Oracle lists Codex and Claude Code; it also appears in ChatGPT's plugin search)
NetSuite SuiteSkills"NetSuite skills for insights and workflows across your business" (Claude's listing); announced at SuiteWorld 2026 as 45+ prebuilt skills for finance, inventory, projects and HR (report)Business users

Oracle's plugins page lists the first three and which AI applications support them. Other publishers, such as Analytos Labs with InvoiceIQ, are third parties. Check who runs the service and what access it needs before connecting.

In Claude, search for “NetSuite” on the Discover tab. Under More you can add, the four Oracle plugins are labeled Plugin. The NetSuite connection is listed alongside them as Connector.

You can also upload an individual Oracle skill file under Settings› then Customize› then Skills. (Oracle instructions)

Claude's Discover tab. Under Yours are the NetSuite connector and a custom connector for the second account. Oracle's plugins appear under More you can add.

The same search turns up other entries too:

  • QuickStart (Connector, by Oracle NetSuite) connects to NetSuite QuickStart, Oracle's finance application for tech startups. It lets the assistant read QuickStart records and run reports. With write access, it can also change records and send email. It connects to a QuickStart account, so it serves a different purpose from the NetSuite ERP connector used in this guide. We haven't tested it. (About QuickStart, connector documentation)
  • oracle-ai-data-platform-workbench-spark-connectors (Plugin, oracle-samples). Oracle sample code for its AI Data Platform, not a NetSuite tool.
  • CData Connect AI and Coefficient SuperAgent are connectors for separate products from other companies. They're relevant if you use those services to connect to NetSuite. Each uses its vendor's service, so check how that company handles your data before connecting.

Our advice: get the connector working and tested first. Add one skill at a time after that, and judge it on the answers it gives you. A skill changes how the assistant works. It does not change what your role lets it reach.

Where CraftQL fits

CraftQL is our SuiteApp for building and checking SuiteQL reports. An assistant that writes its own query is guessing at your account's field names and at what your role can see. CraftQL goes after those two weaknesses, for you and for the assistant.

What it does today:

  • Verified fields. It finds your custom fields and record types by their actual names, then checks that they work in your account before marking them as verified.
  • Check who can use a report before sharing it. The editor checks the query before it runs. You can also test a report against your account's roles to see who cannot run it and who would get results with a column missing. In our sandbox, a field hidden from a role disappeared from the results without an error.
  • A schema Change Log. Alongside Query Editor and Schema, the editor has a Change Log tab. It shows when your account's tables and fields changed, with the date, NetSuite version and a count of tables added, removed or changed. The first entry records the starting point. This is a history of the tables and fields your queries use, rather than edits to the queries themselves. If a query stops working after a NetSuite update or customization, you can check here for changes.
  • Save it as a report. Your team can open it, set the filters and run it with their own NetSuite permissions. AI helps write the query. After that, the query runs as written each time.

The assistant helps you work out the question and draft the query. CraftQL lets you check that query using the signed-in role's permissions and run it again once it's right.

CraftQL already includes a custom toolset for the AI Connector, built as described in Give it your own tools: custom tools. Its eleven tools appear alongside the standard tools when the connected role has Perform Search set to View.

Connect it with its own custom connector pointed straight at CraftQL's /suiteapp/ address, not the /all address. That connection carries only CraftQL's tools, separate from your standard NetSuite connector, so you can name it, switch it on per chat and set its tool permissions on their own. The ones that matter most for a first try:

ToolWhat it does
ytbe_getVerifiedSchemaReturns the verified field list for a record type and role, so the assistant uses real field names.
ytbe_reviewQueryTakes a draft SuiteQL query and returns structured objections before anything runs: a field the calling role cannot read, an unknown name (with a "did you mean"), a wrong literal that would silently return zero rows, an ambiguous join, a cost warning. An empty list is not an all-clear, and the tool says so.
ytbe_runVerifiedReportRuns the query, or a saved one, under the calling role. A field the role cannot read that appears only in the SELECT is stripped with a banner. One in a WHERE or JOIN blocks the query with a reason.
ytbe_getAudienceImpactFor a query, reports which roles can run it and which would be blocked or quietly missing a column.

The other tools help you find tables and fields, follow a field's reference to another table before writing a join, and build a query from a tested starting point. They can also create a saved report from a plain-language request, suggest reporting patterns your business uses for a record, find custom fields missing descriptions, and convert a saved search to SuiteQL.

Try itC: let the assistant check its own query

Optional. Needs CraftQL installed and its own custom connector (see Where CraftQL fits). The built-in ChatGPT plugin and Claude connector do not show custom tools (see Step 7).

Connect through CraftQL's own custom connector so its tools show up, then type:

Prompt to paste

Using the CraftQL tools, find open sales orders over 30 days old by sales rep. Look up the verified fields first, review your draft query before running it, then run it. Tell me what the review objected to and what the run stripped or blocked for my role.

Start by looking up the tables and fields, then draft and review the query. If the review finds a field name that doesn't exist, correct it before running. Check the returned rows and any fields left out because of your role's permissions. Illustrative, not captured from a real run: the review catches a misspelled status value and the assistant fixes it before the query runs. Try it in your sandbox and check the tool calls and results.

You still need to check the results, and use your financial reports for the books. These checks help catch mistakes before the query runs. For reports you use every week, the next article in this series covers how to get the same answer every time.

More about CraftQL.

Where Lexicon fits

CraftQL helps when the assistant has to write a query. Often it should not write one at all. Most businesses already have the reports that answer their common questions, with the filters, formulas and definitions their team agreed on. The trouble is finding the right one among the near duplicates.

Lexicon is our SuiteApp for naming and defining reports. It keeps a catalog of your canonical reports, the ones your business has certified, with plain descriptions of what each one measures, which filters it applies and how its formulas work. Lexicon ships its own AI toolset, so the assistant can search that catalog directly. Connect it the same way as CraftQL, with its own custom connector pointed at Lexicon's /suiteapp/ address. The assistant can then find the certified report for a question and cite its definition, instead of writing a new query that misses a filter or calculates a total differently. That follows Oracle's own advice to prefer existing reports and saved searches over new SuiteQL, and it means the answer matches the number your team already reports.

Lexicon also checks each report against the signed-in role, so the assistant is not pointed at a report that would come back empty for that user.

The tools are available to roles that hold the Perform Search permission at View. Lexicon's toolset has two tools, and both are read-only and run under the signed-in role:

ToolWhat it does
ytbe_searchReportCatalogSearches the catalog of governed reports and business metrics, including the built-in financial reports. Certified reports come first, each with who certified it, its current health and a ready-to-quote citation.
ytbe_explainMetricExplains why a number can be trusted: the plain-language definition, how it is calculated, who certified it and when, the last clean run with its row count, the report's current health and any caveats.

Neither Lexicon tool runs the report itself. Once the assistant has found the certified report, it runs it with the NetSuite MCP Standard Tools you connected in Part 2: ns_runReport for a report or ns_runSavedSearch for a saved search, under the same read-only role. Lexicon finds and explains the report; the standard tools run it.

Troubleshooting

Show the troubleshooting ladder

Work down the ladder in order. Each rung assumes the one above it is fine, so do not skip ahead. Evidence to check is named for each (Oracle FAQ, Oracle: Installing the SuiteApp).

RungSymptomLikely causeFixEvidence to check
1. InstallNothing to connect to; the SuiteApp or features are missingSuiteApp not installed, or Server SuiteScript, OAuth 2.0 or REST Web Services offInstall the MCP Standard Tools SuiteApp and turn on the three features (Steps 2 and 3)the Installed SuiteApps list in NetSuite; Setup› then Company› then Enable Features
2. AuthenticationCannot connect or sign in at allAdministrator or full-access role chosen at sign-in; role lacks MCP Server Connection or Log in using OAuth 2.0 Access Tokens (not the plain Access Tokens one); wrong account chosenSign in with the read-only role from Step 4; check the account you pickedThe role's Setup permissions; the account ID on Company Information
2. Authentication"Connected" in the client, nothing in NetSuiteCustom connector address wrong, or pointing at another accountUse one of the two forms in Part 2, with the domain copied from the Company URLs subtabThe integration record's Execution Log: no rows usually means the request never reached this account. Check the account, the integration record, the time range and log retention before concluding
2. AuthenticationIntegration record stuck pendingAn administrator has not enabled itOpen the record and enable it. It cannot go back to pending, but it can be disabledIntegration record State
3. Tool discoveryConnected, but no tools in the listSigned in under the wrong role; the role lacks permissions a tool needs; the SuiteApp folder in the File Cabinet is restricted for the roleSign in under the intended role; add the permissions the tools need; adjust the restriction on the SuiteApp's folder for this roleExecution Log shows tools/list; the role's permissions
3. Tool discoveryA write tool shows upSeven standard tools can change data, and two Interactive tools can upload files (Step 8)Block Claude's Write/delete and Interactive groups, or switch ChatGPT's Write tools off, and keep the role at View. ChatGPT kept listing ns_createRecord after we changed the roleThe tool list against Step 8
4. PermissionAccess deniedThe role cannot reach the SuiteApp's File Cabinet folder, or lacks a record permissionCheck folder restrictions and the roleThe role; the Execution Log status
4. PermissionRecords or subsidiaries missingThe role's subsidiary list leaves one out, or the audit permission is missing (Step 4)Check Subsidiary Restrictions on the role; add System Notes for Analytics and REST only if you need auditsThe role record
5. Execution"Too Many Requests"You hit the concurrency limit shared with other integrations, often at month-endRetry; ask an administrator to review the limit (Step 9)The integration record's Concurrency Limit
5. ExecutionLong or large answers fail, or a long chat stops making senseOracle says clients typically handle up to about 5,000 rows per call (Oracle FAQ), and clients apply their own token limits and timeouts; a very long conversation carries all earlier resultsNarrow the question by date, subsidiary or record type, or start a fresh chatRow counts in the answer; the Execution Log
6. Answer qualityEmpty or thin answerDo not assume nothing exists. A tool may have been refused or the role cannot see itAsk which tool it called and what came back, then check the role. This matters most for audit questionsTool calls in the client; the Execution Log
6. Answer qualityAnswer looks wrong, or comes from the wrong placeThe wrong account or environment, or a wrong queryOpen the tool calls and compare with a report you trust, and re-run the account check from Part 2The tool calls; Company Information; the Execution Log in each account

For anything unexpected, look in the Execution Log first. It shows which request reached NetSuite, who sent it and whether it succeeded. Oracle's advice is to review both the steps and the final answer.

Security checklist

Based on Oracle's risks, controls and mitigation page, with our additions marked.

Quick reference

Show the quick reference
ItemValueSource
FeaturesServer SuiteScript, OAuth 2.0, REST Web ServicesOracle: Required Features and Permissions
Role permissionsMCP Server Connection; Log in using OAuth 2.0 Access TokensOracle: Required Features and Permissions
Optional permissionSystem Notes for Analytics and REST (Lists, View), only for auditsOur measurement; see Step 4
Role limitsNot Administrator, nor any role with full accessOracle: Required Features and Permissions
SuiteAppMCP Standard Tools (free, managed)Oracle FAQ
Built-in connectorsClaude's NetSuite connector and ChatGPT's NetSuite plugin set the address (standard tools) and ask for account and role at sign-inOur sandbox
Custom connector URL, all toolshttps://<accountid>.suitetalk.api.netsuite.com/services/mcp/v1/allOracle: Connecting AI Clients
Custom connector URL, one SuiteApp.../services/mcp/v1/suiteapp/<applicationid>Oracle: Connecting AI Clients
Tools that can change dataSeven: ns_attachFile, ns_detachFile, ns_executeRecordAction, ns_uploadFile; and, with REST Web Services, ns_createRecord, ns_transformRecord, ns_updateRecord. The Interactive apps ns_uploadFileApp and ns_fileCabinet_app can also upload filesOracle: Available Tools and Available MCP Apps; our sandbox
Standard tool groups34 tools with every permission in place. You see fewer when the role leaves out a permission, such as REST Web Services (Step 4), or when you block or switch off tools in Claude or ChatGPT (Steps 7 and 8).Oracle: Available Tools; our sandbox
SuiteQLRead-only queries onlyOracle: Available Tools
ReportsDate and subsidiary filters only, no accounting periodsOracle FAQ
Where to see usageSetup > Integration > Manage Integrations > record > Execution LogOracle: Connecting AI Clients
Log retention21 days production, 7 days sandboxOracle: Connecting AI Clients
Custom toolsCustomization > Scripting > Custom ToolsOracle: Creating Custom Tools
AI unitsNot consumed by the connectorOracle FAQ
Not forProtected health informationOracle FAQ

Endpoints

EndpointReturnsUse it for
/services/mcp/v1/allEvery custom tool available to the role, from SuiteApps and account customization projectsOne custom connector for everything the role can see
/services/mcp/v1/suiteapp/com.netsuite.mcpstandardtoolsThe standard tools onlyWhat the built-in Claude and ChatGPT connectors use
/services/mcp/v1/suiteapp/<applicationid>The tools from one SuiteAppA separate connector per tool set (CraftQL, Lexicon)

All start with https:// followed by your SuiteTalk host, for example 1234567-sb1.suitetalk.api.netsuite.com. Copy the whole host from the Company URLs subtab rather than typing it (Oracle).

Where to click

TaskPath
Find the account ID and domainSetup > Company > Company Information
Turn on featuresSetup > Company > Enable Features
Build the roleSetup > Users/Roles > Manage Roles > New
Check the integration record, state and concurrencySetup > Integration > Manage Integrations
Read the logManage Integrations > record > Execution Log > AI Connector Service (MCP)
See toolsets and custom toolsCustomization > Scripting > Custom Tools
Check the SuiteApp is installedThe Installed SuiteApps list (see Step 3)

Our take

For teams already using an AI assistant every day, we think the connector is the most useful thing Oracle has shipped. You control its access through NetSuite roles, just as you do for your team. The difference is that an outside application is now using that access to read your records and potentially change them. Start with a read-only role, check the tool calls, and add permissions only when there's a specific need.

Next in this series: CraftQL, and how to get the same answer every time from an AI-written report.

Get new articles by email

Guides, films and field notes from our NetSuite and IT work. About one a week. No spam.

Get new articles by email

Guides, films and field notes. About one a week. No spam.

Loading the sign-up form.

Share

← More guides and articles

YTBE Inc.

Technology partners for growing brands.
Morris County, New Jersey. Working worldwide.

LearnPrivacy PolicyContact Us

© 2026 YTBE, Inc. · Monday–Friday, 9 a.m.–5 p.m. Eastern

NetSuite is a registered trademark of Oracle America, Inc. SAP and SAP Business ByDesign are trademarks or registered trademarks of SAP SE. Microsoft and Microsoft Teams are trademarks of the Microsoft group of companies. YTBE, Inc. and its products and services are independent third-party offerings and are not endorsed or sponsored by Oracle, SAP, Microsoft or their subsidiaries.