Agentic Data Plane
Preview

NetSuite Managed MCP Server

The NetSuite managed MCP server lets agents query Oracle NetSuite records and run SuiteQL with the calling user’s OAuth identity. The server wraps SuiteTalk REST APIs and exposes read-only tools for records, customers, sales orders, and items.

After reading this page, you will be able to:

  • Configure the NetSuite managed MCP server with account ID and user-delegated OAuth

  • Identify the NetSuite read-only tools available to agents

  • Test NetSuite tool calls with an authorized user’s connection

What this MCP server does

Use NetSuite when an agent needs ERP, finance, or accounting context from records that a NetSuite user can already read. Every tool is read-only.

Tool What it does

suite_ql_query

Runs a SuiteQL query and returns rows as JSON. Use this tool for joins, aggregates, and cross-record analysis.

get_record

Fetches one record by record type and internal ID. You can expand sub-resources, such as line items and addresses.

list_records

Lists records of a type with optional NetSuite filter expression and paging. Use typed helpers when they fit.

get_customer

Fetches a customer record by internal ID.

list_customers

Lists customers with optional company name, email, modified-since, inactive, and paging filters.

list_sales_orders

Lists sales orders with optional customer ID, date range, status, modified-since, and paging filters.

search_items

Searches inventory and service items by SKU, display name, item type, inactive flag, and paging filters.

The managed server does not expose write tools, saved-search execution, or report execution.

Prerequisites

  • The OAuth 2.0 feature enabled in NetSuite. In NetSuite, go to Setup > Company > Enable Features, open the SuiteCloud subtab, and select OAuth 2.0 under Manage Authentication.

  • A NetSuite Integration Record that uses OAuth 2.0 Authorization Code grant.

  • A NetSuite OAuth Provider in Redpanda Agentic Data Plane for the same account.

  • Your NetSuite account ID. Production accounts use a numeric ID such as 1234567. Sandbox accounts include a suffix such as 1234567_SB1; release-preview accounts can use a suffix such as 1234567_RP1.

  • NetSuite users with a role that has both the REST Web Services and the Log in using OAuth 2.0 Access Tokens permissions.

Configure NetSuite OAuth

In NetSuite, create an Integration Record with OAuth 2.0 enabled. Set the redirect URI to the OAuth callback URL for your AI Gateway deployment. Select the REST Web Services scope.

Find your account ID under Setup > Company > Company Information > ACCOUNT ID. The managed server lowercases the account ID and turns underscores into hyphens when it builds the SuiteTalk host. The OAuth Provider endpoints you enter need the same form, because NetSuite’s account-specific domains use it. For example, account ID 1234567_SB1 becomes 1234567-sb1 in these URLs.

Create a custom NetSuite OAuth Provider in Agentic Data Plane with account-scoped endpoints, replacing <account-domain-id> with the lowercase, hyphenated form of your account ID:

Authorization endpoint: https://<account-domain-id>.app.netsuite.com/app/login/oauth2/authorize.nl
Token endpoint:         https://<account-domain-id>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
Scopes:                 rest_webservices

Store the NetSuite client secret in the Agentic Data Plane secret store, then reference that secret from the OAuth Provider.

Create the managed MCP server

Create a managed MCP server with the NetSuite type. NetSuite authentication is part of the managed config, so include user_oauth inside the JSON. In account_id, enter the account ID exactly as NetSuite shows it, such as 1234567_SB1.

{
  "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig",
  "account_id": "1234567_SB1",
  "user_oauth": {
    "provider_name": "netsuite",
    "required_scopes": ["rest_webservices"]
  }
}

For a non-UI path, use rpk ai mcp-server create with --managed.config. A managed server carries its user-delegated OAuth settings inside that JSON; the --remote.user-oauth.* flags belong to the remote flag group and apply to remote servers only.

rpk ai mcp-server create netsuite \
  --enabled \
  --description "NetSuite ERP with user OAuth" \
  --managed.config '{
    "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig",
    "account_id": "1234567_SB1",
    "user_oauth": {
      "provider_name": "netsuite",
      "required_scopes": ["rest_webservices"]
    }
  }'

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create leaves it off unless you pass --code-mode. See Code Mode.

Authorize and test

Before a caller can use NetSuite tools, the caller must authorize the NetSuite OAuth Provider. After authorization, Redpanda stores the user’s access token in the token vault and subsequent tool calls use that token automatically.

Test the server in the Inspector before you connect it to an agent. Start with a narrow suite_ql_query, get_customer, or list_customers call to confirm that NetSuite returns records visible to the authorized user.

NetSuite query notes

NetSuite record filters use NetSuite-specific forms:

  • Use CONTAIN for substring filters, not CONTAINS.

  • Use M/D/YYYY date literals for REST collection filters.

  • Match reference fields by internal ID. For example, sales-order customer filters use entity ANY_OF [12345].

  • Use NetSuite status IDs such as _pendingFulfillment for sales-order status filters, not display labels.

Troubleshooting

Symptom What to check

Tool calls return 403

Confirm the authorizing NetSuite user’s role has the REST Web Services and Log in using OAuth 2.0 Access Tokens permissions.

OAuth succeeds, but tool calls fail

Confirm the OAuth Provider endpoints and the MCP server account_id refer to the same NetSuite account, and that the endpoints use the lowercase, hyphenated account ID.

A sales-order status filter returns no rows

Use the NetSuite internal status ID, such as _pendingFulfillment, instead of the display label.

Next steps