NetSuite SuperMCP

NetSuite SuperMCP is a single MCP endpoint for AI clients to operate NetSuite through the NetSuite OAuth account and role you configure.

Includes:

• Streamable HTTP MCP endpoint.
• Bearer-token protection for MCP clients.
• Strict Zod config parsing.
• Tool risk metadata and audit logging.
• File-backed audit log.
• NetSuite REST/RESTlet adapter boundaries.
• Read, write, action, audit, capability, platform, File Cabinet, reporting, and account-permission tools.
• Typed record/field discovery, bounded batch reads, transaction graphs, System Notes, snapshots, diffs, and redacted evidence bundles.
• Inventory stock import preparation and commit tools for XLS/CSV-derived stock counts.
• Connector-visible version diagnostics with local MCP, npm package, RESTlet, tool-count, account, and execution-context details.

Local Setup

Install from npm:

npm install -g netsuite-supermcp
netsuite-supermcp oauth2
netsuite-supermcp install --all-detected

oauth2 is the shortest browser-login path. It asks only for your NetSuite account ID and the Integration Client ID/Secret when they are not already in .env, derives the NetSuite OAuth/REST URLs, opens the NetSuite OAuth consent screen, saves the refresh token, and runs doctor.

Use setup when you also want the longer guided wizard with NetSuite Integration instructions and detected agent-client install prompts.

Useful direct commands:

netsuite-supermcp oauth2
netsuite-supermcp switch-account
netsuite-supermcp public-url
netsuite-supermcp setup
netsuite-supermcp doctor
netsuite-supermcp suitecloud
netsuite-supermcp suitecloud --deploy --auth-id supermcp-11675047
netsuite-supermcp-public-url
netsuite-supermcp-oauth2
netsuite-supermcp-oauth-login
netsuite-supermcp-install --list
netsuite-supermcp-stdio

Run directly with npm/npx:

npx netsuite-supermcp oauth2
npx netsuite-supermcp switch-account
npx netsuite-supermcp setup
npx netsuite-supermcp doctor
npx netsuite-supermcp suitecloud
npx netsuite-supermcp public-url
npx netsuite-supermcp install --all-detected
npx netsuite-supermcp oauth-login
npx netsuite-supermcp stdio
npx netsuite-supermcp http

Install from source:

bun install
cp .env.example .env
bun run install:clients --list
bun run install:clients --all-detected
bun run typecheck
bun test
bun run smoke
bun run dev

Windows setup wrapper:

.\setup.ps1 -AllDetected

Or run setup.cmd from Explorer/terminal. The setup wrapper installs dependencies, creates .env from .env.example when missing, and registers detected MCP clients without changing any client approval settings.

macOS/Linux setup wrapper:

sh ./setup.sh --all-detected

The MCP endpoint is available at:

http://127.0.0.1:3025/mcp

Health check:

http://127.0.0.1:3025/health

ChatGPT Server URL With ngrok

For ChatGPT's custom app "Server URL" mode, run:

netsuite-supermcp public-url

The command starts the local MCP server, downloads the ngrok agent into your user profile when it is not already installed, starts an HTTPS public tunnel, and prints a URL like:

https://example.ngrok-free.app/mcp

In ChatGPT, use:

• Connection: Server URL
• Authentication: No auth
• URL: the printed /mcp URL

Keep the terminal open while ChatGPT uses the connector. If ngrok has not been configured on the machine before, the command opens the ngrok authtoken page and asks you to paste the token once.

Verification

bun run typecheck
bun run lint
bun test
bun run check:restlet-contract
bun run probe:live
bun run smoke

bun run smoke starts the server with sandbox-shaped local config, verifies /health, unauthorized MCP rejection, MCP initialize, and ns_getEnvironment, then shuts the server down.

netsuite-supermcp doctor uses your real .env and runs non-mutating live probes for OAuth, REST metadata, SuiteQL, and the RESTlet action layer.

Use ns_getSuperMcpVersion from any connected MCP client to verify what that client is actually seeing. It returns the local MCP package/configured version, MCP tool count, deployed RESTlet version, RESTlet action map version, NetSuite account ID, and RESTlet execution context. If a client still shows an old tool count after an update, restart that client/server process and call this tool first.

configuredVersion normally follows the installed package version. Leave MCP_SERVER_VERSION_OVERRIDE empty unless you intentionally need a custom server version string in client metadata.

bun run probe:live uses your real .env and calls the MCP tool surface with live-safe probes. Read-only tools are called directly when safe IDs can be discovered; write/delete/transform actions are exercised through ns_prepareAction so NetSuite data is not changed.

SuiteScript source files and File Cabinet folders can be listed with ns_listFileCabinet, read with ns_getFile, and managed with ns_writeFile, ns_createFolder, ns_updateFolder, ns_deleteFolder, ns_copyFile, ns_moveFile, and ns_deleteFile through the RESTlet action layer. Mutating File Cabinet tools return a server-side operation plan without changing NetSuite. Review it with ns_previewAction, then pass its operationId and exact confirmation to ns_commitAction.

Direct tool calls accept either top-level arguments or a payload object. These are equivalent:

{ "path": "/SuiteScripts", "limit": 10 }

{ "payload": { "path": "/SuiteScripts", "limit": 10 } }

ns_listFileCabinet accepts folderId or path. NetSuite root folders such as /SuiteScripts resolve to their native folder IDs, and missing paths return notFound: true with empty lists instead of failing output validation. Use limit as the friendly alias for File Cabinet maxEntries.

Platform/report discovery tools include ns_listPlatformObjects, ns_getPlatformObject, ns_searchRecords, ns_listReportTypes, ns_listReports, ns_runSearch, ns_createSavedSearch, ns_updateSavedSearch, and ns_deleteSavedSearch. These run under the configured NetSuite OAuth role, so NetSuite permissions decide what the agent can see or mutate. Use limit or pageSize for paged platform/report reads. Read-only direct calls return phase: "preview". Mutating direct calls are prepare-only and can change NetSuite only through a bound, single-use ns_commitAction operation plan. The calling harness still owns user approval and tool availability.

Record Explorer And Evidence

Record discovery tools expose record types and fields without requiring the model to guess internal IDs: ns_listRecordTypes, ns_describeRecordType, ns_listRecordFields, ns_describeField, and ns_findFieldByLabel. REST metadata is preferred; unsupported record families use the bundled, permanent read-only SuiteScript fallback.

ns_batchResolveInternalIds, ns_batchGetRecords, and ns_getRecordWithSublists are explicitly bounded and return per-record gaps instead of discarding successful reads. Transaction inspection uses ns_getTransactionChain, ns_getSystemNotes, ns_explainRecordHistory, ns_getTransactionEventStream, and ns_diagnoseTransaction. System Notes retain NetSuite's raw values and returned sequence. SuperMCP does not normalize, sort, compare, infer, or rewrite date/time values.

ns_createRecordSnapshot, ns_diffRecordSnapshots, and ns_createEvidenceBundle produce typed business-field differences and deterministic, secret-redacted evidence manifests with SHA-256 hashes. Evidence remains read-only and cites its source record, query, log, file, or audit reference.

Safe SuiteQL And Exports

ns_buildSuiteQL, ns_validateSuiteQL, and ns_explainSuiteQL provide parameterized construction, tokenized read-only validation, row-cap requirements, cost warnings, and sensitive-field classification. ns_runSuiteQLPaged uses an explicitly selected unique key and a signed opaque cursor; it does not use offset pagination for large reads. ns_incrementalExport exposes the same cursor as an opaque checkpoint and does not infer or compare date/time fields.

ns_exportSuiteQL and ns_exportSavedSearch create persistent jobs. Continue them with ns_runJobStep; inspect, cancel, or recover them with ns_getJobStatus, ns_cancelJob, and ns_resumeJob. Completed CSV/JSONL exports are exposed as netsuite-supermcp://exports/{resourceId} MCP resources and can be gzip-compressed. Deterministic chunk files prevent completed chunks from being duplicated after resume. Saved Search definition export, diff, and clone preview are also read-only; a clone is created only through the normal prepare/commit operation-plan flow.

SuiteScript Observability And Source Audit

ns_getScriptObservability reads native script, deployment, execution-log, and scheduled-instance evidence directly by script or deployment ID; it does not require an account-specific Saved Search. ns_analyzeScript, ns_findScriptDependencies, ns_findRecordWriters, ns_findRecordReaders, ns_findFieldUsage, and ns_findDuplicateScriptLogic read bounded source sets through the permanent RESTlet module. Findings include file, line, rule, severity, confidence, and redacted evidence. Secret-like literals are represented only by a SHA-256 fingerprint.

Static analysis is deliberately conservative. Dynamic AMD dependencies and unsupported dependency types are returned as unknown; they are never invented. Execution values remain as NetSuite returns them. SuperMCP does not compare or normalize date/time values to infer stuck executions.

Integration Reconciliation And Safe Replay

Versioned integration contracts define canonical keys, mappings, field semantics, and invariants. ns_reconcileRecords plus the order, inventory, return, and payment variants classify missing, extra, duplicate, amount, status, quantity, value, and delayed-processing differences and link summary totals to record evidence. External-system credentials remain in provider-owned storage; the harness supplies canonical external records to SuperMCP.

ns_shadowPayload, ns_replayPayload, and regression execution call only RESTlet preview phases and cannot save NetSuite records. Sandbox replay is rejected unless the configured NetSuite account is a sandbox. Canary prepare/monitor/promote/abort is bounded by an explicit predicate and record count. Promotion only validates existing operation plans and returns requiresHarnessApproval; it never commits them.

Synthetic test data and anonymization require explicit templates and field lists. Integration event subscriptions use a persistent idempotent outbox; SuperMCP does not contact endpoints itself. The provider polls and delivers events, then acknowledges success or failure for deterministic retry.

Customization Drift And Deployment Plans

ns_inventoryCustomizations uses permanent native NetSuite searches for custom records, fields, lists, scripts, deployments, workflows, forms, searches, roles, integrations, bundles, SuiteApps, and files. Objects without a stable script ID are returned as explicit gaps. Environment comparison uses type, script ID, definition checksum, deployment state, permissions, and dependencies; it never matches by internal ID alone and excludes date/time fields from drift checks.

ns_generateSuiteCloudProject creates a bounded checksum-pinned project from explicitly selected objects and files. Validate and preview it before ns_prepareCustomizationDeployment. Preparation stores a provider command, changed object list, confirmation, and harness-approval requirement but does not execute SuiteCloud or mutate NetSuite. After the provider runs the reviewed command, ns_recordCustomizationDeploymentResult records uploaded files, changed objects, validation warnings, and provider evidence. ns_verifyCustomizationDeployment checks the live RESTlet version.

Rollback output includes only files whose previous content and checksum were captured. Migration, cleanup, technical-debt, orphan, and documentation outputs never invent owners or delete objects; cleanup remains a proposal for the normal operation-plan flow.

Business Metrics And Lineage

Business terms and metrics are requester-owned, immutable id + version definitions stored in SEMANTIC_STORE_PATH. Define them with ns_defineBusinessTerm and ns_defineMetric; retrieve and compare them with ns_getMetricDefinition and ns_compareMetricDefinitions. Definitions explicitly name their NetSuite table, fields, aggregation, dimensions, filters, exclusions, currency metadata, owner, and source references. SuperMCP ships no account-specific meaning for sales, stock, margin, returns, active items, or other ambiguous business terms.

ns_planBusinessQuery and ns_validateMetricPlan compile only the selected metric version into a parameterized, read-only SuiteQL plan and return its table, fields, formula, filters, exclusions, lineage, and deterministic fingerprint before execution. ns_runMetric executes the bounded plan. Every result row carries its formula, query and plan fingerprints, term references, source table and fields, and caller-supplied record, integration, Saved Search, or query references.

ns_generateMetricReport returns the same evidence-backed rows as a structured report. ns_exportMetricResult writes a bounded JSONL or CSV resource, optionally gzip-compressed, with the evidence attached. No semantic tool normalizes, converts, compares, infers, or rewrites date/time values.

Process Assurance And Simulation

ns_discoverProcess builds process variants and edges from explicitly ordered transaction-chain evidence, calculates bottleneck facts only from caller-supplied durations, and preserves visibility gaps as unknown. ns_discoverBusinessRules requires every candidate to be labeled observed, inferred, or configured with confidence, source location, and evidence. ns_analyzeFieldWriteConflicts groups multiple field writers and reports ordering as unknown unless every writer includes explicit ordering evidence.

ns_profileDataQuality, ns_validateMasterData, and ns_evaluateInvariants run bounded declarative rules with severity and remediation. Pattern rules use only a literal * wildcard, not arbitrary regular expressions. ns_evaluatePolicyFacts returns matches and effects but always reports enforced: false; the provider or agent harness owns enforcement and approval.

ns_simulateDownstreamImpact, ns_simulateInventoryState, and ns_simulateChannelAllocation require complete scenario inputs and return mutatesNetSuite: false. They never enter an operation commit path and never select a location, status, channel, account, or policy default. ns_previewGlImpact accepts exactly one source: NetSuite-provided GL lines, explicit caller estimates, or a prepared operation plan. Non-NetSuite sources are always labeled estimated. ns_rankRootCauses ranks explicit hypotheses while retaining supporting evidence, contradicting evidence, and uncertainty.

Runbooks, Repairs, And Evidence Memory

ns_defineRunbook stores immutable typed steps that reference existing MCP tools and operation plans. ns_previewRunbook, ns_startRunbook, ns_getRunbookExecution, and ns_recordRunbookStep maintain persistent, resumable, ordered execution state. The provider or harness executes each referenced tool and records the result. SuperMCP never hides nested tool execution. Mutating steps require a connection-bound operation plan, preview output, and expected preview fingerprint; changed evidence stops the runbook before any commit.

ns_proposeRepair and ns_prepareBoundedRepair never execute a repair. By default no repair class is low risk. A provider may explicitly list local-only classes in RUNBOOK_LOW_RISK_REPAIR_CLASSES; financial, destructive, and unlisted repairs remain proposal-only. Existing operation plans are required where the operation protocol applies, and the harness owns final approval and execution.

ns_correlateIncidents groups deterministic identifiers before bounded message similarity. ns_measureSla evaluates caller-supplied durations without deriving or normalizing timestamps. ns_buildSupportEvidenceBundle creates redacted manifests, hashes, and reproducible-query evidence. ns_generateLiveDocumentation fingerprints caller-supplied live architecture, script, field, role, search, mapping, transaction-flow, and runbook metadata.

ns_recordEvidenceClaim stores claim, evidence, confidence, and a content fingerprint. Replacing a current claim requires its exact supersedesVersion; ns_getEvidenceMemory returns the full claim history so a later conversation cannot silently contradict prior evidence.

Harness Profiles and Composite Tools

Providers can sign a versioned harness context with MCP_HARNESS_CONTEXT_SECRET and send it in x-supermcp-context plus x-supermcp-signature headers. Stdio providers use the matching MCP_HARNESS_CONTEXT and MCP_HARNESS_CONTEXT_SIGNATURE environment values. When verification is configured, unsigned or invalid scope claims are rejected.

The signed context selects the read, preview, or operations catalog, optional tool and record type allowlists, persistent call/row/record/governance/runtime budgets, PII fields, and approval facts. ns_getHarnessContext, ns_getHarnessBudget, and ns_getCatalogProfile expose the active facts. Secrets are always redacted. The harness may permit non-secret PII, but SuperMCP never calls an approval callback or treats model text as consent.

ns_createCompositeTool stores an immutable versioned composite assembled from existing typed tools, runbooks, and prior composites. Inputs must be declared and include validation examples; tool templates are checked against the public tool schema, unavailable tools and undeclared inputs are rejected, and composite cycles are blocked. ns_getCompositeTool reads the definition. The provider executes the declared sequence; SuperMCP does not run hidden nested tools or arbitrary code.

Inventory Stock Imports

For stock count files such as Fastmag/Paris stock exports, parse the file into rows and call:

• ns_prepareInventoryStockImport
• ns_commitInventoryStockImport

Both names prepare the same server-side operation plan; ns_commitInventoryStockImport remains as a compatibility alias and does not commit directly. The planner matches each row to NetSuite items with itemMatchField (upccode by default), reads current stock from inventorybalance for the target locationId, calculates targetQuantity - currentQuantity, and returns rejected rows, impact details, an opaque operationId, and an exact confirmation. It does not change NetSuite.

Commit with ns_commitAction. It recomputes and fingerprints the same stock state, rejects stale plans and plans with missing/duplicate/ambiguous rows, and creates one inventoryAdjustment with adjustQtyBy lines through the permanent SuperMCP RESTlet inventory module. It never uploads a temporary SuiteScript file or modifies the RESTlet at runtime. Required NetSuite IDs are locationId and adjustmentAccountId; provide subsidiaryId when the account requires it.

When an inventory adjustment needs an Inventory Status assignment, pass its explicitly discovered inventoryStatusId. SuperMCP does not select a default status or adjustment account: use ns_findInventoryAdjustmentAccounts and the relevant NetSuite lookup before committing.

Use ns_findInventoryAdjustmentAccounts to find likely adjustmentAccountId values from NetSuite accounts without leaving the agent. Pass search or preferredAccountNumberPrefix when the user knows the local chart-of-accounts convention; otherwise it searches generic inventory/stock adjustment terms and returns candidate internal IDs for review.

Typed Tool Contracts

Every public tool has a bounded input schema, output schema, risk/effect metadata, permission hints, phase behavior, and valid/invalid examples. Use ns_describeTool, ns_getToolExample, and ns_validateToolRequest; validation is local and does not call NetSuite. Generated references are in docs/generated/tool-contracts.md and cached ChatGPT app guidance is in docs/generated/chatgpt-compatibility.md.

Deployment details are in docs/deployment.md. Agent client setup details are in docs/client-setup.md.

NetSuite Identity Model

Execution uses the NetSuite OAuth mapping from .env. For user-delegated access, run netsuite-supermcp oauth2; it configures .env, opens NetSuite in the browser, captures the authorization callback, exchanges the code for a refresh token, and saves it to .env. netsuite-supermcp-oauth-login is still available when .env is already configured. For machine-to-machine access, set NETSUITE_OAUTH_FLOW=client_credentials and provide the certificate values.

Run netsuite-supermcp auth-diagnose for offline configuration checks followed by authenticated metadata/RESTlet probes. Run netsuite-supermcp logout to revoke the current authorization-code refresh token at NetSuite and remove it from .env; use --local-only when only local removal is required. Run netsuite-supermcp switch-account to clear the local token and immediately start browser OAuth with NetSuite prompt=login consent for another account or role.

Identity diagnostics include ns_getLoginAuditTrail, ns_diagnoseAuthentication, ns_testOAuthCredentials, ns_getOAuthTokenMetadata, ns_analyzeRoleAccess, ns_compareRoleVisibility, ns_explainTokenEligibility, ns_getIdentityRelationship, ns_getIntegrationState, and ns_analyzeSegregationOfDuties. The optional NETSUITE_MANAGEMENT_* profile is used only when a diagnostic explicitly selects management; normal NetSuite tools always use the primary OAuth identity.

SuiteCloud Deploy

netsuite-supermcp suitecloud --deploy generates the bundled SuiteCloud project and runs Oracle SuiteCloud CLI through npx -y @oracle/[email protected]. Pass --auth-id <id> to reuse an existing SuiteCloud browser-auth ID without the interactive account picker. When only one matching auth ID is configured, SuperMCP selects it automatically. On Windows, if Java 17/21 is not available, it installs a portable Temurin JDK 21 under the user profile and uses it only for that SuiteCloud process.

SuperMCP does not impose a specific employee, role, or naming convention. It also does not bypass NetSuite authorization; NetSuite allows or denies actions based on the mapped account's permissions.

Tool Safety

Tools return risk metadata and write audit events. Client applications, harness settings, or the user decide approval. Use ns_checkAccountPermissions to probe the configured account's effective REST, SuiteQL, record metadata, and optional RESTlet access.