Local tools
Three names in mantis tools are not MCP tools. export, project, and install_extension are injected into the tool list by the CLI itself, and mantis use routes them to local code that talks to the Mantis REST API directly. They never reach the MCP server.
That matters because they behave unlike every other mantis use call: export writes a file to your disk, install_extension reads one and uploads it, and none of them go through the X-Space-State-ID MCP header path in the same way. An agent that lists tools sees them mixed in with the server tools, so it is worth knowing which is which.
export
Resolves a mantis:// URI to its full point set and writes a local parquet file. This is the sanctioned way to do bulk-row analysis: correlations, distributions, top-K, outliers.
mantis use export --uri "mantis://map/<id>"
mantis use export --uri "mantis://map/<id>/cluster/<cid>" --fields title,rating
mantis use export --uri "mantis://map/<id>" --include-embedding| Argument | Required | Meaning |
|---|---|---|
uri | Yes | Any URI resolving to a point set: map, cluster, bag, point, or selection. |
fields | No | Column names to project. Omit to export every field. |
filename | No | Output basename. Defaults to <uri-tail>_<n>rows.parquet. |
include_embedding | No | Adds _embedding (1536-d) and _embedding_2d columns. |
Files land in ~/.mantis/mantis_data/, and .parquet is appended if your filename lacks it. The call prints {path, rows, fields, format, size_bytes}, so read it back locally:
python3 -c "import pandas as pd; print(pd.read_parquet('<path>').head())"- Row cap
- 200,000
- Format
- parquet
- Written to
- ~/.mantis/mantis_data/
Every export gains three columns regardless of fields: _point_id, _cluster_id, and _cluster_label, so you can group by cluster without a second call. Over 200,000 rows the request fails with too_many_rows; narrow the URI to a cluster or bag.
export requires a configured thread, like MCP calls do.
Do not export to look around
inspect on a map gives you cluster themes and counts, inspect on mantis://map/<id>/dimensions gives the real field names, and compare with on: "distribution" summarizes a field. Reach for export only when the answer genuinely needs many rows.
project
Places text on an existing map at the coordinates that map’s trained model predicts for it, assigns it to the nearest cluster, and by default persists it as a new point.
mantis use project --map-id <map-uuid> --text "a sentence to place on the map"
mantis use project --map-id <map-uuid> --file ./abstract.txt
mantis use project --map-id <map-uuid> --text "preview only" --persist false| Argument | Required | Meaning |
|---|---|---|
map_id | Yes | Target map UUID, or a Mantis link the CLI can parse a UUID out of. |
text | One of these | The text to project. |
file | One of these | Path to a file whose contents are projected. Cannot be combined with text. |
embedding | One of these | A raw embedding vector to project. Preview only; persisting requires text or a file. |
persist | No | Defaults to true. Set false to get coordinates back without creating a point. |
service_name | No | Embedding-service override. Defaults to the map’s own configuration. |
model | No | Embedding-model override. Defaults to the map’s own configuration. |
When it persists, the response carries the new point’s URI (mantis://map/<id>/point/<pid>), which you can hand straight to inspect.
install_extension
Uploads a built extension package and installs it for the API-key user in one space.
mantis use install_extension --file ./package.mantisx --space-id <space-uuid>| Argument | Required | Meaning |
|---|---|---|
file | Yes | Local path to a .mantisx, .zip, or JSON package. |
space_id | Yes | Target space UUID or Mantis space link. |
This is a personal installation scoped to that space, not a space-wide publish, and the API-key user must own the space. The CLI checks the file exists before uploading. If the call returns 404, the backend you are pointed at does not serve the space-scoped extension install endpoint.
For what goes into a package in the first place, see Packaging and installation.
Why they are local
The MCP server does expose an export tool, but the CLI blocks that passthrough and substitutes its own, because the useful result is a file on your machine rather than JSON in a chat transcript. project and install_extension have no MCP equivalent at all: both need a local file path, which an MCP tool call cannot carry.