MCP guide

Connect a client

1. Install MedMLX with its MCP server, as on Get started:
   Install MedMLX Copy

   uv tool install --python 3.13 "medmlx[all,mcp]"

2. Give this command to your client as the server to start. The folder must already exist:
   MCP server Copy

   medmlx serve --root /path/to/work

When the client disconnects, its running jobs stop. Installing MedMLX doesn't add it to your client. You register it in the client's settings.

Tools

Your client may show these tools to you, or let the agent call them for you.

• runtime_infoNo arguments

  Reports the server folder, the platform, package versions and whether MLX and Metal work.

• list_packagesNo arguments

  Lists the model families, which runtimes are installed and any that failed to load.

• list_modelsOptional task, family

  Lists the installed models. You can filter by task, or by the segment, generate or vision family.

• list_checkpointsOptional model_id

  Lists where model checkpoints come from and their channel order. Downloads nothing.

• describe_modelmodel_id

  Shows the arguments a model takes and its author’s instructions.

• model_readinessOptional model_ids, arguments

  Checks that a model can run. With arguments, it also checks their names and that input and weight paths exist.

• run_modelmodel_id, arguments

  Starts a model in its own process and returns a job.

• get_jobjob_id, optional wait_seconds

  Shows a job’s state, the end of its log, and its result or error when done.

• list_jobsNo arguments

  Lists this session’s jobs.

• cancel_jobjob_id

  Stops a running job and anything it started.

If a model is missing, check that its family is installed and look at discovery_errors. If a run is blocked, check runtime_info, the reason and hint from readiness, and the job's error and log. list_checkpoints shows where checkpoints come from. It doesn't mean they're installed or tested.

Run a model

A run usually goes like this:

1. Call runtime_info and list_models to see what this Mac supports and which models are installed.
2. Call describe_model for the model you want. parameters lists its arguments, and instructions is the model author's own documentation. Follow it for inputs, weights, units and outputs.
3. Call model_readiness with the model ID and the arguments you plan to use, and fix anything it reports.
4. Call run_model, keep the job_id it returns, and call get_job until the job finishes. Then read the result or error and open the output files.

Example: TotalSegmentator

With a converted TotalSegmentator model and a CT image in NIfTI format in place, a client can call these tools with these arguments. Paths are relative to the server's folder; replace them with your own. The TotalSegmentator runtime documents its model folders, modes and input requirements.

{"model_id": "totalsegmentator"}

Call get_job again while the state is running. A short job may already be done the first time you check. TotalSegmentator writes mask.nii.gz to the output folder and doesn't overwrite an existing mask by default. When the run succeeds, the job result lists the output files.

To try a full MCP session without model weights, follow the FDG smoke walkthrough. It creates its own test inputs.

Readiness and jobs

model_readiness reports ready and runtime_ready, which always match. They say that the model's package loads and Metal works, not that a particular run will succeed. run_ready is false when there's a known problem, and null when none was found but the input and checkpoint files weren't checked. In this version it is never true.

When you pass arguments, pass exactly one model ID. The check confirms the argument names, that required arguments are present and that input and weight paths exist. It doesn't open the images, check their geometry, check that a checkpoint fits the model, or check whether outputs would be overwritten. run_model repeats the argument and Metal checks before starting. The model checks its own inputs when it runs, so a run can still fail.

A job is running, completed, failed or cancelled. get_job can wait up to 60 seconds for a change with wait_seconds, which defaults to 0. It returns the end of the log and, when ready, the result or error. list_jobs lists this session's jobs, and cancel_job stops a running job and anything it started. Jobs belong to the session: when the client disconnects, running jobs stop, and a new session can't see them. Cancelling doesn't delete files a model has already written.

Install from source

To run from source, you need macOS on Apple Silicon, Python 3.13 and uv. Clone the repository and install the MCP server with the model family you need. This installs the segmentation family:

git clone https://github.com/MedMLX/medmlx.git
cd medmlx
uv sync --locked --no-dev --extra segment --extra mcp

The clone starts on the main branch. To match this 0.4.2 guide, run git checkout v0.4.2 before uv sync. For other families, use generate, vision or all in place of segment.

Most models download their weights the first time they run if you leave out weights_path. To work offline, run medmlx setup --all first, or pass your own folder as weights_path. Readiness never downloads anything. MedGemma needs local weights and runs through a bridge to a separate environment.

Before connecting a client, check the install. models lists the installed models and any that failed to load, and runtime checks MLX and Metal.

.venv/bin/medmlx models
.venv/bin/medmlx runtime

Codex

Run this from the checkout. It makes a working folder in your home directory and registers the checkout's medmlx by its full path, so Codex uses the environment you just installed.

MEDMLX_WORK_ROOT="$HOME/medmlx-work"
mkdir -p "$MEDMLX_WORK_ROOT"
codex mcp add medmlx -- "$PWD/.venv/bin/medmlx" serve --root "$MEDMLX_WORK_ROOT"
codex mcp list

Start a new Codex session and check its MCP servers, or type /mcp in the terminal. Then ask it to list the MedMLX models and report runtime_info. The Codex MCP documentation covers setup and troubleshooting.

Other clients

Set the command to the full path of .venv/bin/medmlx, with serve, --root and the full path of your working folder as separate arguments. The folder must already exist. Without --root, the server uses whatever folder it starts in, which may not be the one you work in.

Files and permissions

--root sets the folder that relative paths start from. It isn't a sandbox: a model can read and write any path that your account and your client allow, and some models download files. Results and logs go back to the MCP client and can include file paths and model output, so set your client's access and data settings with that in mind.

MedMLX is research software. Matching the original model's numbers doesn't make it clinically equivalent, and every output needs human review.