/businessnxtapi/ai section A section for AI related information such as Business NXT MCP server. 2026-07-10T12:31:03+03:00 # AI Connect A section for AI related information such as Business NXT MCP server. Business NXT enables your AI assistants running in MCP clients to work directly with Business NXT data, reading tables, running GraphQL queries on your behalf, creating and updating entities, attaching and retrieving documents, and running workflow skills — all in the context of a company you have access to. Learn how to do that from the [Business NXT MCP](mcp.md) page. /businessnxtapi/ai/mcp page This is a guide to get started with the Business NXT MCP. 2026-07-10T12:31:03+03:00 # Business NXT MCP This is a guide to get started with the Business NXT MCP. ## Introduction The Business NXT MCP server lets AI assistants running in [Model Context Protocol](https://modelcontextprotocol.io/) clients — such as Claude Code, Claude Desktop, Cursor or Codex — 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](https://modelcontextprotocol.io/). Business NXT exposes an MCP server; you bring an MCP-aware client. ## Endpoint | URL | Description | | --- | ----------- | | | 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. ### Claude Code Add the server from the command line: ```bash claude mcp add --transport http business-nxt https://mcp.business.visma.net/ ``` The first time you use the server, Claude Code starts the OAuth flow with Visma Connect; run `/mcp` to check the connection status and sign in if prompted. ### Codex Add the server, then authenticate with Visma Connect: ```bash codex mcp add business-nxt --url https://mcp.business.visma.net/ codex mcp login business-nxt ``` `codex mcp login` opens the OAuth flow in your browser. Use `codex mcp list` to check the configured servers. ### 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](/businessnxtapi/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](https://doc.visma.net/userdoc/businessnxt/en/administration/companies/system_information.html). - The **Company** table — applies per company. See the Business NXT help page on [Company](https://doc.visma.net/userdoc/businessnxt/en/administration/companies/company.html). 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](#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.