MCPXL30

You can run and manage the mcpXL30 MCP server to control an XL30 instrument via a safe, programmable interface. This server exposes a curated set of control functions and safety boundaries, enabling you to automate common XL30 operations while guarding against risky actions.

How to use

You operate the MCP server through a client that speaks the MCP protocol. Start the local server to use the standard input/output transport, or use a remote transport if you need HTTP-based access. The server exposes tools that let you identify the instrument, read and set high tension, manage scan modes, capture images, and perform beam and detector adjustments within defined safety limits. You can enable or disable specific capabilities to tailor what your controlling agent is allowed to do.

How to install

Prerequisites: Python and Pip must be available on your system. You may also install optional remote transport support if you plan to run the remote HTTP transport.

pip install mcpXL30
# or to enable remote transport features
pip install "mcpXL30[remote]"

Configuration and running the server

Create or edit the configuration file at the default location, or supply a custom path when you start the server. The configuration enables the instrument connection, image capture, safety envelope, logging, and optional remote server settings.

Default configuration block (example) is used to demonstrate keys you may adjust. You should populate this in your own config file according to your deployment needs.

{
  "instrument": {
    "port": "/dev/ttyUSB0",
    "log_level": "INFO",
    "retry_count": 3,
    "reconnect_count": 3
  },
  "image_capture": {
    "remote_directory": "C:\\TEMP",
    "filename_prefix": "MCPIMG_"
  },
  "safety": {
    "max_high_tension_kv": 15.0,
    "allow_venting": false,
    "allow_pumping": true,
    "allow_scan_mode_changes": true,
    "allow_stage_motion": false,
    "allow_detector_switching": true,
    "allow_beam_shift": true,
    "allow_scan_rotation_changes": true,
    "allow_image_filter_changes": true,
    "allow_specimen_current_mode_changes": false,
    "allow_beam_blank_control": true,
    "allow_oplock_control": false
  },
  "logging": {
    "level": "INFO",
    "logfile": null
  },
  "remote_server": {
    "uds": "/var/run/mcpxl30.sock",
    "api_key_kdf": {
      "algorithm": "argon2id",
      "salt": "<base64>",
      "time_cost": 3,
      "memory_cost": 65536,
      "parallelism": 1,
      "hash_len": 32,
      "hash": "<base64>"
    }
  }
}

"""

## How to run the local (stdio) server

Run the server using the standard input/output transport. This is the default mode useful for local development or single-machine setups.

mcpxl30 --config ~/.config/mcpxl30/config.json

## How to run the remote HTTP transport

If you need remote access, install the remote transport package and run the server with the remote flag. This enables a FastAPI/uvicorn interface and an HTTP-based MCP streaming API.

pip install "mcpXL30[remote]" mcpxl30 --transport remotehttp --config ~/.config/mcpxl30/config.json

## Additional configuration notes

Key sections govern safety and capabilities. The safety envelope limits high tension and several sensitive operations. Only enable tools you trust your agent to use. The server provides live MCP resources to describe the instrument and active configuration, and includes a safety-conscious design to prevent unsafe actions.

Routes and authentication details: the remote FastAPI app exposes /mcp for the MCP streaming API and /status for a health check. Authentication accepts tokens via the Authorization header, an API key header, or a query parameter. Unix domain sockets are used by default for local communication, with TCP binding available if a port is specified.

## Resources and capabilities you can access

The server makes available a wide range of control endpoints grouped by instrument actions, beam and detector controls, imaging utilities, and stage/alignment. Each setter operation runs in a background thread to preserve responsive event handling.

## Examples and bootstrap

You can bootstrap deployments with example configurations and reuse common FastMCP infrastructure, adapting it to your deployment needs. A ready-to-run configuration helps you start quickly.

## Available tools

### instrument\_identify

Return the instrument type and serial number, current scan mode, and high-tension settings.

### read\_high\_tension

Read the current accelerating voltage with safety checks.

### set\_high\_tension

Set the accelerating voltage within the safety envelope.

### get\_scan\_mode

Read the active scan mode.

### set\_scan\_mode

Change the scan mode when allowed by safety settings.

### capture\_image

Capture and store an image from the instrument.

### trigger\_photo\_capture

Trigger an immediate image capture event.

### control\_vent

Open or close the instrument chamber vent (safety gated).

### pump\_chamber

Control the chamber pump (safety gated).

### get\_spot\_size

Read the probe current setting.

### set\_spot\_size

Set the probe current within allowed range.

### get\_magnification

Read the current magnification.

### set\_magnification

Change magnification within supported limits.

### get\_stigmator

Read stigmator X/Y values.

### set\_stigmator

Update stigmator X/Y values.

### get\_detector

Inspect the active detector.

### set\_detector

Switch the active detector if permitted.

### read\_high\_tension

Included above but relevant for beam tuning.

### get\_line\_time

Read the line time setting.

### set\_line\_time

Set the line time for imaging.

### get\_lines\_per\_frame

Inspect lines per frame.

### set\_lines\_per\_frame

Adjust lines per frame.

### get\_scan\_rotation

Read scan rotation.

### set\_scan\_rotation

Change scan rotation when allowed.

### get\_area\_dot\_shift

Manage area/dot shift percentages.

### set\_area\_dot\_shift

Update area/dot shift percentages.

### get\_selected\_area\_size

Control dimensions of the selected area.

### set\_selected\_area\_size

Set the size of the selected area.

### get\_contrast

Read image contrast.

### set\_contrast

Set image contrast.

### get\_brightness

Read image brightness.

### set\_brightness

Set image brightness.

### auto\_contrast\_brightness

Run automatic contrast and brightness routines.

### auto\_focus

Run automatic focus routine.

### get\_databar\_text

Read the databar text shown on images.

### set\_databar\_text

Set the databar text.

### stage\_home

Home the instrument stage if motion is allowed.

### get\_stage\_position

Read stage X/Y/Z/tilt/rotation positions.

### set\_stage\_position

Move the stage within permitted axes.

### get\_beam\_shift

Inspect beam shift values.

### set\_beam\_shift

Adjust beam shift within safety bounds.

### get\_image\_filter\_mode

Manage image filter mode and frame count.

### set\_image\_filter\_mode

Change image filter configuration.

### get\_specimen\_current\_detector\_mode

Inspect detector mode for specimen current reading.

### set\_specimen\_current\_detector\_mode

Change detector mode for specimen current.

### get\_specimen\_current

Read the specimen current value (requires measure mode).

### is\_beam\_blanked

Inspect beam blank state.

### blank\_beam

Blank the beam when allowed.

### unblank\_beam

Unblank the beam.

### get\_oplock\_state

Inspect the operator lock state.

### set\_oplock\_state

Set the operator lock state.