MCP Integration

Beta Feature

MCP Integration is currently in beta. The available tools and configuration format may change in future releases.

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 organizations it is for and has a permission list for each. It can do only what its list for an organization allows, never more than your own role there allows, and it is refused in an organization it does not name. When a tool call is refused, the refusal names the permission the token is missing. For building App Studio apps (coming soon, not part of release 3.0), the Build apps button in the dialog selects the set that job needs.

For detailed instructions, see Personal Access Tokens.

Step 2: Obtain the Organization ID

Most MCP configurations require an Organization ID to scope API requests to the correct organization.

For how to find and copy your Organization ID, see Organization 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 organization 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.

To write the settings by hand instead:

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

• Claude Code
• Claude Desktop App
• Cursor
• VS Code
• Antigravity
• Codex
• 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: Antigravity + Gemini.

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. Coming soon: App Studio is not part of release 3.0
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, data schemas, 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, organizations, 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.

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	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	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	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

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

Coming soon

App Studio is coming soon: it is in development and testing and is not part of release 3.0. This section describes it as it is being built.

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	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, and see which calls the running app was refused
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, with the scope each one needs

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

Organization & License

Tool	Actions	Description
manage_organizations	list, get, settings, maintenance_status, settings_history	View organization 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

Building an App Studio App

Coming soon

App Studio is coming soon: it is in development and testing and is not part of release 3.0. This section describes it as it is being built.

An assistant connected over MCP 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."

1. Create the token with Build apps. In the token dialog, click Build apps. It selects Apps Write plus read access to topics, pipelines, connectors and entities. If the button is disabled, its tooltip names the permissions your role lacks.
2. Describe the app. The assistant creates it, writes the code against the App Studio SDK, validates the draft, and gives you a link to the app's builder page. Validation reports 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.
3. Open the preview, then let the assistant check it. A draft that validates can still be refused at run time, for example when your role lacks a permission the app uses. After you open the builder link, ask the assistant to check the run report: it lists the calls the app was refused, errors thrown by the app's code, and live data it could not subscribe to, and the assistant fixes what it can.
4. Publish in MaestroHub. Publishing is not something the assistant can do. On the app's builder page, click Publish. Publishing shows the permissions the app requests before it goes live.

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

Only one editor works on a draft at a time. The assistant 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.

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:8080), replace https:// with http:// in the MCP server URL.
• Token management — Rotate tokens periodically and use a 1-year expiration for development.
• Organization context — The X-Organization-ID header determines which organization'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.