---
name: iblai-connect-oracle-netsuite
description: "Read and write Oracle NetSuite data through the SuiteTalk REST Web Services, SuiteQL, NetSuite AI Connector Service and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Oracle NetSuite data, or to set up an Oracle NetSuite MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Oracle NetSuite connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/oracle-netsuite — not part of the iblai/vibe repository. Checked against Oracle's documentation on October 20, 2026; test it against your own Oracle NetSuite setup before you rely on it.

NetSuite is a cloud ERP. An account stores the general ledger, customers, vendors, items, sales orders, invoices, purchase orders, inventory, saved searches and reports.

## Auth & conventions

- **API:** SuiteTalk REST Web Services, SuiteQL, NetSuite AI Connector Service (REST). REST record service for CRUD on records (/services/rest/record/v1/), metadata catalog, and query service for SuiteQL (/services/rest/query/v1/suiteql) and datasets. The AI Connector Service exposes MCP tools.
- **Base URL:** https://{accountId}.suitetalk.api.netsuite.com/services/rest/
- **Access:** Issued by your administrator. An admin enables the REST Web Services feature (accepting SuiteCloud terms), creates an integration record, and assigns a role with REST Web Services and Log in using Access Tokens. Oracle advises against the Administrator role.
- **Auth:** OAuth 2.0; Token-based authentication (TBA). REST web services support OAuth 2.0 and TBA. The AI Connector Service uses OAuth 2.0 authorization code grant; the role needs MCP Server Connection and Log in using OAuth 2.0 Access Tokens.
- **Limits:** A SuiteQL query returns at most 100,000 results; beyond that Oracle points to SuiteAnalytics Connect. Concurrency governance applies, and the AI Connector integration record has an editable concurrency limit.
- Keep Oracle NetSuite credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Records** — GET /services/rest/record/v1/{recordType}/{id}, e.g. customer, salesorder, invoice.
- **SuiteQL queries** — POST /services/rest/query/v1/suiteql with header Prefer: transient; page with limit and offset.
- **Record metadata** — GET /services/rest/record/v1/metadata-catalog/ describes record types and fields.
- **Datasets** — GET /services/rest/query/v1/dataset/{id}/result returns a SuiteAnalytics dataset.
- **Reports and saved searches** — Run via the MCP Standard Tools SuiteApp in an AI client.

## Writes

- **Create records** — POST to the record service, e.g. a new customer or sales order.
- **Update records** — PATCH /services/rest/record/v1/{recordType}/{id}.
- **Delete records** — DELETE on a record URL. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Oracle publishes an official MCP server, NetSuite AI Connector Service (https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_3200541651.html). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "What were total sales by subsidiary last quarter?"
- "List invoices over 60 days past due with customer and amount"
- "Run our 'Open Purchase Orders' saved search and summarize by vendor"
- "Create a customer record for Northwind Traders with net 30 terms"

## Guardrails

- Holds financial records, customer and vendor data, and may hold payroll data. Oracle states the AI Connector Service is not HIPAA-compliant and must not be used with ePHI.
- Request the narrowest Oracle NetSuite scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- SuiteTalk REST Web Services API Guide: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1559132836.html
- Get Started with the NetSuite AI Connector: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_3200541651.html
- REST URL schema and account-specific URLs: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1546938065.html
- NetSuite AI Connector Service: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_3200541651.html
- This connector on ibl.ai: https://ibl.ai/developer/connectors/oracle-netsuite
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections