> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NetSuite

> Remote MCP server for NetSuite (Oracle) ERP, CRM, and business operations via the NetSuite AI Connector Service

<Info>
  **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.
</Info>

Connect your AI assistant to [NetSuite](https://www.netsuite.com) 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.

<Steps>
  <Step title="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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714080625.html).
  </Step>

  <Step title="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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714080625.html).

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714082142.html#bridgehead_0804033316).

    When creating the record:

    * Set the **Redirect URI** (also labeled "callback URL") to your Runlayer callback, exactly and with no trailing slash:

      ```
      https://<your-tenant>.runlayer.com/oauth/callback
      ```

    * 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.
  </Step>

  <Step title="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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7200233106.html).
  </Step>
</Steps>

## Setup in Runlayer

<Steps>
  <Step title="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**
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Troubleshooting

Work through the checks below in order.

<Accordion title="invalid_grant or 401 from NetSuite during authorization">
  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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714080625.html), 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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_158521832417.html).
</Accordion>

<Accordion title="tools/list returns 401 after connecting">
  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.
</Accordion>

<Accordion title="Redirect URI mismatch">
  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:

  ```
  https://<your-tenant>.runlayer.com/oauth/callback
  ```

  See Oracle's [Creating an Integration Record for the NetSuite AI Connector Service](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714082142.html#bridgehead_0804033316) for the setting's location.
</Accordion>

<Accordion title="Multiple NetSuite integration records for the same client">
  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.
</Accordion>

## Reference — Oracle documentation

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

* [NetSuite AI Connector Service overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7200233106.html)
* [Setting Up the NetSuite AI Connector Service](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714080625.html) — features and role permissions
* [Creating an Integration Record](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714082142.html#bridgehead_0804033316)
* [Role permissions reference](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771483.html)
* [Common OAuth errors (`invalid_grant`)](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/subsect_158521832417.html)

## 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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0714080625.html) 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.