OpenSuiteMCP

Docs/Agent access

Agent access

OpenSuiteMCP is an MCP server. Give an external AI agent a key and your install’s URL and it works inside that NetSuite workspace as the person who minted the key — their permissions, their connected account, their tool policy.

The three calls

Streamable HTTP, JSON-RPC over POST to /api/mcp. One endpoint, no session to establish. Replace YOUR-INSTALL with the host your key came from.

List the tools. Every tool comes back with its JSON Schema.

curl -sS https://YOUR-INSTALL/api/mcp \
  -H "Authorization: Bearer osmcp_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call one. The tool name goes in params.name, never in method.

curl -sS https://YOUR-INSTALL/api/mcp \
  -H "Authorization: Bearer osmcp_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"osmcp_whoami","arguments":{}}}'

Find the server. RFC 9728 metadata, readable without a key.

curl -sS https://YOUR-INSTALL/.well-known/oauth-protected-resource

Getting a key

In the app, open App Portal → Agent access. Copy the server URL shown there, name a key after the agent that will hold it, and copy the key immediately — it is shown once and only a SHA-256 digest is stored. Keys can be pinned to one NetSuite account and revoked at any time.

There is nothing to switch on first. The endpoint refuses every request until a key exists, and a key exists only because a person made one. On an organization install an owner or admin opens Agent access under Admin → Agent access first, and may limit it to named members.

What an agent reaches

  • NetSuite tools. Every NetSuite MCP Standard Tool the account is allowed to run, re-exposed under its own name with NetSuite’s input schema forwarded verbatim — records, SuiteQL, saved searches, reports.
  • Workspace tools. osmcp_whoami, connection health, the configured NetSuite accounts and a tool to switch between them, chat history, and the skills and personas this workspace has enabled — listed and readable in full, so an agent can adopt the same playbook the app would.
  • Nothing else. A tool disabled for the connection is neither listed nor callable, and the policy is re-read on every call. A key never reaches further than the person who minted it.

Protocol

Revision 2026-07-28 — stateless, with 2025-11-25, 2025-06-18 and 2025-03-26 still accepted. Send the revision you speak in MCP-Protocol-Version; omitting it is read as the oldest.

Methods: tools/list, tools/call, ping, and initialize on the handshake-era revisions. Results carry both readable text and structuredContent; prefer the latter for rows and columns.

When something fails

  • 401 with a WWW-Authenticate header — the key is missing, revoked, or expired.
  • 403 — the organization has Agent access off, or has limited it to members this key’s owner is not among.
  • 405 — the request was not a POST.
  • -32601 Method not found — usually a tool name sent as the method. The error names the methods this server answers.
  • A tool result with isError — NetSuite refused it. Permission violations come from the NetSuite role, not from OpenSuiteMCP; call osmcp_connection_status when a tool fails unexpectedly.