Skip to main content
Version: 2.4-dev

Microsoft Copilot Studio

Microsoft Copilot Studio is a low-code platform for building AI agents. It has native MCP support (GA since May 2025), making it a great option for giving business users natural-language control over MaestroHub — without writing code.

Agents built in Copilot Studio can be published to Microsoft Teams, SharePoint, custom websites, mobile apps, and more.

Prerequisites​

Local development

For local development, use a tunnel service to expose your instance over HTTPS:

Step 1: Create an Agent​

  1. Go to copilotstudio.microsoft.com

  2. Click Create > New Agent

  3. Give it a name (e.g., "MaestroHub Assistant")

  4. Add instructions describing the agent's role. For example:

    You are a MaestroHub assistant. You help users manage their industrial data infrastructure — UNS topics, data connectors, pipelines, and dashboards. Always confirm before making changes. When listing items, format results as tables.

  5. Make sure Generative Orchestration is enabled — go to Settings > Generative AI and confirm it is turned on. MCP tools will not work without it.

Step 2: Add the MCP Server​

  1. In your agent, go to the Tools page

  2. Click Add a tool > New tool > Model Context Protocol

  3. Fill in the following:

    FieldValue
    Server nameMaestroHub
    Server descriptionIndustrial data management — topics, connectors, pipelines, dashboards
    Server URLhttps://<your-instance>/api/v1/mcp

  4. Select the Authentication type — see Authentication Options below

  5. Click Create

Step 3: Create a Connection​

After creating the tool, Copilot Studio prompts you to create a connection:

  1. Click Create a new connection
  2. Enter the required credentials (API key value or OAuth details, depending on which auth type you chose)
  3. Click Connect
  4. Copilot Studio auto-discovers all MCP tools and resources from MaestroHub

Step 4: Select Tools​

After connecting, you will see MaestroHub's tools listed. You can enable or disable individual tools. Tools stay dynamically synced — as tools are added or removed on the MaestroHub server, Copilot Studio reflects changes automatically.

Tool limit

Copilot Studio enforces a limit of 70 tools per MCP server. MaestroHub exposes more than 70 tools, so you may see a warning. Disable tools you don't need for your use case.

Step 5: Test​

Use the built-in Test Agent panel (bottom-left of the Copilot Studio editor) to send messages:

  • "List all UNS topics"
  • "What's the MQTT broker status?"
  • "Show me all connectors"
  • "List recent pipeline executions"

If the agent responds with data from your MaestroHub instance, the integration is working.

Authentication Options​

Copilot Studio offers three authentication options when adding an MCP server. MaestroHub supports two of them.

Option A: API Key (Simplest)​

Use this option to authenticate with a MaestroHub Personal Access Token (PAT). This is the fastest way to get started.

In the MCP tool wizard:

FieldValue
AuthenticationAPI Key
TypeHeader
NameAuthorization

When creating the connection, enter the full value including the scheme prefix:

ApiKey <your-token>

For example: ApiKey eyJhbGciOiJSUzI1NiIs...

This causes Copilot Studio to send the following header on each request:

Authorization: ApiKey eyJhbGciOiJSUzI1NiIs...

Limitations:

  • The PAT is tied to a single user — all agent actions run as that user
  • PATs expire (max 1 year) and must be rotated manually
  • No per-user identity — the agent cannot distinguish which end user is making the request
API key delivery behavior

Some users have reported that Copilot Studio sends the API key only on the first HTTP request in a session, not on every request. If you experience 401 errors after the first tool call, switch to OAuth 2.0 instead.

info

OAuth 2.0 authentication with Copilot Studio requires MaestroHub v2.3.0 or later.

OAuth 2.0 is the recommended authentication method for production use. Copilot Studio performs the full Authorization Code flow, and MaestroHub already has all the required OAuth2 endpoints.

B1. Register an OAuth2 Client in MaestroHub​

  1. In MaestroHub, navigate to System Management → API Clients

  2. Click Register Application

  3. Fill in the form:

    FieldValue
    Application NameCopilot Studio Agent
    Description(optional) e.g., "Microsoft Copilot Studio integration"
    Client TypeConfidential Client — Copilot Studio runs server-side and can store a secret securely
    Grant TypesCheck Authorization Code and Refresh Token
    Redirect URIsEnter a placeholder for now (e.g., https://placeholder.example.com) — you will replace this with the actual Copilot Studio callback URL in step B3

  4. Under Allowed Scopes, select the permissions your agent needs. For a typical setup, select:

    • OIDC: openid, profile, email
    • UNS: uns:read, uns:write
    • Connectors: connectors:read
    • Dashboards: dashboards:read
    • Pipelines: pipelines:read

  5. Click Register Application to create the client

  6. The Application Registered dialog appears with your Client ID and Client Secret. Copy both values immediately — the secret is shown only once and cannot be retrieved later.

Scope selection

Choose the minimum scopes your agent needs. For the full list of available scopes, see Available Scopes.

For detailed instructions on client registration including screenshots, see OAuth2 Clients.

B2. Configure OAuth in Copilot Studio​

In the MCP tool wizard, select OAuth 2.0 > Manual and fill in:

FieldValue
Client ID<client_id from step B1>
Client Secret<client_secret from step B1>
Authorization URLhttps://<your-instance>/api/v1/oauth2/authorize
Token URL Templatehttps://<your-instance>/api/v1/oauth2/token
Refresh URLhttps://<your-instance>/api/v1/oauth2/token
Scopesuns:read uns:write connectors:read dashboards:read pipelines:read

Click Create.

B3. Register the Callback URL​

After clicking Create, Copilot Studio generates a callback URL (e.g., https://...copilot.studio/...callback). You must add this URL to the OAuth2 client's redirect URIs in MaestroHub:

  1. In MaestroHub, go to System Management → API Clients
  2. Click the actions menu (⋯) on your "Copilot Studio Agent" client and select View Details
  3. Click Edit
  4. Under Redirect URIs, remove the placeholder and add the callback URL from Copilot Studio
  5. Click Save Changes

B4. Create a Connection and Test​

  1. In Copilot Studio, click Create a new connection
  2. A popup redirects you to MaestroHub's authorization page
  3. Sign in with your MaestroHub credentials
  4. Grant consent for the requested scopes
  5. You are redirected back to Copilot Studio with a valid connection

Advantages over API Key:

  • Per-user identity — the token's sub claim identifies which user is acting
  • Automatic token refresh — Copilot Studio refreshes expired tokens transparently
  • Scope-based access control — the token only grants permissions for the requested scopes
  • No manual token rotation required

Publishing Your Agent​

Once your agent is working, you can publish it to multiple channels:

ChannelUse Case
Microsoft TeamsOperations teams checking MaestroHub status from chat
Microsoft 365 CopilotEnterprise users accessing MaestroHub from Teams, Outlook, or Word
SharePointEmbedded agent on internal portals
Custom websiteCustomer-facing chatbot via JavaScript embed or iframe
Demo websiteQuick shareable link for testing and demos

To publish, go to Publish in the left sidebar of Copilot Studio and select your target channel.

Troubleshooting​

SymptomCauseFix
"Unable to connect to server"MaestroHub not reachable from Microsoft cloudEnsure the instance is publicly accessible or use a tunnel
401 on first requestInvalid or expired PAT / OAuth tokenRegenerate the PAT or re-authenticate the OAuth connection
401 after first tool callAPI key not sent on subsequent requestsSwitch to OAuth 2.0 authentication
Agent ignores MCP toolsGenerative Orchestration not enabledGo to Settings > Generative AI and enable it
No data returnedWrong organization contextCheck that the PAT or OAuth user has access to the target organization

Further Reading​