Business NXT MCP

Introduction

Note

The MCP is not in official release yet and is in piloting. Reach out to your BNXT contact for more information.

The Business NXT MCP server lets AI assistants running in Model Context Protocol clients — such as Claude Desktop, Cursor, or the MCP Inspector — work directly with Business NXT data. Once connected, the assistant can read tables, run GraphQL queries on your behalf, create and update entities, attach and read documents, and run workflow skills — all in the context of a company you have access to.

You authenticate with your normal Visma Connect login. The assistant only sees data the signed-in user is allowed to see, and write operations require your explicit approval before they run.

Tip

If you are not familiar with MCP, see the official Model Context Protocol documentation. Business NXT exposes an MCP server; you bring an MCP-aware client.

Endpoint

URL	Description
https://mcp.business.visma.net/	The Business NXT MCP server (HTTP streamable transport).

The endpoint is stateless — each request is handled independently and authenticated with a bearer token. There is no session to keep alive between requests.

Connecting a client

Most MCP clients only need the URL above. The first time you connect, the client will be redirected to Visma Connect to sign in and approve access; after that, the client stores a token and reuses it.

MCP Inspector

The easiest way to try the server is the official inspector:

npx @modelcontextprotocol/inspector --url https://mcp.business.visma.net/

The inspector opens in your browser, starts the OAuth flow with Visma Connect, and lets you call the tools interactively.

Claude Desktop, Cursor and other clients

Add the Business NXT MCP server to your client’s MCP configuration with the URL above. The client handles client registration, the login flow, and token refresh automatically — you only need to sign in to Visma Connect when prompted.

Authentication

Sign-in goes through Visma Connect, the same identity provider as the rest of the Business NXT API. The token is issued for you personally, so every tool call runs with your Business NXT permissions — the assistant cannot see or change anything you couldn’t access directly.

See Authentication for general information about Visma Connect.

Selecting a company

After signing in, the assistant calls businessnxt-init first. It returns the list of companies the user can access, each with a companyNo and tenantId. Once a company has been chosen, the assistant calls businessnxt-init_company with that pair to load the rest of the context: the table schemas (including custom tables and columns from data model extensions), the GraphQL query rules, and the per-company configuration — org-unit dimension labels, account-number series and active voucher series. Queries, skills and mutations all depend on this second call.

AI permission

Even when the signed-in user has access to a company, the Business NXT GraphQL API only allows MCP requests when the company has explicitly opted in via the AI permission setting. The setting carries separate Read and Write toggles for the MCP server; Write requires Read.

The setting is configured in two places, both of which must allow the operation:

The System information table — sets the tenant-wide default. See the Business NXT help page on System information.
The Company table — applies per company. See the Business NXT help page on Company.

Only users marked as System supervisor in the User table can modify these fields. Changes take effect immediately.

When the MCP permission is not granted, requests reach the GraphQL API and are rejected there with an access error — independently of the user’s other Business NXT permissions.

Read and write access

Reads are open: businessnxt-execute_graphql_query accepts any GraphQL query against any table the signed-in user can see in Business NXT. Mutations are blocked at the AST level, so the assistant has to use businessnxt-create_entity and businessnxt-update_entity for writes.

Writes are restricted to a fixed list of tables. Most accept both create_entity and update_entity; two are restricted to a single operation:

Table	What it covers	Operations
`order`	Sales orders	create, update
`orderLine`	Sales order lines	create, update
`associate`	Customers, suppliers and contacts	create, update
`appointment`	Appointments and activities	create, update
`product`	Products	create, update
`productCategory`	Product categories	create, update
`priceAndDiscountMatrix`	Price and discount matrices	create, update
`deliveryAlternative`	Delivery alternatives	create, update
`structure`	Product structures (bills of materials)	create, update
`text`	Text records	create, update
`batch`	Voucher batches	create, update
`voucher`	Posted vouchers	create, update
`budget`	Budgets	create, update
`budgetLine`	Budget lines	create, update
`capitalAsset`	Capital assets	create, update
`crossReference`	Payment-matching records linking transactions across associates	create only
`stockBalance`	Inventory replenishment parameters (forecast inputs)	update only

Tables outside this list are read-only through the MCP, even if the signed-in user has write permission in Business NXT itself.

Tools

The server exposes the following tools. Tool names are prefixed with businessnxt- so they don’t collide with tools from other MCP servers your client may have connected.

Tool	Description
`businessnxt-init`	Starts the session. Returns the list of companies the user can access (with `companyNo` and `tenantId` for each). Call this first.
`businessnxt-init_company`	Second step. Loads the tenant’s full schema (core tables and data model extensions) and the selected company’s configuration — org-unit dimension labels, account-number series, voucher series, open accounting periods and behaviour switches. Required before any query, skill or mutation.
`businessnxt-get_table_definitions`	Returns table schemas — columns (with `readOnly`, `primaryKey` and DME accessor hints), relations (`joinup`/`joindown`) and `canInsert`/`canUpdate` flags — for one or more tables. Required before running queries or entity operations. Columns tagged with an `enumKind` need a follow-up `get_field_values` call before they can be read or written.
`businessnxt-get_table_documentation`	Returns the plain-English reference docs from doc.visma.net for a table, a specific field, or an arbitrary workflow/concept page. Use it for business semantics — disambiguating similar fields, understanding how a column is used in a workflow — rather than for query construction.
`businessnxt-get_field_values`	Returns the enum/bitmask catalogue for one or more coded integer fields on a table (for example `order.orderType`, `order.orderStatus1`). Call it for every column flagged with an `enumKind` by `get_table_definitions` before reading or writing the value.
`businessnxt-search_documentation`	Free-text search over doc.visma.net page titles and summaries. Returns ranked path/title/summary hits; pass the chosen path to `get_table_documentation` to load the full prose.
`businessnxt-execute_graphql_query`	Runs a read-only GraphQL query against the selected company. Mutations are blocked at the AST level. Results default to compact toon encoding; set `response_format="json"` for raw JSON when exact values matter. Supports a client-side `@decodeBase64` directive that decodes base64-encoded string fields before returning them — useful for blob columns such as `approvalTaskChangeLog.messageXml`.
`businessnxt-create_entity`	Creates one or more entities (orders, associates, etc.). Requires a user-approved plan, a prior table-definition lookup and foreign-key validation. Supports nested children (for example an order with its `orderLines`) in a single call, and a `dryRun` mode that validates and returns server-computed values — including currency context on tables with `*InCurrency` amounts — without persisting. Error handling defaults to `FAIL_TABLE` so a single bad field aborts the whole batch instead of silently substituting defaults.
`businessnxt-update_entity`	Updates an entity. Requires the entity’s primary keys and current `oldValues` for safety — the update only runs when the stored values still match. DME extension columns can be written using either flat field names or the `extensions: [{column, …Value}]` array shape on both `entity` and `oldValues`. Error handling defaults to `FAIL_TABLE`.
`businessnxt-list_skills`	Lists available workflow skill guides (for example order management, associate management) with summaries and tags.
`businessnxt-get_skill`	Loads a skill guide by id or search query. Optionally fetches live reference data (number series, countries, …) for a given company. When called with `company_no`, also checks the user’s access to the tables the skill needs and surfaces an upfront warning if any read or write permission is missing.
`businessnxt-attach_document`	Attaches a file to a Business NXT entity. Two phases: the first call shows the upload UI (or asks for file bytes); the second call performs the attachment.
`businessnxt-view_document`	Opens an attached document in a visual viewer that renders PDFs, images and text files.
`businessnxt-read_document`	Extracts the content of a document. `content` mode returns text and embedded images from PDFs, XML, HTML and CSV; `png` mode renders PDF pages as PNG.
`businessnxt-get_design_guidelines`	Returns design tokens, ECharts theme and styling rules so dashboards and document viewers render with the Business NXT look and feel.
`businessnxt-dashboard`	Renders an interactive chart dashboard (bar, line, pie, scatter, heatmap) over a result set.
`businessnxt-calculator`	Evaluates mathematical expressions with arbitrary-precision arithmetic. Use it for monetary and accounting computations where rounding matters.
`businessnxt-get_current_datetime`	Returns the current date and time in a given IANA timezone (defaults to `Europe/Oslo`), with an optional day offset for relative dates like yesterday or next week.
`businessnxt-submit_feedback`	Reports a problem, gap or friction with the `businessnxt-*` tools — bugs, unclear errors, missing capabilities. Only in scope for tools this server exposes; other MCP servers and the host’s connection/authentication flow are out of scope. Not a route to Visma support.

Tip

The assistant generally chooses tools on its own based on what you ask. You don’t need to call them by name — just describe what you want to do with your Business NXT data.

Safety

A few things worth knowing:

Stale values block updates. update_entity requires the current row values via oldValues, so a stale snapshot blocks the update rather than silently overwriting a change someone else made.
Writes are limited to a fixed table list (see Read and write access). Any other table is read-only through the MCP.
Your user, your scope. The token issued by Visma Connect represents you; the server cannot see or do anything you couldn’t do directly in Business NXT.