Using xpsflow from an AI client (MCP)

The Model Context Protocol (MCP) is an open standard that lets an AI application, such as a desktop assistant, an editor agent or a chat client, discover and call tools served by a separate program. The client's model decides which tool to call; the server runs it and returns the result. xpsflow ships an MCP server that exposes its analysis tools, its templates and its reference data, so any MCP client can read instrument files, grade them, fit regions with physics constraints, quantify and report, without xpsflow knowing anything about the model on the other side. It is, as far as we know, the first MCP server for X-ray photoelectron spectroscopy.

Install the optional extra and start the server:

pip install "xpsflow[mcp]"        # or: uv pip install -e ".[mcp]"
xpsflow mcp                       # stdio, for desktop clients and editors
xpsflow mcp --http --port 8766    # streamable HTTP at http://127.0.0.1:8766/mcp
xpsflow serve                     # the web workbench also serves MCP at http://127.0.0.1:8765/mcp

By default a session can only read files inside its own, initially empty, work directory. To let the client analyze real data, point the server at a directory of instrument files:

xpsflow mcp --data ./data                 # or: export XPSFLOW_MCP_DATA_DIR=./data

Connecting a client

Claude Desktop. Add the server to the desktop configuration file (claude_desktop_config.json; its location is shown in the application's developer settings) and restart the application:

{
  "mcpServers": {
    "xpsflow": {
      "command": "xpsflow",
      "args": ["mcp", "--data", "/path/to/your/data"]
    }
  }
}

If xpsflow is not on the desktop application's PATH, give the full path to the executable inside your virtual environment (for example .venv/bin/xpsflow).

Claude Code and other editor agents. The repository contains a .mcp.json that registers the server over stdio for any project-aware client that reads that file. From the command line:

claude mcp add xpsflow -- xpsflow mcp --data ./data

Any client over HTTP. Run xpsflow mcp --http (or xpsflow serve) and point the client at the streamable HTTP endpoint, http://127.0.0.1:8766/mcp or http://127.0.0.1:8765/mcp respectively. With the official Python SDK:

from mcp.client import Client

async with Client("http://127.0.0.1:8766/mcp") as client:
    tools = (await client.list_tools()).tools
    result = await client.call_tool("load_data", {"paths": ["sample.vms"]})
    print(result.structured_content["spectra"])

Every tool returns structured JSON (the same compact result the built-in assistant receives) and raises an MCP tool error with the underlying message when a call fails.

Security model

One sandboxed session per connection. Each stdio process, and each streamable-HTTP session, owns a separate analysis session. A tool may only read files inside that session's data directory (--data, or its own work directory when none is given); any other path, absolute or relative, is refused with a PermissionError. Figures and the JSONL event log are written under XPSFLOW_RUNS_DIR/mcp/<session id>.
No network. The MCP server makes no outbound connections. Only the built-in assistant (xpsflow chat, the workbench) talks to a model endpoint, and that is a different process from the MCP client's model.
No raw spectra over the wire. Results carry metadata, down-sampled sketches, component tables, audit findings and figure paths, never full intensity arrays.
Local hosts only on the mounted endpoint. The /mcp route of the web workbench uses the SDK's DNS-rebinding protection and only accepts requests whose Host is a loopback address. To expose the standalone server on another interface, run xpsflow mcp --http --host <ip> behind whatever authentication your network requires; the server itself has none.
Bounded. At most XPSFLOW_MAX_SESSIONS (default 64) sessions are kept; the least recently used is dropped first.

Tools

The tool list is generated from the same registry the command line, the web workbench and the built-in assistant use, so a tool added to xpsflow.agent.tools appears here automatically. Required arguments are listed first; optional ones are in brackets.

Tool	Arguments	What it does
`list_files`	[directory]	List instrument files (.kal, .vms, .txt, .csv) in a directory.
`load_data`	paths	Read one or more instrument files (Kratos .kal, VAMAS .vms, ASCII) into the session.
`describe_spectrum`	key	Return metadata and a down-sampled sketch (≤ 40 points) of one spectrum.
`check_quality`	[keys]	Run the quality gate (SNR, resolution, saturation, spikes) on spectra and return grades.
`calibrate_energy`	[mode, reference_be, near, max_shift_ev]	Align the binding-energy scale of all XPS spectra using a reference peak.
`identify_survey`	[key]	Find peaks in a survey scan, identify elements and estimate a rough composition.
`lookup_element`	query · [be, window]	Look up reference data: lines near a binding energy, or chemical states of an element/core level.
`list_templates`	—	List the built-in fit templates and the regions they cover.
`propose_fit`	key · [element, orbital, max_components]	Build a starting fit template for a narrow scan from detected peaks and literature chemical states.
`use_template`	key, template	Attach a built-in template to a spectrum (by template name like "Te3d").
`edit_component`	key, component · [enabled, center, center_min, center_max, fwhm, fwhm_min, fwhm_max, lineshape]	Enable/disable or re-bound one component of the region attached to a spectrum.
`fit_spectrum`	key · [background, audit, model_selection]	Fit the region attached to a spectrum (attach one with use_template or propose_fit; if none is attached a built-in template or an automatic proposal is used).
`quantify`	[rsf_set, use_transmission, angular_correction]	Compute elemental atomic percentages from all fitted regions and partition them by chemical state.
`session_state`	—	Return what has been loaded, checked, fitted and quantified so far.
`note`	text	Record an analyst note (an observation, decision or caveat) in the session log.

Tools that only read (list_files, describe_spectrum, lookup_element, list_templates, session_state) are annotated as read-only so clients can run them without confirmation.

Resources

URI	Content
`xpsflow://templates`	The built-in fit templates: name, file, regions, description and the full YAML of each.
`xpsflow://elements/{symbol}`	One element's core levels, spin-orbit doublets and curated chemical states, each with its binding energy, range and citation (for example `xpsflow://elements/Te`).

Prompts

Name	Arguments	Purpose
`analyze-sample`	[files, calibration]	Walks the client through the standard workflow: load, grade, calibrate, identify the survey, fit each narrow scan with a template or a proposal, quantify, and summarize with the audit findings.