> For the complete documentation index, see [llms.txt](https://developer.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.vario-software.de/documentation/ai-assistants-mcp.md). # AI Assistants (MCP) Connect Claude Code, Cursor, VS Code or any MCP client to VARIO Cloud and let an AI assistant explore the live REST API, VQL fields, batch processing and print layouts of your tenant while you build. VARIO Cloud ships its own **MCP server**. MCP (Model Context Protocol) is the open standard AI tools use to call external systems. Install the **MCP-Server** app and any MCP client — Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, ChatGPT, LM Studio, n8n — can read and, if you allow it, write ERP data of your tenant through more than 50 curated tools. For developers this means your coding assistant no longer guesses: it asks your tenant for the exact endpoint contract, the field paths of a query source or the running version of a print layout, and tests a VQL statement before you put it into code. {% hint style="info" %} How end users connect an assistant, pick an access level and revoke keys is described in the user manual: [MCP-Server](https://help.vario-software.de/vario-cloud-handbuch/apps/apps-von-vario/mcp-server) (German). {% endhint %} ## Connect your assistant 1. Install the **MCP-Server** app in the Admin-Center of your tenant — ideally a test or development tenant. 2. Open **user settings → MCP-Server**, choose your client, an access level and the wiki scope, and click **Verbinden**. 3. Copy the generated configuration. It contains the server URL and a personal **API key**, which is shown only once. The server speaks streamable HTTP and authenticates with a bearer header. For Claude Code the generated snippet looks like this: ```bash claude mcp add --transport http vario-cloud \ --header "Authorization: Bearer " ``` Any other client that supports remote MCP servers over HTTP works the same way: server URL plus `Authorization: Bearer `. {% hint style="warning" %} **The key acts as you.** It carries your user's permissions for one year. Use a read-only key for exploring, keep keys out of repositories, and revoke them under **Meine MCP-Zugriffs-Token** when you no longer need them. {% endhint %} ## Access levels | Level | Tools the key sees | | ----------------------------- | -------------------------------------------------------------------------------------------------------- | | **Nur lesen** | Search, fetch, queries, VQL, API exploration, guides — no write tool is registered | | **Schreiben mit Bestätigung** | Additionally all write tools; destructive actions return a preview first and run only after confirmation | | **Autonom schreiben** | Write tools without the confirmation step — for supervised automations only | Write levels require the **Plus** plan or higher. The wiki is a separate axis: a key can add the wiki tools or be restricted to the wiki only. The tool list a client receives always mirrors the key's rights, so an assistant cannot call what it does not see. ## Tools that help while you build | You want to … | Tool | What it does | | ---------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Find an endpoint and its payload | `explore_api` | Live OpenAPI introspection of your tenant: search endpoints, show parameters, required fields, enums and custom fields of a schema | | Call an endpoint no curated tool covers | `call_api` / `call_api_write` | Validates path, parameters and body against the spec before sending; writes show a field diff first | | Find query sources and exact field paths | `list_query_sources`, `get_query_fields` | Enumerates groups, templates and fields at runtime — the approach recommended in [VQL](/documentation/fundamentals/vql.md#dont-guess-field-paths-ask-the-api) | | Test a query | `query_list`, `execute_vql` | Structured list queries with filters and aggregates, or a raw VQL statement | | Look up platform knowledge | `get_guide` | Built-in guides: VQL reference, `rd{}`/`rdt{}` dates, document workflow, batch scripting, import mapping, wiki, print layouts, output modules | | Run or debug a batch process | `list_batch_templates`, `run_batch`, `get_batch_run` | Lists templates and import target fields, starts a run with preview and violations, returns the result | | Work on print layouts | `list_reports`, `get_report_jrxml`, `update_report_jrxml`, `create_report`, `check_report` | Reads and edits JRXML, copies system layouts, lints them and dry-runs every query against a real record | | Open a record in the UI | `get_link` | Builds a deep link into VARIO Cloud | Beyond that the server offers business tools — documents, accounts, articles, prices, listings, CRM, wiki — plus three agents (master data audit, accounting hygiene, reorder run), interactive MCP App views and ready-made prompts. {% hint style="info" %} `explore_api` answers *what to send*, `get_query_fields` answers *which path to query*. They are not interchangeable: REST payloads and VQL field paths come from different catalogues. {% endhint %} ## Guard rails * **Your permissions apply.** Every ERP call runs under the rights of the user who created the key. * **Preview → confirm.** With **Schreiben mit Bestätigung**, destructive writes return a preview first; nothing is written before the client confirms. * **Undo.** `undo_last_action` reverses the most recent reversible write — finalizing a document, wiki changes, print layout changes and `PUT`/`PATCH` calls through `call_api_write`. Creations, master data tool writes and batch runs are not reversible. * **Blocked areas.** The generic API tools cannot touch secrets and credentials, users and roles, apps, system settings and licences, server-side scripting or the wiki. Imports only run through `run_batch`. * **Cancellation.** A cancelled request stops before the next ERP call; a write already in flight completes, so no record is left half-changed. * **Audit and rate limits.** Every call is logged in the app's protocol against the key. Each key has its own rate limit on top of the [API rate limit](/documentation/rest-api/rate-limiting.md). ## Protocol support The server is stateless and supports both the 2025 protocol revisions and the 2026-07-28 revision per request, including tool annotations, structured output, prompts, resources and MCP Apps (`ui://` resources) for clients that render them. ## FAQ ### Does the MCP server replace the REST API? No. It sits on top of the REST API and is meant for AI assistants. Production integrations should call the [REST API](/documentation/rest-api/introduction.md) directly with an App's credentials. ### Which tenant should I connect my coding assistant to? A test or development tenant. With a write key the assistant changes real data, and batch runs cannot be undone. ### Why does my assistant only see read tools? The key was created with **Nur lesen**, your user lacks the right to grant write access, or the tenant is below the **Plus** plan. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.vario-software.de/documentation/ai-assistants-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.