MCP server reference
xpd mcp starts a Model Context Protocol server, so an agent
can lint, fix, search and check Python through tools instead of a shell. The server is built on
FastMCP 4.2 and gets every rule and result from the xpd binary, so it
matches the installed version. This page and the pages below list what the server registers, as
the site's build read it from the running server. xpd mcp lists the
server's flags.
claude mcp add xpd -- uvx xpd mcpThe server is named xpd, and xpd 0.41.5 lists 21 tools, 10 resources, 2 resource templates and 5 prompts.
| Tool | What it does | May change files |
|---|---|---|
find |
Find up to five symbols, three rules and three recipes, ranked within each kind. | No |
api |
Read a public dotted name's parameters, summary, own class members and rule links. | No |
check |
Lint Python files for slow or wrong habits with pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly, Apache Hamilton and Python itself. | No |
fix |
Write xpd's fixes into the files, then lint what is left. | Yes |
graph |
Read the dataflow of step code or Apache Hamilton modules without running them: which step or node reads which, and what does not connect. | No |
profile |
Profile a data file (csv, parquet, feather, json or xlsx): each column's dtype, nulls, distinct values and memory. | No |
refit |
Fit a clone of the saved Pipeline on raw training rows and compare held out outputs and validation scores. | Yes |
equiv |
Run two scripts with the project's Python, each in its own process, and check that they leave an equal result (DataFrames and Series with pandas.testing, anything else with numpy.testing). |
Yes |
query |
Find AST patterns or syntax kinds and preview replacements without changing files. | No |
rewrite |
Preview a structural rewrite, ask for confirmation, then apply it to project files. | Yes |
outline |
Read symbols, signatures, imports, members and source ranges without execution. | No |
new |
Create a project, rule, empty case template or shared utility without prompts. | Yes |
test |
Check valid and invalid examples using xpd's scanner and compare snapshots. | Yes |
discovery_gate |
Read Python files and check direct imported calls in the chosen symbols' modules. | No |
show_issues |
Show what check finds as a sortable, searchable table, in hosts that render MCP Apps. |
No |
show_dataflow |
Show what graph reads as a flowchart of steps or nodes and a table of its problems, in hosts that render MCP Apps. |
No |
show_columns |
Show what profile reads as a table of columns, in hosts that render MCP Apps. |
No |
rules |
List xpd's rules and package checks, without their documentation. | No |
rule |
Read one rule: why it matters, what it reports, and its before and after examples. | No |
contract |
Read the contract that a training script saved beside its model: the data file and target, the split, the input columns, the steps of the Pipeline, the validation scores, and the model file with the versions that wrote it and the project files it imports when it loads. | No |
gates |
Judge a pipeline run from raw rows to a saved model. | No |
The resources page lists the resources and templates, and the prompts page lists the prompts.
Code mode
Section titled “Code mode”With --code-mode, the server lists these 3 tools in place of the ones above.
| Tool | Arguments | Description |
|---|---|---|
search |
query, tags?, detail?, limit? |
Search for available tools by query. Returns matching tools ranked by relevance. |
get_schema |
tools, detail? |
Get parameter schemas for specific tools. Use after searching to get the detail needed to call a tool. |
execute |
code |
Chain await call_tool(...) calls in one Python block; prefer returning the final answer from a single block. Use return to produce output. Only call_tool(tool_name: str, params: dict) -> Any is available in scope. |
Instructions
Section titled “Instructions”The server gives the agent these instructions when it connects.
xpd lints Python for slow or wrong habits with pandas, NumPy, SciPy, scikit-learn, scikit-lego, MAPIE, Category Encoders, linearmodels, arch, pymoo, plotly and Apache Hamilton, reads the dataflow of step code and Hamilton modules, profiles data files, and checks that a refactor keeps its result. Every path is relative to the project root.
- Before choosing a library, call `find` with the task, then `api` with a returned name. Call `api` with `Class.method` to read a method's parameters with their defaults before you call it.- After choosing and writing code, call `discovery_gate` on its files before `equiv`.- After you write or change Python, call `check`. Fix every error. Fix a warning unless you can say why the code is right. `fix` writes xpd's fixes, and asks the user before unsafe ones.- Use `query` to find code patterns and preview replacements, and `rewrite` to apply them after confirmation. Use `outline` to browse project symbols, imports and members in supported languages.- Use `new` to create a local rule project, rule, empty case template or shared utility.- To learn why a rule fires and see its before and after code, call `rule`. `rules` lists and filters all of them.- After you add, move or rename a step or a Hamilton node, call `graph`, and reuse columns that exist instead of computing their formulas again.- Before you choose methods for a data file, call `profile`.- After you refactor data logic, call `equiv` on the old and new script. The refactor is done when it says `equivalent: true`.- To build a model from a data file, follow the `build_pipeline` prompt. The run is done when `gates` returns `passed: true` for the results of `profile`, `check`, `graph`, `equiv`, `refit` and `contract`. With code mode on, one `execute` call chains them.- The show_ tools draw the same results as tables and charts in hosts that render apps.- skill://xpd/SKILL.md, skill://python-best-practices/SKILL.md and skill://python-review/SKILL.md hold the style a linter cannot check.How a call runs
Section titled “How a call runs”A tool checks that each path is inside the project root, runs the xpd binary there and returns
the binary's JSON as a typed result. find and api run in the server's working folder,
because they read no project file. discovery_gate parses the files in Python, contract reads
a JSON file, and gates only judges the results it is given.
sequenceDiagram
participant Agent
participant Server as xpd mcp
participant Binary as xpd binary
Agent->>Server: check(paths=["samples/bad.py"])
Server->>Server: check that the path is inside the project root
Server->>Binary: xpd check --format json -- samples/bad.py
Binary-->>Server: {"fixed": 0, "fixable": 0, "issues": [...]}
Server-->>Agent: the same JSON, as a typed result
The project root is --root or XPD_MCP_ROOT when one is set. A client that starts the server
in a plugin's folder sets PLUGIN_ROOT, and then the root is the first root of the client that is
a folder on the machine. Otherwise it is the server's working folder.
Errors
Section titled “Errors”A tool that cannot finish returns a tool error with a message, and the agent sees it as the
result of the call. A path outside the project root fails before xpd runs. When the binary
exits with a code that carries no result, the error names the command and its message, such as
xpd api -- no.such.name exited with 2: xpd: no entry named no.such.name. Issues, problems in
a dataflow and failed gates are results, not errors.
Background tasks
Section titled “Background tasks”A client can run check, fix, query, rewrite, outline, new, test, profile,
refit and equiv as background tasks, so it gets a task at once and fetches the result when
the tool is done. Each of them reports progress and logs the xpd command it runs.