Skip to main content
Hosted by a third party. This MCP server is built and hosted by the vendor, not Runlayer. This guide covers connecting it through Runlayer for governance, policies, and audit.
Connect your AI assistant to NetSuite through the NetSuite AI Connector Service — a remote MCP server hosted by NetSuite. Runlayer proxies requests to NetSuite’s MCP endpoint using OAuth 2.0. The MCP server URL is tied to a specific NetSuite role. Each user authorizes with their own NetSuite identity, and every tool call runs with that user’s role permissions.

​
Prerequisites (in NetSuite)

Complete every step below before adding the connector in Runlayer. Use Oracle’s own documentation as the source of truth — screens and permission names vary by NetSuite version.
1

Enable required SuiteCloud features

Go to Setup > Company > Enable Features > SuiteCloud and confirm the features required by the NetSuite AI Connector Service are enabled (including Server SuiteScript and OAuth 2.0).Follow Oracle’s guide for the authoritative list: Setting Up the NetSuite AI Connector Service.
2

Grant the required role permissions

Go to Setup > Users/Roles > Manage Roles and edit each role that should be able to use the connector. Under the Permissions > Setup subtab, add the permissions listed in Oracle’s setup guide, including:
  • MCP Server Connection
  • Log in using OAuth 2.0 Access Tokens — this is a distinct permission from “Log in using Access Tokens”. They look almost identical; the connector requires the OAuth 2.0 variant.
The full permission set is documented by Oracle and can change between NetSuite releases. Always cross-check against Setting Up the NetSuite AI Connector Service.
Do not connect as an Administrator. NetSuite explicitly blocks the AI Connector Service for the Administrator role and for any role with full permissions to all NetSuite features. Connecting as an admin will surface invalid_grant or similar authorization errors even when every other setting is correct. Create or use a dedicated, least-privilege role instead.
3

Create an integration record for Runlayer

NetSuite auto-provisions integration records for some AI clients (e.g. ChatGPT, Claude Desktop) but does not do this for Runlayer. You must create one manually.Follow Oracle’s guide: Creating an Integration Record for the NetSuite AI Connector Service.When creating the record:
  • Set the Redirect URI (also labeled “callback URL”) to your Runlayer callback, exactly and with no trailing slash:
  • Enable the mcp scope on the integration record. No other scopes are required.
  • Copy the Client ID and Client Secret that NetSuite generates — you’ll enter these in Runlayer.
  • If you already have multiple NetSuite integration records for other AI clients, avoid duplicates for Runlayer; keep a single, clearly named record for it.
4

Get the MCP server URL for your account

The NetSuite AI Connector Service MCP endpoint is scoped to your NetSuite account and to a specific role. Retrieve the exact URL for your account from Oracle’s NetSuite AI Connector Service documentation.

​
Setup in Runlayer

1

Add the NetSuite connector

  1. In Runlayer, go to My connectors, find NetSuite, and click Add connector
  2. Enter the MCP server URL from the previous step
  3. Enter the Client ID and Client Secret from your NetSuite integration record
  4. Click Deploy Server
2

Authorize

  1. On the server page, click Connect under Missing Authorization
  2. Sign in to NetSuite as a user who has been granted the role configured above
  3. If NetSuite prompts you to Choose another role, pick the least-privilege role you configured — not Administrator
Each user connects with their own NetSuite credentials, so tools run with that user’s role permissions.

​
Troubleshooting

Work through the checks below in order.
This almost always means the connecting role is missing permissions required by the NetSuite AI Connector Service, or you are signing in as Administrator.Verify, in order:
  1. The role has every permission listed in Setting Up the NetSuite AI Connector Service, including Log in using OAuth 2.0 Access Tokens (not “Log in using Access Tokens”).
  2. You are not signing in as Administrator or any role with full permissions to all NetSuite features. Reconnect and use Choose another role to switch to the configured least-privilege role.
  3. The integration record has the mcp scope enabled.
Oracle also maintains a specific reference for this error class: Common Errors > invalid_grant.
Authorization succeeded, but NetSuite rejected the follow-up request to list tools. This is a permissions issue on the role, not an OAuth issue.Recheck the role’s permissions against the Oracle setup guide and make sure the permissions were added to the exact role the user selected at sign-in.
NetSuite rejects the callback because it isn’t allowlisted on the integration record.Confirm that the integration record’s Redirect URI matches your Runlayer callback exactly, with no trailing slash:
See Oracle’s Creating an Integration Record for the NetSuite AI Connector Service for the setting’s location.
If your NetSuite account has several integration records for AI clients, users can end up authorizing against the wrong one. Confirm the Client ID and Client Secret you entered in Runlayer belong to the Runlayer-specific integration record, and disable duplicates.

​
Reference — Oracle documentation

Keep Oracle’s docs as the source of truth for NetSuite-side configuration. These are the pages this guide relies on:

​
Getting help from NetSuite

If you’ve worked through the troubleshooting section and are still stuck, open a support case with NetSuite Customer Support (via SuiteAnswers or your NetSuite account team). NetSuite can see server-side logs for your account and integration record — including the exact permission or setting that rejected the request — that aren’t visible to Runlayer. Include in the case:
  • The exact error message and, if visible, the HTTP status and NetSuite error code (e.g. invalid_grant)
  • The authorization URL Runlayer opens when you click Connect (copy it from the browser)
  • The MCP server URL configured in Runlayer
  • The role you selected at sign-in and confirmation that it is not Administrator / a full-permissions role
  • Confirmation that the role has every permission listed in Oracle’s Setting Up the NetSuite AI Connector Service guide
  • Confirmation that a Runlayer-specific integration record exists with the mcp scope and the correct Redirect URI
If NetSuite support identifies an additional permission or setting that isn’t already documented here, please share it with Runlayer support so we can update this guide.