How it works

Four hooks

Four Claude Code hooks do the work. Each one matches the connector's ns_* tools under whatever name you gave the server (mcp__<server>__ns_*), so they fire on NetSuite calls and nothing else.

Hook	What it does
SessionStart	Adds the account profile and any stale cache sections to the session context
PreToolUse	Checks SuiteQL, adds default row caps, blocks writes (or requires a preview and your approval)
PostToolUse	Caches catalog results, saves large results to files and replaces them with a summary, writes the audit log
PostToolUseFailure	Classifies the error and adds the next step

The PreToolUse hook fills in paging the connector would otherwise skip. A SuiteQL call without pageSize gets 500 by default, or N when the query ends in FETCH FIRST N ROWS ONLY. A call without pageIndex gets pageIndex: 0, so it returns one page. Without pageIndex, the connector returns every page in one response. A saved search without range_end gets a 200-row cap.

When a hook fails

If a hook fails for any reason, the call goes through untouched. Writes are the exception: a write the plugin couldn't check is blocked.

The cache

Report lists, saved searches, subsidiaries, accounting books, periods, the record-type list and field metadata are fetched once and stored on your machine. Claude looks things up with nsx before it calls a catalog tool. A second session can answer "which report shows AR aging?" with one nsx reports search and no connector call.

Each cache section goes stale after a set number of days: one for saved searches and periods, seven for reports and subsidiaries, 30 for field metadata and the record-type list. When a section Claude needs is stale, it runs /su-ns-harness:refresh for that section by itself. A catalog result that would empty or halve a cached section, or that can't be parsed, doesn't replace it.

One cache per connector

The cache is keyed by the connector, meaning the MCP server name in the tool name. Production and sandbox are separate connectors, so they never share data. Switching connectors switches the cache, and the other one stays on disk. The CLI and the session context use the connector of the most recent NetSuite call.

One account reached through two connectors gets two caches. To make them share one, set account_id and environment. See Settings.

Large results go to files

A result larger than inline_max_chars (6,000 characters by default) is saved to a local file. Claude gets a summary instead: row count, column stats, the first rows and a result id. The first line looks like this:

[su-ns-harness] 3,214 rows × 9 cols saved → … (id r_7f3a2c)

A 3,000-row result comes back as a summary of under 1,500 characters. Claude then totals, filters, sorts, pivots or diffs the file with nsx results instead of querying NetSuite again. When a result is truncated, the summary carries a truncation warning, and the skill tells Claude never to present partial totals as complete.

The results tools refuse sums that would be wrong and print n/a with a hint instead. That covers amounts in several currencies, base amounts across subsidiaries, nested report rows, a header amount repeated on every line, and id or rate columns.

Errors come back with a next step

The failure hook classifies each connector error and adds a recovery line. Rate limits get up to three sequential retries, after about 5, 10 and 20 seconds. Auth errors tell you to reconnect via /mcp. An unknown field marks that table's field cache stale. The full list is on the Troubleshooting page.

The ns-explorer agent

For open-ended questions like "which table holds X?" or "how is Y linked to Z?", Claude hands the work to the ns-explorer agent. It runs in its own context, checks the cache first, tests ideas with tiny queries, and returns only the conclusion: tables, fields, joins, the working SuiteQL and any result ids. Its answer is capped at about 15 lines, with no raw rows or metadata dumps.

The agent has no Edit, Write, NotebookEdit, WebFetch, WebSearch or Agent tools, and its instructions forbid write tools. It does have Bash. Treat that as a restricted tool list plus instructions. It isn't a sandbox. NetSuite writes from the agent still go through the same write guard as any other call.

What gets installed

Hooks: the four above. They only fire on ns_* connector tools.
Skills: netsuite, which loads by itself for NetSuite questions, plus /su-ns-harness:init, /su-ns-harness:refresh and /su-ns-harness:doctor.
Agent: ns-explorer.
CLI: one bundled Node script, scripts/nsx.mjs, with no dependencies. Claude runs it for cache lookups and result analysis. It isn't added to your PATH.

The plugin adds no MCP server, runs no background process, makes no network calls of its own and doesn't touch the connector's configuration or OAuth.