MCP server

Connect an AI assistant to MaestroHub over MCP so it can query connections, build pipelines, publish to the UNS and create dashboards for you.

Status

Available

Prerequisites

OAuth2 module · Personal Access Token

Where

Profile menu › Connect an AI client

Workspace header

X-Workspace-ID

Overview

MaestroHub exposes a Model Context Protocol (MCP) server that lets AI coding assistants interact directly with your industrial automation platform. Once connected, an AI assistant can query connections, build pipelines, publish data to the Unified Namespace, create dashboards, and more, all through natural language.

This enables use cases such as:

• Rapid prototyping: describe a pipeline in plain English and have the AI build it
• Data exploration: ask questions about your UNS topics, connections, and pipeline executions
• Dashboard creation: generate monitoring dashboards from conversational descriptions
• Troubleshooting: inspect connection statuses, execution logs, and dependency graphs with AI assistance

Prerequisites

• OAuth2 module enabled: The MCP server authenticates via Personal Access Tokens (PATs), which require the OAuth2 module
• A Personal Access Token: Generated from your profile page (see below)

Step 1: Generate a Personal Access Token

Create a PAT from your profile's Security tab. Give it a descriptive name (e.g., "MCP - Claude Code"), select an expiration period (1 year recommended for development use), and grant the permissions needed for your workflow.

A token names the workspaces it is for and has a permission list for each. It can do only what its list for a workspace allows, never more than your own role there allows, and it is refused in a workspace it does not name. When a tool call is refused, the refusal names the permission the token is missing. The dialog's For an AI client list selects the permissions for one area of work (pipelines, connections, dashboards and so on): exactly what that area's tools check, read from the tools themselves. An area your role cannot fully cover is shown greyed out, naming what your role lacks.

For detailed instructions, see Personal Access Tokens.

Step 2: Obtain the workspace ID

Most MCP configurations require a workspace ID, sent in the X-Workspace-ID header, to scope API requests to the correct workspace.

For how to find and copy your workspace ID, see Workspace Context.

Step 3: Configure Your Editor

The quickest way is inside MaestroHub: open the profile menu and choose Connect an AI client. Pick what the assistant should work on, the workspace it works in and your client, and the page writes the settings, ready to copy. Nothing is saved; paste your token where the settings say YOUR_TOKEN.

The page also lists the permissions a token needs for what you picked, and Create a token with these permissions opens the token dialog with them selected. They are read from the tools themselves, so a token created this way can use every tool the page lists, with three exceptions it names:

• Functions that delete data or are not yet classified (functions:delete, functions:invoke) and the audit trail (audit_log:read) are left out on purpose: they are not given to assistants by default. Add them in the dialog only if the assistant really needs them.
• License history needs a signed-in session; no token can read it.
• Listing users, roles and sign-in providers needs Users, Roles and Identity Providers read permissions (users:read, roles:read, identity_providers:read); the page suggests them when you pick Administration. A few actions, such as reading the license status or asking whether you yourself may do something, need no permission at all. The page lists them under actions follow your own role.

To write the settings by hand instead:

Choose your editor from the guides below to set up MCP integration:

• Claude Code
• Cursor
• VS Code
• Antigravity
• Codex
• Claude Desktop App
• Microsoft Copilot Studio

Each guide provides the exact configuration file format and location for the editor.

For real-world prompt examples with actual outputs, see the Example Prompts page. For a full end-to-end walkthrough, see Walkthrough: Claude Code.

Step 4 (optional): Choose What the Assistant Works On

By default the server lists every tool. An assistant reads the whole list at the start of every conversation, so a shorter list makes it faster, cheaper and better at picking the right tool. Name the areas you want in the server address:

https://<your-host>/api/v1/mcp?toolsets=apps,pipelines

Toolset	What it lists
apps	Build and manage App Studio apps, including the read-only plant tools the app builder uses. App Studio is in release 3.0 as Beta, a paid add-on
pipelines	Build, dry-run, start and inspect pipelines, including the connection and function tools a pipeline needs
connectors	Connections to devices, databases and brokers, their functions, and connection monitoring
uns	Topics, topic data, lineage and alerts
dashboards	Dashboards, panels and library panels, including finding and reading topics
plant	Ask about and propose changes to the plant model of the Knowledge Graph. Coming soon: the Knowledge Graph is not part of release 3.0
admin	Users, access, workspaces, license and the activity feed

Each toolset is enough for its kind of work on its own, so a tool can appear in more than one.

Search, system status and dependency lookup are always listed.

• Separate several toolsets with commas. Clients that cannot edit the address can send the same list in an X-MCP-Toolsets header.
• Leave toolsets out to list every tool.
• A name the server does not know is refused with the list of valid names, so a typing mistake shows up when the client connects.
• Toolsets only choose what is listed. What the assistant may do is still decided by the token's permissions and your role.

The list follows the token's permissions

The tool list a token receives holds only the tools it can call: a tool is listed when at least one of its actions needs a permission the token has, or needs none. A token with only Apps permissions does not receive the pipeline, connection or user tools, so the assistant spends none of its context on them. The list is read from the same declaration each tool checks when it is called, so it never hides a tool the token could use. A signed-in session (no token) lists every tool. This works together with toolsets: a toolset picks the area of work, and the token's permissions leave out what it cannot reach in that area.

A tool missing from the list is not an error. If the assistant needs it, give the token the permission the tool needs (the Connect an AI client page names it) and reconnect.

Available Tools

The MCP server exposes consolidated tools, most supporting multiple actions via an action parameter. The tables below cover the main ones, grouped by module; ask your assistant to list the tools for the full, current set. Tools for a feature your license does not include are not listed.

Connectors

Tool	Actions	Description
manage_connections	list, get, create, update, test, start, stop, delete	Manage data source/destination connections: CRUD, connectivity testing, and lifecycle control
monitor_connections	status, state_history, health_summary	Monitor connection health, state transitions, and aggregated reliability stats
manage_functions	list, get, create, update, execute, bulk_create, delete	Manage and execute connector functions (queries, API calls, pub/sub)
explore_protocols	list, get	Discover available connection protocols and their configuration schemas

Pipeline Engine

Tool	Actions	Description
manage_pipelines	list, get, create, update, apply_changes, enable, disable, validate, validate_draft, dry_run, delete	Manage data pipelines: create and edit, lifecycle control, validation, and a dry run: the saved pipeline runs once in a sandbox with sample data and returns every node's output, while connector calls and publishes are stubbed so nothing leaves the platform
query_executions	list, get	Query pipeline execution history and details. list searches one pipeline's runs, or every pipeline you may read when pipeline_id is omitted, by status, time window (since / until), execution ID fragment and zero-output runs, newest or oldest first
explore_node_types	list, get	Discover available pipeline node types and their configuration schemas
pipeline_builder_guide	-	The manual for building pipelines: how nodes relate, the expression syntax, what each built-in node is for, and complete worked pipelines. The assistant reads it once before creating or changing a pipeline

Unified Namespace (UNS)

Tool	Actions	Description
manage_topics	list, search, get, create	Manage UNS topics with hierarchical naming
query_topic_data	publish, fetch_recent, fetch_range, broker_status	Publish and query data on UNS topics, check MQTT broker status
find_signals_by_meaning	-	Every signal with one meaning, optionally under one folder, now or over a window, in the meaning's unit, one row per signal with its machine and area. Read-only, the twin of POST /api/v1/uns/data/by-meaning (Find signals). Listed with the semantic layer (Beta) in your licence
list_broker_clients	connected, away	The MQTT broker's devices, every workspace's: which are connected now, and which saved sessions wait for a device that is away. System Administrators only (uns_settings:update), and only with a signed-in session: no access-token scope grants it

Dashboards

Tool	Actions	Description
manage_dashboards	list, get, create, update, delete	Manage UNS dashboards: CRUD with grid layout, time ranges, and variables
manage_panels	list_types, get_type, add, update, remove	Manage dashboard panels and discover available panel types

App Studio

Beta

App Studio is in release 3.0 as Beta: a paid add-on that no edition includes by default. A licence or a trial licence that includes the app_studio feature switches it on. The module is on by default, so the licence decides. Names and steps may change while it is in Beta.

Tool	Actions	Description
app_builder_guide	-	The reference for building an app: the app's shape, its manifest, the SDK and UI kit, and the rules the platform enforces. The assistant reads it once before writing app code
manage_apps	list, get, create, update, list_templates, list_versions, run_report, publish, rollback	Find the apps you may read, create a new one (from a minimal starter or a template), rename it or switch it off, see what has been published, see which calls the running app was refused, and ask for a release or a rollback, which a person approves
manage_app_source	list_files, read_file, edit_file, write_file, delete_file, validate, checkpoint, list_checkpoints, restore_checkpoint, release	Work on an app's draft: read and edit its files, validate it, save and restore checkpoints, and release the editing seat
find_topics	-	Search the UNS topics an app can bind
find_pipelines	-	Search the pipelines an app can start, with their manual trigger nodes
find_functions	-	Search the saved connector functions an app can run in plant language (names, descriptions and labels of functions and their connections), with the scope each one needs and the params it takes
try_function	-	Run a saved read or discover function once and return the exact result the app's connectors.execute gets (write and stream functions are tried in the app's preview instead)

Dependencies

Tool	Actions	Description
query_dependencies	graph, dependents, dependencies, impact, orphans, insights, stats, node	Query the dependency graph: relationships, impact analysis, orphans, and insights

Authentication & Authorization

Tool	Actions	Description
manage_users	list, get, stats	View users and user statistics
list_identity_providers	-	List configured SSO identity providers (OIDC, LDAP, SAML)
manage_access	list_roles, user_roles, role_members, check	Query roles, role assignments, and access permissions

Workspace & License

Tool	Actions	Description
manage_workspaces	list, get, settings, maintenance_status, settings_history	View workspace details, settings, and maintenance status
manage_license	status, features, history, check_feature	View license status, enabled features, and history

Scheduler & Search

Tool	Actions	Description
manage_scheduler	stats, trigger, list_webhooks	View scheduler status, start a pipeline's manual trigger (optionally with input data, to try a pipeline), and list webhook endpoints
search	query, find_by_id, stats	Search across all entity types (pipelines, connections, functions, topics, models, dashboards)

System Status

Tool	Actions	Description
get_system_status	websocket, presence	Get WebSocket server status and pipeline editor presence

Deleting through MCP

manage_connections, manage_functions and manage_pipelines can delete, with the same checks as deleting in MaestroHub: the token needs the write scope (connectors:write or pipelines:write), your role must allow the delete, and nothing may depend on what you delete.

• If something depends on it, the delete is refused with code CONFLICT and the same details as the REST API's 409 HAS_DEPENDENTS: details.dependents lists what depends on it, and details.hiddenDependents counts dependents you are not allowed to see. Those are not named; someone who can read them has to clear them. Delete in order: the pipelines that use a function, then the function, then its connection.
• If every dependent is one that heals by itself, such as a topic a pipeline publishes to, the refusal says so. Call the delete again with ignore_warnings: true to go ahead.
• There is no force delete over MCP. A user with the force_delete permission can force a delete in MaestroHub.
• A delete over MCP is not previewed. A blocked delete is its own preview (the refusal lists what blocks it); a delete with nothing in the way goes through at once, so confirm it with the user first.

Building an App Studio App

Beta

App Studio is in release 3.0 as Beta: a paid add-on that no edition includes by default. A licence or a trial licence that includes the app_studio feature switches it on. The module is on by default, so the licence decides. Names and steps may change while it is in Beta.

Your own AI client (Claude Desktop, Claude Code, Cursor or any MCP client) can build an App Studio app for you from a description, for example "Build an app that shows the line 1 temperature and lets the operator add a shift note." This does not need MaestroHub's built-in assistant: when no AI provider is set up, or the AI Assistant is not installed, your client is how apps are built. You watch the app take shape in MaestroHub, and nothing goes live until a person approves it.

1. Start in App Studio. Open App Studio → New app, describe the app, and choose Build with your AI client. MaestroHub creates the app and opens its builder with a prompt to copy into your client. The prompt names the app and tells the client where to start.

2. Connect your client once. The builder's Connect an AI client button opens the connect page with the Apps toolset and this workspace already chosen. Create a token with these permissions fills the new token into the settings it shows, so there is nothing to paste by hand. The token can build apps and ask for releases (Apps Write), with read access to the topics, pipelines, connections and entities an app binds to; if the choice is greyed out, it names the permissions your role lacks.

3. Paste the prompt and watch. The client reads app_builder_guide, writes the app with manage_app_source and validates it. The builder's preview rebuilds within seconds of each change, and the panel says when the draft last changed. Validation names a missing permission in the app's manifest, an SDK name that does not exist, or code that does not compile, with the file and line.

4. Let the client check what you see. A draft that validates can still be refused when it runs, for example when your role lacks a permission the app uses. While the preview is open, ask the client to check manage_apps → run_report. It lists:

   • the calls the app was refused, each with its reason code (ACTION_NOT_DECLARED, INSUFFICIENT_SCOPE, APP_ENDPOINT_NOT_ALLOWED …);
   • errors thrown by the app's code;
   • live data it could not subscribe to;
   • what the preview rendered.

   The client fixes what it can.

5. Ask for a release; a person approves it. When the app is ready, the client calls manage_apps → publish. That makes a release request, it does not publish. The builder shows Release v1 is waiting for approval, and the Apps library lists it for everyone who may publish the app. Review shows the files that changed and the permissions viewers would grant; Approve and go live publishes it. Only a signed-in person can approve, never a token or an assistant. The client reads the outcome with manage_apps → get, including the reason when a request is rejected. rollback asks the same way for an earlier version to go live again.

The app runs as whoever opens it: each person sees only what the app's manifest requests and their own role allows. Changes the client makes are saved as checkpoints marked as made by an assistant, so they show in the app's history and can be undone.

Only one editor works on a draft at a time. The client takes the editing seat when it writes and releases it when it is done; if someone else is editing, its change is refused and nothing is written.

For one recorded session with screenshots, see Walkthrough: build an App Studio app. To build an app over several rounds, saying what you see in the preview each time, see Prompting an AI client to build apps: five prompts that built a live 3D twin of the Digital Factory Simulator line.

Tips & Best Practices

• HTTP vs HTTPS: The examples in these guides use https://. If your MaestroHub instance is deployed locally without TLS (e.g., http://localhost:6163), replace https:// with http:// in the MCP server URL.
• Token management: Rotate tokens periodically and use a 1-year expiration for development.
• Workspace context: The X-Workspace-ID header determines which workspace's data the AI can access. Make sure it matches your target environment.
• Tool discovery: Ask the AI "What MCP tools are available?" to get a full list of capabilities. The AI can also call explore_node_types and explore_protocols to discover what pipeline nodes and connector types are supported.
• Iterative building: Start with simple pipelines and add complexity incrementally. The AI can update existing pipelines with manage_pipelines (action: update).
• Impact analysis: Before modifying or deleting a connection or function, ask the AI to run query_dependencies with action impact to understand what will be affected.