MCP Server

ModbusLab can expose the running desktop workspace through a local HTTP MCP server. This lets an MCP-capable LLM client inspect live server state, validate operations, and optionally control servers, memory, watches, simulation, rules, reactions, traffic diagnostics, and import/export.

MCP access works against the live WPF application state, not a copy of the project file. The app must be running.

Enable MCP

Open Application Settings and enable MCP server.

The endpoint is:

http://127.0.0.1:<port>/mcp

By default, the server is local-only and protected with a bearer token:

Authorization: Bearer <token>

Use the copy buttons in Application Settings to copy the endpoint and token. Regenerating the token invalidates the previous one.

Security Model

MCP is disabled by default. When enabled:

  • the HTTP host binds only to 127.0.0.1;
  • token authentication is enabled by default;
  • mutation permission is disabled by default, including for projects created from files that omit the setting;
  • tools run against the same write paths used by the UI;
  • mutating tools are blocked unless Allow mutations is enabled;
  • mutating tools support dryRun where validation without changes is useful.

Use dryRun=true before applying changes from an LLM client. Read tools, resources, validation tools, and dry runs remain available while mutations are disabled.

Only the local Application Settings window can grant Allow mutations. An MCP client cannot grant that permission to itself. A client that already has mutation permission may turn the permission off remotely; after that change, the local UI is required to enable it again.

Resources

Resources are read-only JSON snapshots:

  • modbuslab://project: project path, MCP settings summary, selected server, and recent MCP diagnostics.
  • modbuslab://servers: configured servers and runtime state.
  • modbuslab://selected-server: the currently selected server.
  • modbuslab://diagnostics: runtime diagnostics for the selected server.

Read Tools

Read tools return compact JSON DTOs:

  • modbuslab_project_summary
  • modbuslab_list_servers
  • modbuslab_selected_server
  • modbuslab_server_settings
  • modbuslab_read_memory
  • modbuslab_list_watches
  • modbuslab_list_rules
  • modbuslab_runtime_diagnostics
  • modbuslab_mcp_status

Use these before mutating state so the client can resolve server names, Watch names, rule indexes, memory areas, and runtime keys.

Control Tools

Server and app control:

  • modbuslab_select_server
  • modbuslab_create_server
  • modbuslab_clone_server
  • modbuslab_delete_server
  • modbuslab_update_server_settings
  • modbuslab_update_mcp_settings
  • modbuslab_start_server
  • modbuslab_stop_server
  • modbuslab_start_all_servers
  • modbuslab_stop_all_servers
  • modbuslab_set_simulation

Memory and Watch control:

  • modbuslab_write_memory
  • modbuslab_clear_memory
  • modbuslab_capture_startup_snapshot
  • modbuslab_set_startup_memory_mode
  • modbuslab_write_watch
  • modbuslab_upsert_watch
  • modbuslab_delete_watch

Rule control:

  • modbuslab_upsert_simulation_rule
  • modbuslab_delete_simulation_rule
  • modbuslab_upsert_fault_rule
  • modbuslab_delete_fault_rule
  • modbuslab_upsert_reaction
  • modbuslab_delete_reaction
  • modbuslab_reset_rule_hits

Runtime diagnostics and cleanup:

  • modbuslab_reset_stats
  • modbuslab_clear_logs
  • modbuslab_clear_log_entries
  • modbuslab_clear_blocks
  • modbuslab_clear_block_entries
  • modbuslab_clear_inactive_clients
  • modbuslab_disconnect_client

Server transfer:

  • modbuslab_export_server
  • modbuslab_import_server

Validation Tools

Validation tools are read-only and do not change state:

  • modbuslab_validate_memory_write
  • modbuslab_validate_watch_write
  • modbuslab_validate_rule_payload

Most mutating tools also include a dryRun parameter. A dry run validates the request and returns the expected result shape without changing memory, settings, rules, logs, or files.

When a dedicated validation tool successfully performs validation, the outer call has ok=true even when the payload is invalid. Inspect result.valid, the normalized model, and the field-level errors:

{
  "ok": true,
  "result": {
    "valid": false,
    "normalized": {},
    "errors": [
      { "Field": "TargetWatchName", "Message": "Watch 'Missing' was not found." }
    ]
  }
}

Upsert and mutation tools use the same validator. An invalid mutation returns ok=false, including when dryRun=true, and does not change the workspace.

Common Workflows

Read the project and server list first:

  1. Read modbuslab://project or call modbuslab_project_summary.
  2. Call modbuslab_list_servers.
  3. Select a server with modbuslab_select_server.
  4. Read memory, watches, rules, or diagnostics.
  5. Validate planned writes or rule payloads.
  6. Re-run the same tool with dryRun=false only when the result is acceptable.

For typed values, prefer modbuslab_write_watch over raw memory writes. It uses the Watch data type, string format, byte order, and word order, then applies local write reactions through the existing app path.

For raw memory writes, pass a JSON array of booleans for bit areas or unsigned 16-bit values for register areas.

Diagnostics

MCP calls and failures are recorded in the app's MCP diagnostics. Project validation warnings and the latest save error are also exposed by project and runtime diagnostics. Use modbuslab_mcp_status, modbuslab_runtime_diagnostics, or Application Settings to inspect recent status and errors.

If a client receives 401 Unauthorized, check the bearer token. If it receives 404 Not Found, verify that it is connecting to /mcp and not /.