MCP tools
openreadout mcp runs OpenReadout as a Model Context Protocol server. It speaks over standard input and output by default, or over HTTP in builds that include it (see Transports). To connect a client, see AI agents.
The tools are the commands of the command line and return the same JSON as their --json output (the data part). Each result is sent twice: as structuredContent, checked against the tool’s output schema, and as one text block with the same JSON for clients that only read text.
When a client connects, the server sends short instructions. They say what OpenReadout reads (vendor binary formats and their text and XML exports), that indices are zero-based, that values are raw as stored unless a tool says it processed them, what the assurance level means, that only openreadout_export (data, and figures from openreadout_plot or openreadout_preview) and openreadout_extract write next to the data, that tools and arguments have the command line’s names, and that errors carry a code and a hint.
Names
A tool is openreadout_ plus the command, or the analyze subcommand, with - as _: check is openreadout_check and analyze nmr-peaks is openreadout_nmr_peaks. Its arguments are the command’s long flags with - as _: --rt-range is rt_range. Two rules cover the rest:
- A flag that can be repeated is singular on the command line and a plural list in MCP:
--channel 0 --channel 2ischannels: [0, 2]. - A flag that turns off something on by default is
--no-Xon the command line andX: falsein MCP:index --no-piiispii: false.
The command pages list each flag. Flags that only make sense in a terminal or a script (output files of a plot, compression levels, man pages) have no MCP argument; the command pages say which.
Tools
The server has 28 tools.
| tool | what it does | command |
|---|---|---|
openreadout_info |
what a file holds, from its headers | info |
openreadout_check |
integrity check | check |
openreadout_compare |
compare two files, such as a raw file and its export | compare |
openreadout_report |
a diagnostic bundle for a file OpenReadout cannot read | report |
openreadout_preview |
a picture of the data | preview |
openreadout_plot |
a finished figure from one or more files | plot |
openreadout_stats |
pixel statistics, per-well statistics of a plate, intensity profiles, polygon statistics and object counts | stats |
openreadout_trace |
samples and statistics of one sweep of a signal or 1-D spectrum | trace |
openreadout_table |
rows of a table | table |
openreadout_scans |
the scan headers of a mass-spectrometry run | scans |
openreadout_spectrum |
one mass spectrum, with its most intense peaks and their charges | spectrum |
openreadout_peaks |
chromatographic peaks; bands and regions of spectra | analyze peaks |
openreadout_chromatogram |
TIC, BPC, XIC, SRM and detector chromatograms | analyze chromatogram |
openreadout_nmr_peaks |
NMR peaks and integrals | analyze nmr-peaks |
openreadout_ephys_features |
patch-clamp features | analyze ephys-features |
openreadout_spikes |
extracellular spikes | analyze spikes |
openreadout_qpcr |
qPCR Cq, Tm, ΔΔCq and standard curves | analyze qpcr |
openreadout_gate |
flow-cytometry gating | analyze gate |
openreadout_assay |
plate-reader assays: wells and replicates, standard curves, IC50/EC50, kinetics, growth with crash and regrowth, Z′ | analyze |
openreadout_export |
export to an open format, or save a figure | export |
openreadout_extract |
write one embedded attachment, such as a slide label, to a file | extract |
openreadout_batch |
one measure over many files as one table | batch |
openreadout_summarize |
group statistics of a table written earlier | summarize |
openreadout_link |
group files of the same sample | link |
openreadout_index |
catalog every data set under directories | index |
openreadout_search |
query an index | search |
openreadout_health |
damaged, unreadable and duplicate files in an index | health |
openreadout_watch |
follow directories an instrument writes to | watch |
Every tool that reads a file takes file: an absolute path, or a path relative to the server’s working directory. It can also be a data-set directory, such as a Bruker experiment or an Agilent .D folder. The output schemas are listed by the server and described in the JSON output reference.
Strict mode
The tools that read values from a file take strict: true. A strict call refuses values the file’s assurance does not validate, with an error whose exit_code is 6. Start the server with OPENREADOUT_STRICT=1 (or openreadout --strict mcp) to make every call strict. See Assurance and strict mode.
openreadout_info
Arguments:
fileview:summary(default),full,structure,explainorformat, as ininfo --view.ask: a question in plain words, answered underanswerswith the fields each answer came from. Impliesview: "explain".max_images: list at most this many images (0 = all).thumbnail: withview: "summary", attach a small picture of image 0 (defaulttrue). See Pictures. MCP only.vendor: withview: "full", include the vendor’s metadata tree (defaultfalse; it can be megabytes).max_frames: withview: "full", per-frame records per image (default 100; 0 for none, -1 for all).
A file still being written gets the same acquisition block as on the command line.
openreadout_check, openreadout_compare and openreadout_report
openreadout_check returns the integrity report: ok and a list of findings. headers_only: true checks the structure without decoding data.
openreadout_compare compares file with against (for example its export): metadata differences, geometry, channel names and per-plane hashes. image, select, level, tolerance, ignore and no_pixels work as in compare. identical says whether the files hold the same data.
openreadout_report builds the privacy-reviewed diagnostic bundle of report, for a file that fails or is not validated. It contains no data values, and free text only with include_text: true. It is written to a file only when output is given.
openreadout_preview
Returns a picture as image content, followed by JSON that says what was drawn. Arguments as in preview: image, select, mip, composite, level, region ({x, y, width, height}), max_size (default 768, at most 2048), axes (rulers, grid, scale-bar or none; default rulers), title and caption (images; they pick scale-bar), contrast, lut and format; for traces trace, sweep and channels; for spectra run, spectrum, scan and centroid; for plates and flow cytometry table and columns; marks (auto, peaks, spikes or none), annotations (see Annotations) and dark. With format: "svg" the picture still comes back as PNG, followed by the SVG text. An unknown argument is an error that lists the known ones. The tool writes nothing; its result’s save line is the openreadout_export call that saves the picture.
openreadout_plot
Returns a figure as image content (PNG, or JPEG when the PNG would be over 750 kB), followed by JSON that says what was drawn: per panel the axes (label, unit, range) and the series with the file and selector each was read from, the points drawn, their ranges and the peaks or spikes marked. The arguments are the JSON spec of plot: data (one series or a list) and the panel keys, or panels; title, caption, theme, width and height. The tool writes nothing; its result’s save line is the openreadout_export call that saves the figure. The result’s _meta["openreadout/figure"] holds each panel’s pixel rectangle, axis ranges and thinned series, for the viewer.
An agent names the data rather than pasting it: {"file": "run.raw", "rt": "apex", "peaks": 6} is the spectrum at the TIC’s apex with its six largest peaks labelled, {"file": "plate.pda", "by": "group", "groups": ["lambda", "HK97"]} the mean and SD of two layout groups. Small numbers the agent computed itself go in values, and the result counts them under inline_series.
openreadout_stats
Per channel and image (the default), with every plane (per: "plane"), or per well or field of a screening plate (per: "well" or "field", with wells to choose wells). Other arguments: image, select, level, region, bins (default 32), scale (linear or log) and mip (z or t). Measurements on one plane: line ([x0, y0, x1, y1]) with line_width, polygon ([[x, y], …]) and objects ({kind, diameter_um, diameter_px, threshold, method, polarity, stain, split, min_area_um2, max_area_um2, max_objects}, all optional; {} counts nuclei), as described under Measurements.
openreadout_trace
One window of one sweep, in physical units, with per-channel statistics (including argmax_axis_value, the position of the maximum on the trace’s axis) and the first max_samples values (default 200, at most 10000). Arguments: trace, sweep, channels, first_sample and count, or x_range on the trace’s own axis; process: true turns an NMR FID into a spectrum.
openreadout_table
Rows of a table: table, first_row, max_rows (default about 5000 values, at most 10000 rows). For FCS files, compensate, transform, parameters, workspace, gatingml, sample and populations work as in table. filter takes conditions such as "FITC-A > 1000"; with count: true, only the number of matching rows is returned.
openreadout_scans and openreadout_spectrum
Mass spectrometry only: IR, Raman, UV-Vis and NMR spectra are traces (openreadout_trace).
openreadout_scans lists the scan headers of a run without decoding peaks, filtered by ms_level, polarity, rt_range (minutes), precursor (within precursor_tol, default 0.01 m/z, or precursor_ppm), charge, activation and scan_filter. Every match is counted. limit (default 100, at most 5000) and offset page the list, and count: true lists none.
openreadout_spectrum returns one spectrum, chosen by rt (minutes: the scan of ms_level, default 1, nearest it), scan, or spectrum (counted within ms_level when given). peaks lists the top_peaks (default 20) most intense peaks with charge, monoisotopic m/z and neutral mass; mz and intensity keep the max_points (default 1000) most intense points in m/z order. centroid: true returns the stored centroid list.
The analysis tools
Each analyze subcommand is a tool whose arguments are its flags. An argument the analysis does not take is an error that names the ones it does. openreadout_batch runs the same analyses over many files with the same arguments as options.
openreadout_peaks: chromatographic peaks with areas, widths, tailing, plates, resolution and S/N; compound lists; bands and regions of IR, Raman, UV-Vis and NMR spectra. Arguments: those ofopenreadout_chromatogramto choose the signal, plussmooth,min_snr,min_height,min_width,baseline,area_seconds,rt,window,pick,integrate,x_range,compoundsandsummary_only. See Chromatograms and peaks.openreadout_chromatogram: TIC, BPC, XIC and SRM chromatograms, or stored detector traces. Arguments:tic,bpc,mz,ppm,da,transitions,transition_tol,traces,channel,sweep,run,ms_level,polarity,scan_filter,precursor,precursor_tol,rt_range,mz_range,profile,aggregateandmax_points.openreadout_nmr_peaks: NMR peak list and region integrals. Arguments:from,trace,sweep,phase,lb,size,baseline,min_snr,min_prominence,min_height_fraction,negative,range_ppm,max_peaks,integrate,auto_integrate(one region per multiplet) andintegral_reference. See NMR processing.openreadout_ephys_features: patch-clamp features per sweep and per cell. Arguments:trace,channel,sweeps,peak_threshold_mv,dvdt_thresholdandmax_spikes. See Electrophysiology.openreadout_spikes: extracellular spike detection per channel. Arguments:trace,channels,sweeps,band_hz,threshold,sign,max_secondsandmax_times.openreadout_qpcr: Cq and Tm per well and target, ΔΔCq and standard curves. Arguments:well,target,sample,run,compute_cq,cq_method,threshold,baseline_start,baseline_end,ddcq,reference_targets,control_sample,standard_curve,undetermined_cq,max_recordsandfields(see Per-well rows).openreadout_gate: population counts, percentages and medians from a FlowJo workspace or Gating-ML file. Arguments:workspace,gatingml,sample,populations,tableandmedians(parameter names, or["all"]for every gated parameter). Withoutworkspaceorgatingml,fileis the gating file itself, described without counts.openreadout_assaytakesanalysis(wells,curve,dose-response,kinetics,growth,qc, the subcommandsassay-wells…assay-qc),layout,blank_wells,positive_wellsandnegative_wells, the arguments of that analysis (reduce,window,normalize;model,weighting,confidence,plot;standards,fit_on,lloq,uloq;wells,growth_threshold),fields(see Per-well rows), and the rarely needed plate options inplate_options:table,read,wavelength_nm,embedded_layout,layout_text,empty_wells,roles,blank_subtraction,outliers,outlier_thresholdandexclude_outliers.plot: trueadds the fitted curve as an image. See Plate-reader assays.
openreadout_export
Writes a new file, reads it back to check it, then gives it its final name. It doesn’t modify the source. An existing output is replaced only with overwrite: true.
format:ome-tiff,ome-zarr,mzml,csv,asm,rdml,parquet,arrow,nwborjcamp. Without it, the extension ofoutputsets the format, as on the command line. With neither, the default ismzmlfor mass spectra,csvfor tables and traces, andome-tifffor images.output: the output path. The default is next to the input. An extension that names no format, or one that contradictsformat, is a usage error (exit code 2).- Images:
image,select,level,regionandwells(OME-Zarr plates). - Tables, traces and spectra:
table,trace,sweep,rows,labels(CSV),spectra,runandcentroid.
Compression, chunk size, pyramid levels and vendor metadata embedding are command-line options only. The result has no output schema, because its shape depends on the format.
Saving figures
openreadout_plot and openreadout_preview only draw. To save what one of them drew, call openreadout_export with plot or preview set to the arguments of that call, instead of file:
{"preview": {"file": "slide/Young_mouse.czi", "region": {"x": 21000, "y": 9000, "width": 6000, "height": 4500}, "annotations": [{"type": "point", "x": 23900, "y": 11200, "label": "Purkinje layer"}]}, "output": "slide/cerebellum-layers.png"}output:.png,.jpg,.tiff,.svgor.pdf. The default is<data file stem>.figure.png(plots) or<stem>.preview.png(previews) next to the data.outputandoverwritegiven insideplotorprevieware used too.scale: pixels per figure pixel in PNG, JPEG and TIFF files (default 2, at most 8). Plots are drawn again at that size. An image preview is read again atmax_size×scale(at most 8192), so the saved picture has real pixels, not enlarged ones; at the default 768 × 2 it looks the same as the picture the agent saw.- An image preview is saved as a figure for people: the picture with a scale bar, the agent’s annotations and the preview’s
titleandcaption, without the rulers the agent read coordinates from (axes: "scale-bar"). Passaxes: "rulers"insidepreviewto keep them. dpi: the print resolution. PNG, JPEG and TIFF files record it; SVG and PDF pages get the size the raster would print at. The result’sprint_size_inis that size in inches.
The result is the saved picture as image content (at most 1568 px on its long side, the size a model reads), then the written file (path, format, width, height, bytes, verified), what was drawn (drawn: plot, or the preview’s kind) and the drawing’s notes and warnings. An agent can save a figure it has not drawn yet in one call and still see it.
openreadout_extract
Writes one embedded attachment, such as a slide label or thumbnail, to a new file as stored. attachment is a name that openreadout_info lists with view: "structure", or #<index>. output and overwrite work as for openreadout_export.
openreadout_batch
Runs one measure over many files and returns one tidy table: stats, trace, table, info, scans, gate, or any analysis (peaks, chromatogram, nmr-peaks, ephys-features, spikes, qpcr, or assay with analysis). Inputs come from paths (files, directories or globs, with recursive) or from an index (from_index and query); formats limits the formats. options holds the measure’s settings: for an analysis, the arguments of its tool.
sample_sheets, worksheet, keys, where, fields, by, values, replicate, exact_by, test and control work as the flags of batch. limit (default 20, at most 500) and offset page the rows; output writes the whole table to a file. A file that fails becomes a row with an error. See Many files.
openreadout_summarize
Group statistics of a table that openreadout_batch wrote with output, or of any CSV, TSV, JSON Lines, JSON or Parquet table. table is the file, and by, values, replicate, test, control, where, exact_by, output and overwrite work as the flags of summarize.
openreadout_link
Groups files that measured the same sample, from their headers. Every link has its evidence and a confidence. Arguments: paths, no_recursive, min_confidence (low, medium or high; weaker links are listed under weak_links), formats, from_index and query.
openreadout_index, openreadout_search, openreadout_health and openreadout_watch
openreadout_index catalogs every data set under roots into Parquet tables in index_dir, reading headers only. One call stops after max_files (default 20000) or max_seconds (default 45) and returns complete: false; the same call again continues where it stopped. Other arguments: check (headers, full or none), exclude, follow_symlinks (directories behind links; links to files are always read), restart, full_rescan, pii and threads. It writes only inside index_dir.
openreadout_search queries an index with the query language of search, for example format=nd2 objective=60x. total counts every match; limit (default 50, at most 1000) caps the results, and fields: ["all"] returns every column.
openreadout_health reports on the files in an index: truncated or corrupt files, formats it could not read, duplicates (confirmed by hashing their content unless no_hash: true), the same experiment stored twice, and personal-data findings. max_list (default 50) caps each list; the counts are complete.
openreadout_watch looks once at dirs per call and returns the events since cursor: new data sets, planes and scans, completed and stalled data sets, QC findings (with qc: true) and errors. stall_after sets the seconds without growth before a data set counts as stalled, and follow_symlinks walks into directories behind links (links to files are always followed; skipped directory links are named in notes). Poll with the returned cursor. The watcher persists between calls with the same dirs. It doesn’t lock files. See Lab shares, indexes and live acquisitions.
Pictures
openreadout_preview lets an agent look at the data. By default it draws image 0 (channel 0, middle z, first time point); for files without images, trace 0, spectrum 0 or the first plate table. Large images are read from the pyramid level nearest max_size. The encoded picture is kept under 750 kB: a PNG over that size is sent as JPEG, then halved until it fits, and notes says so. The same request always gives the same bytes.
Image previews have rulers labelled in full-resolution pixels, and a µm scale bar when the pixel size is known. An agent can read the coordinates of a feature off the rulers and call again with region in the same numbers. OpenReadout reads only the tiles in that region. The JSON gives the exact mapping from picture pixels to source pixels. Measure intensities with openreadout_stats, not from the picture.
openreadout_info with view: "summary" attaches a smaller picture of the same kind, about 384 px, taken from the smallest pyramid level that is large enough. When that would decode too much data, it adds a note pointing to openreadout_preview instead. thumbnail: false skips it.
The viewer
In clients that support MCP Apps, the data shows up in the chat. When the assistant calls openreadout_info, openreadout_preview, openreadout_plot, openreadout_stats, openreadout_trace, openreadout_scans, openreadout_spectrum, openreadout_table, openreadout_gate, openreadout_qpcr or one of the plate and chromatography analyses, the client opens the OpenReadout viewer next to the result. What it shows depends on the file:
| data | view | what you can do |
|---|---|---|
| images | the image plane, with a scale bar and, when zoomed in, a small map of the whole image | pick the image, channel or composite, z, time point and contrast; pan by dragging, zoom with pinch or the + and − buttons; hover for coordinates in px and µm, mm or nm |
| electrophysiology, detector traces, 1-D spectra | sweeps, one panel per channel | step through sweeps, choose channels, select a time range |
| voltammetry | current against potential, one loop per cycle | select a potential range |
| qPCR | every well’s amplification curve, coloured and labelled by target | hover a curve for its well |
| NMR | the spectrum on a ppm axis (an FID is processed first) with its peaks | select a range |
| mass spectrometry, chromatography | the TIC or a detector trace, with peaks | type m/z values for extracted-ion chromatograms, hover a peak for its area and height, click for the spectrum at that time, click a peak in a spectrum for its chromatogram, step through scans |
| plates | a heat map of the wells; for kinetic reads, a small growth curve in each well, coloured by the plate layout stored in the file (samples, groups) | hover a well for its curve with the rest of its group, scrub or play the time course, switch to a heat map at any time point, pick the read and what the colours mean |
| flow cytometry | a density plot of two parameters, or a histogram of one; with a FlowJo workspace or Gating-ML file, the events of a population coloured by its child populations | pick parameters, linear, log or arcsinh scales, and how many events to sample; click a population to open it, go back up with the breadcrumb |
figures from openreadout_plot |
the figure, drawn again in the client’s theme and at the viewer’s width | hover for every curve’s value at the pointer, drag across a plot to draw it again over that x range |
The viewer is one HTML page served as the resource ui://openreadout/viewer.html. It runs in the client’s sandbox, loads nothing from the network and asks the server for data with the tool openreadout_view. That tool is only for the viewer: clients that support MCP Apps hide it from the assistant. Its results are kept small. Pictures are at most 1600 px on their longest side and 750 kB. Plots have at most 4000 points per series, and longer signals are drawn as the minimum and maximum of each slice, so single-sample spikes stay visible. Flow-cytometry plots sample at most 50,000 events; with gating, every event of a file of up to 2 million is gated before sampling (larger files in windows spread over the run). Each result says what was reduced. The viewer draws data in the colours of OpenReadout’s pictures, and colours plate groups, populations and series by the same rule as previews and plots, so a plate looks the same in all three.
The server offers the viewer only to clients that declare the extension io.modelcontextprotocol/ui when they connect. Other clients see the 28 tools exactly as before. Set OPENREADOUT_MCP_APPS=off to turn the viewer off, or on to offer it to a client that supports MCP Apps without declaring it.
Following the assistant
When the assistant zooms into an image with openreadout_preview and region, the viewer shows the whole image first and then moves to the region, so you see where on the slide it is. The assistant’s picture has rulers to help it navigate; the viewer shows the same view without them. When the assistant marks things on a picture or plot (annotations: labelled points, boxes, outlines, arrows, bands and lines), the viewer draws them on top of the data, with labels kept apart and readable on any background. A figure made with openreadout_plot opens in the viewer too, where you can zoom into it and hover its curves for their values.
Pointing at things
You can show the assistant what you mean instead of describing it:
- Shift-drag a box on an image (or press Select first), click a point, or click one of the assistant’s labels.
- Drag across a plot to select a range, or click a chromatogram peak or a peak in a spectrum.
- Click wells on a plate (shift-click to add more, drag for a block, double-click a group name for all of its wells).
- Drag a box over flow-cytometry events, or click a population’s label.
A small bar opens next to the selection. Type a question and press Ask, and the question goes to the chat with the selection in full-resolution pixels, wells, minutes or m/z, the units the tools take. The viewer also keeps the assistant up to date with what you are looking at and what you selected, together with the tool calls that would look closer (for example openreadout_preview with that region, or openreadout_assay with those wells), so a plain “what is this?” in the chat works too. In clients that do not take messages from apps, the bar has only the zoom and copy actions.
In apps that open files with an MCP App (the ChatGPT and Codex desktop apps), the viewer is also the file viewer for .czi, .nd2, .lif, .lof, .oir, .oib, .oif, .vsi, .ims, .zvi, .mrxs, .isyntax, .ndpi, .svs, .dm3, .dm4, .fcs, .abf, .smr, .smrx, .wcp, .wiff, .wiff2 and .asyr files: opening one in a thread shows it in the viewer. OpenReadout claims only extensions that belong to one instrument format, not general ones such as .tif, .csv or .raw.
Annotations
Every tool has a title and the four MCP behaviour hints:
| tools | read-only | destructive | idempotent |
|---|---|---|---|
| info, check, compare, preview, plot, stats, trace, table, scans, spectrum, the analysis tools, link, search, health | yes | no | yes |
| watch | yes | no | no |
| index, report | no | no | yes |
| export, extract, batch, summarize | no | yes | yes |
openreadout_export, openreadout_extract, openreadout_batch and openreadout_summarize are marked destructive because, with overwrite: true, they replace an existing output file. Without it they refuse to touch an existing path. With or without it, they refuse an output that is one of the input files, however the path is spelled, and a figure that reads no file is saved only to an output the call names. openreadout_report writes only when output is given. None of the tools reach the network (openWorldHint is false for all).
Progress
When a request carries a progressToken, long calls send progress notifications whose message a host can show as is, such as “Reading 1,200 of 53,141 spectra”: openreadout_export (planes, spectra, rows or samples read; verification of the written file follows the last one), openreadout_chromatogram and openreadout_peaks (spectra read), openreadout_stats (planes read), openreadout_batch (data sets measured) and openreadout_index (data sets read so far, without a total). A tool argument that takes a list also accepts a single value ("filter": "FITC-A > 1000"), an argument that takes an object or a list also accepts it as a JSON string ("preview": "{\"file\": …}", at any depth, including inside the plot and preview of openreadout_export), and an argument of the wrong type gets a hint listing the tool’s arguments.
Errors
A call that fails returns a tool result with isError: true, so the model reads why. Its text is the message and the hint on the next line, the same as the command line’s JSON errors but in the tools’ words: a hint that names a command line, such as openreadout trace FILE --sweep N, names the tool and its arguments instead (openreadout_trace with sweep: N). A command no tool runs, such as openreadout planes, stays a command line. Notes and warnings in results are worded the same way.
usage error: plot.png exists; pass `overwrite: true` to replace ithint: Choose another output path, or pass `overwrite: true` to replace that file (the input is never modified).The result’s _meta["openreadout/error"] carries code, exit_code and hint for clients that branch on them. A call to a tool that does not exist is a JSON-RPC error.
Reply size
A reply has at most 38,000 characters of text (an openreadout_info summary 20,000), because clients refuse longer ones or set them aside in a file the model may not be able to read. Every text block counts, the JSON and anything beside it, such as the SVG of openreadout_preview with format: "svg". Most replies are far shorter.
Per-well rows
The per-well and per-group rows of openreadout_assay (growth, kinetics, wells, samples) and of openreadout_qpcr (records, relative_quantities) keep their main fields by default, rounded to 4 significant digits (whole numbers stay whole). A field is also left out of a row when it says nothing there: false, null or empty, a role nobody assigned, a group named after its well, raw equal to value, a Cq status of determined. A note lists the other fields. fields: ["all"] returns every field at full precision; fields with names returns those (and the row’s well, sample, target and group). A 96-well plate’s growth rows and a qPCR plate’s ΔΔCq records fit in one reply this way. When a plate’s rows still do not fit (a 384-well plate), the list ends at a whole plate row and a note gives the wells argument for the rest, such as wells: "J1:P24".
Over the limit, the server first leaves out a text block beside the JSON (an SVG over the limit is replaced by a pointer to openreadout_export, which saves it as a file). Then it shortens the longest lists (a plate’s per-well rows, a qPCR run’s records), and then leaves out the largest remaining parts, such as a branch of a vendor metadata tree in openreadout_info with view: "full" and vendor: true, until the reply fits. A note names each list and how many items it kept, each part left out, and the arguments that narrow the call, such as wells for openreadout_assay.
Resources and prompts
Resources:
openreadout://formats: every supported format with its read and write support, confidence and known gaps (the JSON ofopenreadout self formats).openreadout://file/{path}: the header-onlyopenreadout_infoJSON, plus the plain-English explanation ofview: "explain".openreadout://preview/{path}: the default preview as PNG or JPEG, at most 768 px.
{path} is an absolute path, percent-encoded or not: openreadout://file//data/a.czi and openreadout://file/%2Fdata%2Fa.czi are the same file.
Prompts, which clients often show as slash commands:
summarize_file(“Summarize this file”), withfile: what the file is, what was measured, how and when, with a look at the data.check_file(“Check this file and explain problems”), withfile: an integrity check, with each problem explained.convert_to_open_format(“Convert to an open format”), withfileand optionalformatandoutput: an export to the open format that fits the data, verified by reading it back.
Transports
Standard input and output
openreadout mcp with no options serves over stdio. This is what the client configurations in AI agents use.
Streamable HTTP
The HTTP transport is in builds with the mcp-http cargo feature only. Release binaries, the Docker image and the .mcpb bundles are built without it, so they contain no networking code. A build without the feature answers --http with exit code 6 and a hint.
cargo install openreadout --features mcp-httpopenreadout mcp --http 127.0.0.1:8765 # endpoint http://127.0.0.1:8765/mcpOPENREADOUT_MCP_TOKEN=$(openssl rand -hex 16) openreadout mcp --http 127.0.0.1:8765Security model:
- Loopback only by default. A non-loopback address, such as
0.0.0.0:8765or a LAN address, is refused unless--allow-remoteis given. - DNS rebinding. The
Hostheader must namelocalhost,127.0.0.1or[::1](or the bound address, with--allow-remote). Any other host gets 403. - Browsers. Any request with an
Originheader gets 403, so a web page cannot drive the server, even from the same machine. - Token. When
OPENREADOUT_MCP_TOKENis set, every request must carryAuthorization: Bearer <token>, or it gets 401. The token is compared in constant time. Set one whenever other users or processes on the machine should not reach the server, and always with--allow-remote. - What a client can do. The tools read any file the user running the server can read, and
openreadout_exportandopenreadout_extractwrite new files next to them. So can anyone who can reach the port. There is no TLS; put a TLS-terminating proxy in front for anything beyond loopback. - Only
/mcpis served. Sessions are kept in memory and end when the process stops.
Testing a server
oracle/mcp_smoke.py is a client that uses only the Python standard library. It checks capabilities, every tool’s annotations and output schema, resources, prompts, the error model and a call of every tool. With --http, it also checks that a browser Origin, a foreign Host and a missing token are refused. --synthetic writes its own small test files, so it needs no other data:
python3 oracle/mcp_smoke.py target/debug/openreadout crates/openreadout-lif/tests/fixtures/synthetic-dims.lif --synthetic