/businessnxtapi/mcp section This is a guide to get started with the Business NXT MCP. 2026-05-08T08:49:06+02:00 # Business NXT MCP This is a guide to get started with the 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](https://modelcontextprotocol.io/) 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](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. ### MCP Inspector The easiest way to try the server is the official inspector: ```bash 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](/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. ## 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. `create_entity` and `update_entity` only accept: | Table | What it covers | | ----- | -------------- | | `order` | Sales orders | | `orderLine` | Sales order lines | | `associate` | Customers, suppliers and contacts | | `appointment` | Appointments and activities | | `product` | Products | | `productCategory` | Product categories | | `priceAndDiscountMatrix` | Price and discount matrices | | `deliveryAlternative` | Delivery alternatives | | `structure` | Product structures (bills of materials) | | `text` | Text records | | `batch` | Voucher batches | | `voucher` | Posted vouchers | | `budget` | Budgets | | `budgetLine` | Budget lines | | `capitalAsset` | Capital assets | 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 and voucher series. Required before any query, skill or mutation. | | `businessnxt-get_table_definitions` | Returns table schemas — columns, data types and relations — for one or more tables. Required before running queries or entity operations. | | `businessnxt-execute_graphql_query` | Runs a read-only GraphQL query against the selected company. Mutations are blocked at the AST level. Results are returned in compact toon-encoded form. | | `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. | | `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. | | `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-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. | | `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-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-submit_feedback` | Reports a problem, gap or friction with the MCP tooling itself — bugs, unclear errors, missing capabilities. Feedback is about the tools, 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` additionally requires the current row values, so a stale value blocks the update. - **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.