The NetSuite AI Connector Service speaks MCP (Model Context Protocol), which means Claude, ChatGPT, or anything else that speaks MCP can query your account directly.
When it works it’s a twenty-minute job. When it doesn’t, the error messages don’t help much and the fix is usually a checkbox on the integration record that nobody mentioned.
This is organized by what you saw. The last section isn’t troubleshooting, it’s what the connector already gives you, which is more than most people end up using.
The MCP URL
Check this first, it takes ten seconds. The URL is:
https://<your-account-id>.suitetalk.api.netsuite.com/services/mcp/v1/suiteapp/com.netsuite.mcpstandardtools
A wrong account ID or a trailing slash produces failures that look like auth problems, and you can spend a while chasing the wrong thing.
“code: Field required” on the callback page
You got through the NetSuite role-selection screen, NetSuite sent you back to the AI client, and the client showed an error about a missing code parameter.
What happened is that NetSuite’s redirect didn’t carry the authorization code, so the client can’t finish the token exchange. Nothing’s permanently broken and it’s almost always fixable on the NetSuite side.
Work through these in order. Most people are fixed by the first or the fourth.
1. You have more than one integration record
If the SuiteApp was reinstalled, or somebody connected from ChatGPT a few times, you can end up with several of these and they’ll fight over the auth.
Setup > Integration > Manage Integrations, open NetSuite AI Connector Service. Check Show Inactives to see blocked records. You can’t delete an integration record, only block it. On each duplicate, uncheck the NetSuite AI Connector Service box as well as marking it blocked, so you’re left with exactly one active.
2. The MCP scope isn’t checked
Open the integration record, scroll to the OAuth 2.0 section, and confirm “NetSuite AI Connector Service (MCP)” is checked under scopes.
If it’s missing you have to recreate the record. NetSuite won’t let you add that scope to an existing one, which is annoying but that’s where it is.
3. Cookies
Try an incognito window, or a different browser.
The state cookie from the authorize request gets dropped by cookie blocking and cross-site tracking prevention, and when it disappears the redirect comes back without the code. A clean browser context fixes it.
4. Work out which side actually failed
There’s an “AI Connector Service (MCP)” execution log subtab on the integration record. It records whether NetSuite thinks the authorization succeeded.
If NetSuite says it succeeded, the problem is on the client side and NetSuite support can’t help you. If NetSuite says it didn’t, keep working down this list.
You’re asked to re-authorize every few days
Nothing’s wrong. The defaults on the integration record are conservative, your refresh token expires, and you get dropped.
Setup > Integration > Manage Integrations, open the record you’re using, and set three things.
- Enable Public Client. Check it. It’s required for the dynamic OAuth flow and for the longer token lifetimes below.
- Refresh Token Validity. 720 hours, the maximum. Thirty days instead of the default.
- Max Time for Token Rotation. 720 hours.
Save, and the next authorization holds for thirty days.
This matters more than it sounds if you have anything scheduled. A weekly report that quietly stops running because a token expired on a Tuesday is worse than one that never ran, because you’ll assume it ran.
What you actually get: the Standard Tools
Before you go building anything, it’s worth knowing what’s already there. The MCP Standard Tools SuiteApp ships four groups.
| Group | Tools | Permission to see this tool |
| Record | ns_createRecord, ns_getRecord, ns_updateRecord, ns_getRecordTypeMetadata | REST Web Services (Full) |
| Report | ns_listAllReports, ns_runReport, plus ns_getSubsidiaries, ns_getAccountingBooks, ns_getAccountingContexts, ns_getNexusIds for filtering | None |
| Saved Search | ns_listSavedSearches, ns_runSavedSearch | Perform Search (View) |
| SuiteQL | ns_runCustomSuiteQL, ns_getSuiteQLMetadata | None |
Read that column carefully, because “None” is easy to misread as “no permissions involved.” It means nothing gates the tool showing up in your client. What the tool can actually return is still your role, every time. Oracle draws the same line: on the report filters app they write that there are no permission requirements to see the tool, and then, in the next sentence, that your ability to run reports depends on the permissions assigned to your role.
A few other things fall out of that table.
ns_runCustomSuiteQL is read-only. It won’t write. So if the security conversation at your place is about an AI changing data, the writing happens through the Record tools and nowhere else, which means it comes down to one permission, REST Web Services (Full). That’s usually a shorter conversation than people expect.
ns_getSuiteQLMetadata is the one that stops the guessing. It gives you the real queryable fields for a record type, their data types, and which ones are joinable. Most bad SuiteQL out of an AI client is invented field names, and this is the fix. ns_getRecordTypeMetadata does the same for the Record tools.
And tool visibility is role-gated, separately from data access. A tool only appears in your client if your role has every permission that tool requires, so two people on the same connector can be looking at different toolboxes. Seeing a tool doesn’t mean you can reach the data, that’s still your role.
MCP Apps: pick instead of describe
The same SuiteApp ships three MCP Apps. These are interactive panels your AI client draws inside the conversation, so you pick a subsidiary or a record from a list instead of describing it in a sentence and hoping.
| App | Tool name | What it does |
| Prompt Library | ns_prompt_library_app | Browse and use prompt templates from the Companion SuiteApp |
| Record Selector | ns_selector_app | Pick an existing record in a workflow that needs one |
| Report Filters | ns_report_filters_app | Choose the filters for running a report |
Whether they work depends on the client you open them in, which is not something the documentation prepares you for. We ran them in September 2026 and found the same app, on the same account, working in one client and drawing an empty panel in another.
That’s its own page, with the payloads and a five-minute test you can run in your own account: NetSuite MCP Apps, and why yours might come up empty.
Worth reading before you plan a workflow around the Record Selector, which is the app that feeds the tools that write.
Building your own tools
If the standard tools don’t cover what you need, you can write your own and give them a UI. That’s a developer job with its own requirements and a couple of real security traps, so it’s on its own page: building custom tools and MCP Apps for NetSuite.
Go read it now rather than later if you already have a custom tool in production. There’s a migration you need to do and nothing is going to warn you about it.
One thing to decide before you roll this out
Every query the connector runs executes under somebody’s NetSuite role. That’s a security decision rather than a technical detail, and it changes what the answers mean, sometimes in ways that aren’t obvious. That’s the companion page: getting reliable answers out of the NetSuite MCP.
Stuck on one that isn’t here? The first hour is free. Bring us the error and we’ll work it in your account.