product: maestro audience: test-developer, operator, ai-assistant authority: normative

MCP Server — Overview

What Is the MCP Server?

WorkflowEngine.McpServer is a per-station stdio process that exposes the full Maestro API surface to any AI assistant that speaks the Model Context Protocol (MCP).

Once connected, an AI assistant can:

Start and monitor test executions by natural language instruction
Read live and historical test results, step outcomes, and measurement values
Manage test packages (download, activate, uninstall)
Read and write Station Config entries
Query system health and trigger Watchtower container updates
Download test artifacts

Everything the Maestro web UI can do, the MCP server can do — through conversation.

Architecture

  AI assistant (Claude, Copilot, Cursor, …)
        │  MCP stdio
        ▼
  WorkflowEngine.McpServer   ← one instance per station
        │  HTTP
        ▼
  WorkflowEngine.Api         ← local per-station API (http://localhost:5000)
        │
        ▼
  PostgreSQL + Redis          ← shared infrastructure

Key rules:

The MCP server is a thin proxy — it holds no state of its own. Every tool call turns into one or more HTTP requests to the local WorkflowEngine.Api.
The MCP server is launched on demand by the AI assistant via dotnet run. It does not need to run as a background service.
Each station gets its own MCP server instance. The server stamps every response with a station label so the AI assistant always knows which station produced a result.
The server communicates exclusively over stdio. It writes no log output to stdout (log output goes to stderr / the host process log) so the MCP framing is never contaminated.

When to Use the MCP Server

Good uses

Scenario	Why it works well
Automated regression runs triggered by an AI agent (CI-like, no operator present)	Use `unattendedMode: true` — prompt steps auto-respond, the test runs to completion
Diagnostic conversations — "why did SN-0042 fail yesterday?"	The AI can search results, pull step details and measurements, and explain the failure
Package management via chat — "download and activate firmware-test v2.3"	`download_package` + `activate_package` in one conversational turn
Config changes via chat — "set COM_PORT to COM4 for station ST-02"	`set_config_value` with scope `ST-02`
Ad-hoc health checks — "are all runners healthy on station A?"	`get_system_health` returns DB + Redis + runner status

When to use the UI instead

Scenario	Why the UI is better
Operator manually running a test with prompt steps that need human judgement	The UI renders prompt buttons and value-input fields; the AI cannot substitute for human judgement here
Watching live step progress with measurement charts	The Test Monitor page streams SignalR events visually
Reviewing a long multi-page report	The Test Results UI paginates and renders measurement tables

Prerequisites

Requirement	Details
.NET 10 SDK	`dotnet --version` should report `10.x.x`
Maestro API running	`WorkflowEngine.Api` must be reachable at the configured `BaseUrl` (default `http://localhost:5000`)
MCP-compatible AI assistant	Claude Desktop, GitHub Copilot (VS Code), Cursor, or any client that supports `mcpServers` stdio configuration

What the MCP Server Does NOT Do

It does not connect to hardware directly — all test execution goes through the API and the registered runners.
It does not stream live SignalR events — use wait_for_test_completion to poll until a terminal state, or call get_test_status in a loop.
It does not provide statistical analytics (yield, Cp/Cpk) in Phase 1 — those tools are planned for Phase 2.
It does not require authentication in the current release; this matches the API's current state. An ApiKey field is reserved for when the API adds auth.