Connect agents to your apps via MCP [BETA]

caution

MCP support is currently in BETA, which means we reserve the right to make breaking changes without providing an upgrade strategy. It is enabled per environment and off by default, so ask VIKTOR to enable it for your environment. Feedback is welcome on the Community Forum.

MCP lets you run your VIKTOR apps from an AI assistant such as Claude or ChatGPT. Instead of opening an app, filling in a form and reading the result yourself, you ask the assistant: "check this beam against the load table", or "generate the foundation report for this site". It runs the app and reports back.

You connect the assistant to VIKTOR once and log in with your VIKTOR account. From then on it can see the apps you have access to, fill in their inputs, run them, and read the results.

This is the reverse direction of Integrating with LLMs: there, your app code calls a language model. Here, an external agent calls your apps. No app code is needed, as any published app that meets the requirements is exposed automatically.

note

After logging in, the agent can run the apps you have access to and read their results on your behalf. It cannot change your account or credentials. As with any MCP server, only connect agents and clients you trust.

Supported clients

• Claude, ChatGPT and Gemini work out of the box.
• Clients that run on your own machine, such as Claude Code or an IDE extension, work as well.

Another web-based client needs to be added by VIKTOR before it can log in. Let us know if you would like to use one.

Connect an agent

The MCP endpoint for your environment is:

https://<environment>.viktor.ai/mcp

Replace <environment> with your own environment, for example acme.viktor.ai or acme.eu2.viktor.ai if you are in a region other than Frankfurt. The server uses streamable HTTP transport and authenticates with OAuth: your agent opens a browser window, you log in to VIKTOR as usual, and the agent is authorized.

Adding the server differs per client, so follow their instructions and use the URL above as the server URL:

Client	Instructions
Claude (web and desktop)	Getting started with custom connectors
Claude Code	Connect Claude Code to tools via MCP
ChatGPT and Codex	Extend with MCP
Cursor	Model Context Protocol
Gemini	Connect and manage custom apps

In Claude Code, for example, that is:

claude mcp add --transport http viktor https://<environment>.viktor.ai/mcp

To check that the connection works, ask the agent to call the whoami tool. It reports the VIKTOR user and environment the agent is authenticated as:

{
  "domain": "acme.viktor.ai",
  "user": { "name": "Jane Doe", "email": "jane.doe@acme.com" }
}

Which apps and views are exposed

Each view or download button in an app becomes one tool the agent can run, such as "calculate the cross-section" or "generate the PDF report", with the app's input fields as that tool's inputs. The agent reads the list of available tools, picks the one that matches your request, fills in the inputs, and runs it.

After authenticating, the agent receives a tool for every exposable view in every app you have access to. There is no selection step, so you cannot yet choose which apps to expose.

An app is exposed when it is published, visible to you, and has at least one exposable view. A view is exposed when all of its required inputs and its result type are supported.

What is supported today

The lists below reflect what MCP supports today, and they are expected to grow. A view that is not exposed today may become available in a later release without any change to your app.

Inputs supported today

Field	Becomes
NumberField, IntegerField	number, integer
TextField, TextAreaField	string
ToggleButton	boolean
OptionField, AutocompleteField	single choice
MultiSelectField	list of choices
ColorField, DateField	string
GeoPointField	{lat, lon}
GeoPolylineField, GeoPolygonField	list of {lat, lon} points
Table, DynamicArray	list of rows

Layout containers (Section, Tab, Page, Step) are passed through as nested structure and do not affect eligibility.

Not supported yet: FileField and EntityOptionField.

One unsupported field hides every view on that entity type

VIKTOR cannot yet tell which fields a particular view uses, so a tool's inputs are the whole parametrization of its entity type. If that parametrization contains a single unsupported field, none of the entity type's views are exposed, even the ones that never read that field.

If an app is missing from your agent, this is the most likely reason. Removing the unsupported field makes the remaining views available again.

For map inputs, the agent is instructed to ask you for the coordinates rather than invent them, so expect it to ask before running a view that needs a point, line or polygon.

Results supported today

• Results the agent can use in further steps: DataView, TableView, and the …AndDataView composites (the agent uses the data part).
• Results the agent returns as a file: DownloadButton, PDFView, and ImageView.

Not supported yet: purely visual views with no file to download (PlotlyView, GeometryView, MapView, WebView, IFCView, GeoJSONView, AutodeskView), and SetParamsButton, OptimizationButton and generic ActionButton.

Views that fall outside this set are left out of the tool list without an error. If an app you expected is missing entirely, none of its views are exposable yet.

Tool names

Each tool is named after the app, entity type, and method it runs:

<app>__<entity_type>__<method>

For example, a get_forecast view on a Location entity type in an app named weather-app becomes weather_app__Location__get_forecast. A short suffix is added if two tools would otherwise share a name.

Writing apps that work well as tools

The agent chooses a tool and fills its inputs based only on the app name and description, the view label, and the input labels and descriptions. A few habits make that much more reliable:

• Give views clear, descriptive labels, as the label is what the agent reads to decide whether to call the tool.
• Add a description to input fields, especially where a label alone is ambiguous. Include the unit in the label or description, because a unit set with prefix or suffix is not passed to the agent.
• State constraints the agent cannot infer from the field type in the field's description. Rules that span rows or fields ("rows must sum to 100", "start must precede end") and visibility conditions are not visible to the agent otherwise.
• Keep unsupported fields out of entity types whose views you want an agent to reach, since one such field hides all of them. Expect the agent to also see fields a given view ignores, because a tool's inputs are the whole parametrization of its entity type.

Limits

• Number of tools. An environment exposes at most 128 tools. If it has more, the list is cut off and the agent will not see every app.
• Number of clients. At most 1000 clients can authenticate within a 30-day window. Each client a user connects counts separately, so someone connecting two agents uses two of them.
• Duration. A tool call is given 10 minutes to complete. In practice the agent often gives up sooner, because a running app does not report progress back and most clients stop waiting after a shorter period. The app may still finish its run in the background. For long calculations, split them into smaller views or run them from the app interface instead.
• No tool selection. Every app you have access to is exposed and you cannot pick a subset.
• Fixed tool list per session. Apps published or shared after your agent connected only appear once the agent reconnects.
• No access to your saved work. Each call runs the app from scratch with the inputs the agent supplies. The agent cannot open the projects and data you already have in a workspace, and nothing it runs is saved back into one.
• Units set as a prefix or suffix are not passed on. The agent only reads a field's label and description, so a unit defined with prefix or suffix is invisible to it. Put the unit in the label or the description as well if the agent needs to know it.

Administrators

MCP is enabled per environment by VIKTOR, and every user authenticates as themselves, so a user can only reach the apps they already have access to. A consent screen at login is planned. There is not yet an admin toggle to allow or disallow MCP connections, or an allow-list of which apps are exposed. See agent access via MCP for what this means when deciding whether to enable it.