MCP server¶
ebaml-mcp gives an agent a fitted EBM through the Model Context Protocol. The
agent can read the model, read each graph and explain one prediction. The agent can also edit the model so that it meets
a business requirement, and save the edited model after a person confirms the edits. The read, explain and edit tools
call no LLM. They are fast, free and exact, and they need no API key.
A worked example, with its output, is in the MCP server notebook.
Install¶
Install the mcp extra:
pip install "ebaml[mcp]"
Start the server¶
Warning
--model also loads a pickled or joblib file, and loading such a file runs code from the file. Load only a file
that you trust, or use a skops file. The server loads only the path that you give at start. No tool can load or
write a path.
Save a fitted EBM with skops.io, which runs no code when the server loads the file. The server trusts only the EBM
classes, so it rejects a skops file that holds any other type.
import skops.io
skops.io.dump(ebm, "model.skops")
Start the server. The same option loads a skops file or a joblib file, and the server reads the format from the file:
ebaml-mcp --model model.skops --data train.parquet
| Option | Meaning |
|---|---|
--model PATH |
The EBM in a skops file, or in a pickled or joblib file. This option is required. |
--data PATH |
A Parquet or CSV file with the rows for the row argument of explain_prediction. |
--llm PROVIDER/MODEL |
Turn on the LLM tools. See Choosing the model. Without it, the server has no LLM tools. |
--output-dir DIR |
The directory where save_model writes the edited model and its history. The server creates it if it does not exist. Without this option, the server has no save_model tool. |
--labels COLUMN |
The column of --data that holds the true outcome of each row. The effect tools compute the metrics from it. |
--edits PATH |
The history file of an earlier session (*.history.json). The server replays it at start, so the work goes on. The server refuses a history that started from another model. |
--transport |
stdio (the default) or streamable-http. |
--host ADDRESS |
The address of the streamable-http transport. The default is 127.0.0.1, which accepts this computer only. |
--port NUMBER |
The port of the streamable-http transport. The default is 8000. |
The server reads the first bytes of the data file, not its extension. A file that starts and ends with the Parquet mark PAR1 is a Parquet file. Parquet keeps the type of each column. A file of UTF-8 text is a CSV file, and the server infers the types from the text. An empty file, a Parquet file that is cut off, and any other binary file raise a DataFileError that names the file and says how to save the rows.
Connect a client¶
Claude Code:
claude mcp add ebaml -- ebaml-mcp --model /path/to/model.skops --data /path/to/train.parquet
Claude Desktop. Add this entry to claude_desktop_config.json:
{
"mcpServers": {
"ebaml": {
"command": "ebaml-mcp",
"args": ["--model", "/path/to/model.skops", "--data", "/path/to/train.parquet"]
}
}
}
Any other client that starts a stdio server uses the same command and arguments. The MCP Inspector is one example:
npx @modelcontextprotocol/inspector ebaml-mcp --model /path/to/model.skops
Serve over HTTP¶
Use the streamable-http transport when the client runs on another computer or in a container:
ebaml-mcp --model model.skops --data train.parquet --transport streamable-http --port 9000
The client connects to http://127.0.0.1:9000/mcp. The server has no login. Keep the default host 127.0.0.1
unless a firewall or a proxy with authentication protects the port. With --host 0.0.0.0, every computer that
reaches the port can read the model and the rows of the data file.
Tools¶
| Tool | Arguments | Result |
|---|---|---|
get_model_summary |
optional revision |
The kind, the outputs or classes, the intercept, the number of features, and the interaction terms that the server skips. |
list_features |
optional revision |
The name, the type and the importance of each feature, the most important first. |
get_graph |
feature, optional revision, normalization, x_axis_precision, y_axis_precision, max_tokens |
The graph text of EBMGraph.to_text. |
explain_prediction |
instance or row, optional revision, confidence_level |
The LocalFacts and their texts, as JSON. |
list_bins |
feature, optional revision |
The bins of a feature with the number, the edges, the training weight and the score of each bin, and the missing and the unseen bin. |
get_edit_effect |
optional subgroup_feature, subgroup_value, revision |
The counts of the rows that the edits change, and with --labels the metrics of the original model, the model before the last edit and the current model, in three scopes. It needs --data. |
get_affected_profile |
optional revision |
For each other feature, the mix of its bins among the rows that the last edit changes and among all rows, with the l1 distance. It needs --data. |
check_constraints |
constraints, optional revision, tolerance |
One violation for each business constraint that the model breaks, with the bins, the excess and the edit that repairs it. It changes nothing. |
preview_edit |
edit, optional revision |
The report of one edit and its effect on the rows of --data. It changes nothing. |
apply_edit |
edit, reason, optional expected_revision |
Applies one edit to the session copy of the model, and returns the same result as preview_edit. |
undo_edit, redo_edit |
optional expected_revision |
Undoes the last edit, or applies it again. |
checkout_edit |
revision, optional expected_revision |
Sets the model to its state after one commit of the history. |
list_edits |
optional include_replay_json |
The history as a table of commits, and on request the JSON that --edits reads. |
save_model |
message, optional expected_revision |
Saves the edited model and its history after a person confirms. It needs --output-dir. |
describe_feature |
feature |
The words of describe_graph. It needs --llm. |
describe_model |
none | The words of describe_ebm for the current model. The server keeps the text for the revision that it describes. It needs --llm. |
The server also serves each graph as the resource ebm://graphs/{feature}.
explain_prediction works for classifiers and regressors without interactions. For other models, it returns an error
with the reason. A package error is a tool error with its message.
Each JSON result has a session field. It names the revision that the call read, the head of the session, and the
number of edits that the head holds. get_graph writes the same facts in its first line.
The edit tools work for binary classifiers and regressors. For a multiclass classifier, they return an error, and the read tools still work.
The examples below come from a real session over stdio. The model is an EBM with interactions=0 that was fitted on
500 synthetic rows with the features age, income and city. The server started with
--model model.skops --data train.parquet. A result that is long is shortened, and ... marks the cut.
Example session: read the model¶
-
The agent calls
get_model_summaryto learn the kind of the model.{"name": "get_model_summary", "arguments": {}}{ "kind": "BinaryClassifier", "outputs": ["1"], "classes": [0, 1], "score_meaning": "A score is the change of the log-odds of the class 1.", "intercept": [0.611152714154934], "feature_count": 3, "skipped_terms": [], "session": {"revision": "original", "head": "original", "edit_count": 0} } -
The agent calls
list_featuresto choose a graph. The most important feature is first.{"name": "list_features", "arguments": {}}{ "session": {"revision": "original", "head": "original", "edit_count": 0}, "features": [ {"name": "income", "type": "continuous", "importance": 1.1480326430918357}, {"name": "age", "type": "continuous", "importance": 1.1147650229232495}, {"name": "city", "type": "nominal", "importance": 0.840511802142521} ] } -
The agent calls
get_graphfor one feature. The result is text, not JSON. The server merges the bins of a continuous graph until the estimated size is nearmax_tokens. Here the budget is 1000 tokens, and the bins(18.5, 19.5),(19.5, 20.5)and(20.5, 21.5)became the bin(18.5, 21.5).{"name": "get_graph", "arguments": {"feature": "age", "max_tokens": 1000}}Revision original. The head is original, and it holds 0 applied edits. This graph represents a continuous-valued feature. The keys are intervals that represent ranges where the function predicts the same value. Feature Name: age Feature Type: continuous Means: {"(18.0, 18.5)": -2.497, "(18.5, 21.5)": -2.372, "(21.5, 22.5)": -2.283, "(22.5, 24.5)": -1.952, ...} Lower Bounds (95%-Confidence Interval): {"(18.0, 18.5)": -3.507, "(18.5, 21.5)": -3.254, "(21.5, 22.5)": -3.096, ...} Upper Bounds (95%-Confidence Interval): {"(18.0, 18.5)": -1.488, "(18.5, 21.5)": -1.491, "(21.5, 22.5)": -1.47, ...}If the budget is too small for the graph, the tool returns an error. With
"max_tokens": 100, the error says:The graph for feature age of type continuous is estimated at 652 tokens even at a simplification level of 10%.
An agent that asks for a feature that the model lacks, or for an interaction term, gets a tool error that names the features of the model.
Edit the model¶
An edit changes the scores of the bins of one graph. It changes real predictions. Apply only the edits that the person asked for, and check the effect of an edit before you apply it. A written reason and a confirmation by a person protect the model from a harmful edit, as in GAM Changer (Wang et al., KDD 2022). The edit tools call the edit API of Python (EditSession) and call no LLM. The agent is the LLM.
The server edits a copy of the model. It never changes the file of --model. A tool that reads the model, such as
get_graph or explain_prediction, reads the edited copy.
The working order¶
- Read the graph with
get_graphand the bins withlist_bins. A selection must end on the edges of the bins. - Call
preview_edit. Read the changed bins, the share of the training weight that they hold, and the effect on the data. - Call
apply_editwith areason: the business requirement that the edit serves, in one or two sentences. The history keeps it, and a person reads it later. - Tell the person what changed. Call
save_modelwith amessagewhen the person wants the edited model.
If several edits meet the requirement, propose the one that changes the fewest scores.
The edit argument¶
The edit argument is one JSON object. Its field kind names the edit, and the other fields are the fields of that
edit. The description of preview_edit and apply_edit lists every edit with its fields. A new edit of ebaml.edit
appears in the list with no new tool. A selection is a JSON object with a kind too.
kind of the edit |
Effect |
|---|---|
Shift |
Adds a value to the selected scores. |
SetScores |
Sets the selected scores to one value. |
Align |
Sets the selected scores to the score of the left bin, of the right bin, or to the weighted mean. |
Monotonize |
Makes the selected scores monotone, weighted by the training weight of the bins. |
Interpolate, FitLine |
Replaces the selected scores by a straight line, or by the weighted least-squares line. |
Clip |
Moves each selected score outside a range to the nearer bound. |
LimitSteps |
Replaces the selected scores by a weighted least-squares fit with no step between neighbour bins above step. |
Scale |
Multiplies the graph by a factor. |
ZeroTerm, RemoveTerms, RemoveFeature |
Set a graph to 0, or remove terms. The model keeps its input columns. |
Recenter |
Moves the weighted mean of a graph into the intercept. No prediction changes. |
kind of the selection |
Bins |
|---|---|
Bins |
The bin numbers from first to last, both included. A bin number is the number that list_bins gives. |
Categories |
The bins of some categories of a nominal feature. |
ValueInterval |
Every bin that overlaps an interval of values. The report names the bins that it chose. |
MissingBin, UnseenBin, WholeGraph |
The missing bin, the unseen bin, or every real bin. |
EveryBin |
The missing bin, every real bin and the unseen bin. |
An edit that sets scores does not re-centre the graph. The report shows the shift of the weighted mean of the graph
(weighted_mean_shift). Call Recenter when the person wants the shift in the intercept. A score that a person sets
has no fitted uncertainty, so its standard deviation is 0.
Business constraints¶
A person can state a business requirement as a constraint, for example "the risk must not fall when the age goes up".
check_constraints takes a list of constraints and returns one violation for each constraint that the model breaks. It
changes nothing. A constraint is a JSON object with a kind, as an edit is. The description of the tool lists every
constraint with its fields.
kind of the constraint |
Requirement | Repair |
|---|---|---|
Monotone |
The selected scores do not fall (increasing) or do not rise (decreasing). |
Monotonize |
MaxStep |
No step between neighbour bins is larger than step. |
LimitSteps |
Bounded |
Each selected score is between low and high. The default selection is EveryBin. |
Clip |
FixedScore |
Each selected score equals value. |
SetScores |
Unused |
No term uses the feature with a score other than 0, the pair terms included. | RemoveFeature |
Each violation names the bins that break the constraint, the largest excess, and the repair: an edit object that
preview_edit and apply_edit take as it is. Preview the repair and read its effect on the data before you apply it.
A repair of one constraint can break another one, so call check_constraints again after each repair.
{"constraints": [
{"kind": "Monotone", "feature": "age", "direction": "increasing", "selection": {"kind": "Bins", "first": 3, "last": 9}},
{"kind": "FixedScore", "feature": "income", "selection": {"kind": "MissingBin"}, "value": 0}
]}
The result of an edit¶
preview_edit and apply_edit return the report, its text, and the effect on the rows of --data. The report lists
the changed bins with their score before and after, the largest change, the share of the training weight that the
changed bins hold, the shift of the weighted mean, and the pair terms that still use the feature. The edit changes the
main effect only, so a pair term can still use the feature.
The effect on the data counts the rows whose prediction changes, and for a classifier the rows whose class changes. It
needs no labels. It does not say whether the edit is good. Without --data, the field effect_on_data is empty, and
effect_on_data_note says that nobody checked the effect. Tell the person when this happens.
The effect on the data and on subgroups¶
preview_edit and apply_edit count the rows that one edit changes. After an edit, get_edit_effect gives the full
Metric Panel of GAM Changer: the metrics of the original model, the model before the last edit and the current model,
for all rows, for the rows that the last edit changes, and for a subgroup (subgroup_feature and subgroup_value).
Start the server with --labels to get the metrics. Without it, the tool counts rows and says that nobody checked the
accuracy. get_affected_profile shows which subgroups the last edit reaches. Tell the person when one feature has a
large distance, because the edit then reaches one subgroup more than others.
Revisions and the history¶
Each edit is a commit with an id. A read tool takes revision: original, current or the id of a commit. A read of a
revision never changes the model. list_edits shows the history as a table of commits: the id, the time, the feature,
the type, a description, the reason, and whether a person reviewed it. undo_edit and redo_edit move the head, and
checkout_edit sets it to any commit. A new edit after an undo drops the edits that the undo moved to the redo stack.
Several clients can edit at the same time. A tool that changes the model takes expected_revision, the head that the
agent read. If the head is another one, the tool fails and changes nothing. The error names the current head, so the
agent reads again and decides if its call still fits.
Save the edited model¶
Start the server with --output-dir DIR to turn on save_model. The tool needs a message: the change that the saved
model holds. It asks the person to confirm. The question shows the message, each edit and its reason. The tool then writes
the model with skops.io and the history as JSON into the directory. Each save gets a new name, and a save never
overwrites a file. No tool argument names a path.
If the person does not confirm, the tool saves nothing. If the client cannot ask a person, the tool saves the model and
the history marks each edit as not reviewed by a person. The result names the case in the field confirmation:
person_confirmed, no_edits_to_confirm or client_cannot_ask. If the model changes while the person decides, the
tool asks again or fails, so a confirmation of an older model never saves a newer one.
Start the next session with --edits PATH and the first history file to continue the work. The server replays the edits
on the model of --model, and it refuses a history that started from another model.
Example session: edit the model¶
The model is the same as above. The requirement is: "The city must not decide the approval." The result of each call is shortened.
-
The agent reads the bins of
city.{"name": "list_bins", "arguments": {"feature": "city"}}{ "session": {"revision": "original", "head": "original", "edit_count": 0}, "feature": "city", "feature_type": "nominal", "bins": [ {"number": 0, "label": "north", "score": 0.8576651042270622, "weight": 245.0, "weight_share": 0.49}, {"number": 1, "label": "south", "score": -0.824031178571099, "weight": 255.0, "weight_share": 0.51} ], "pair_terms_using_feature": [] } -
The agent previews the edit that sets the score of
northto 0. The preview changes nothing.{"name": "preview_edit", "arguments": {"edit": {"kind": "SetScores", "feature": "city", "selection": {"kind": "Categories", "names": ["north"]}, "value": 0.0}}}{ "applied": false, "report": { "description": "Set 1 bin of city (north) to 0", "changes": [{"position": 1, "label": "north", "before": 0.8576651042270622, "after": 0.0}], "weight_share": 0.49, "weighted_mean_shift": -0.4202559010712605, "intercept_change": 0.0 }, "effect_on_data": {"row_count": 500, "rows_with_changed_value": 245, "rows_with_changed_class": 31, "largest_value_change": 0.2111567810873875}, "effect_on_data_note": null }The edit reaches 245 of 500 rows, and the class changes for 31 of them. The agent tells the person these numbers before it applies the edit.
-
The agent applies the edit with the reason. It passes the head that it read.
{"name": "apply_edit", "arguments": {"edit": {"kind": "SetScores", "feature": "city", "selection": {"kind": "Categories", "names": ["north"]}, "value": 0.0}, "reason": "The city must not decide the approval.", "expected_revision": "original"}}The result has the same fields as the preview. Its
sessionfield names the new head:{"session": {"revision": "01a1d776-fd39-7094-b038-7b55279be217", "head": "01a1d776-fd39-7094-b038-7b55279be217", "edit_count": 1}, "applied": true} -
The agent saves the model with a message. The client asks the person, and the person answers yes.
{"name": "save_model", "arguments": {"message": "Approval rules of the lending policy"}}{ "model_file": "edited-model-001.skops", "history_file": "edited-model-001.skops.history.json", "confirmation": "person_confirmed", "commit": {"kind": "save", "reason": "Approval rules of the lending policy", "reviewed": true} }
The MCP server notebook runs this session with a real server.
Chat with the agent¶
ebaml-chat opens a chat in the terminal. An LLM answers your questions with the tools of the server. Ask about the
model, or about one row of the data, and ask follow-up questions. The command starts the server for you, so you need no
other command.
ebaml-chat --model model.skops --data train.parquet
| Option | Meaning |
|---|---|
--model PATH |
The EBM in a skops file, or in a pickled or joblib file. This option is required. The same warning as for ebaml-mcp applies. |
--data PATH |
A Parquet or CSV file with the rows that you can ask about, by their number. |
--llm PROVIDER/MODEL |
The LLM of the agent. See Choosing the model. The default model needs OPENROUTER_API_KEY. |
--max-steps NUMBER |
The most rounds of tool calls for one answer. The default is 12. |
An empty line ends the chat. The server stays up for the whole chat, so only the first answer waits for it to start. After each answer, the chat prints the tools that the agent called, so you can check that the answer rests on tool results. This example is shortened:
Ask about the model, or about one prediction. Press Enter on an empty line to leave.
you> Explain the prediction for row 3 of the data.
For row 3, the model predicts class 0 with a probability of 0.581. Age (34) pushes toward this prediction, and so
does income (45.1). The smallest change that flips it to class 1 is to move age from 34 into [77.5, 78.5). ...
(tools: explain_prediction)
you> What would flip it?
Only one change flips it: age from 34 into [77.5, 78.5). That change raises the score by 0.781 ...
you>
The chat notebook runs the same command behind a chat box.
The agent remembers the earlier messages of the chat, but not the results of earlier tool calls. It calls a tool again when it needs a number. A turn that fails, for example because of a rate limit, prints its error, and you can ask again.
BAML agent¶
ebaml-chat runs chat_with_mcp, a BAML function. BAML can act as the MCP client for one question too. explain_with_mcp starts ebaml-mcp, offers its tools to a language model, and lets
the model call them. It returns the report and the names of the tools that the model called, in order. The agent needs
the BAML toolchain and OPENROUTER_API_KEY, or a model that you choose with model=.
baml run -e 'root.explain_with_mcp("Which features drive the model?", "ebaml-mcp", ["--model", "model.skops", "--data", "train.parquet"])' --output-format json
The tool_calls field shows that the report rests on tool results. A report with an empty tool_calls has no
evidence from the model. explain_with_tools is the same loop on tools that you supply, for example the tools of
another MCP server.
The BAML agent notebook runs the agent step by step.
Example session: explain a prediction¶
The agent gives the number of a row of the data file with row. It can also give the value of every feature with
instance. The tool returns the facts as numbers (facts) and the same facts as the texts of the prompts (texts).
{"name": "explain_prediction", "arguments": {"row": 0}}
{
"facts": {
"prediction": {"decision": 1, "output": 0.9564728682136135, "lower": 0.9259432129958867, "upper": 0.9747598512442751, "score": 3.089867959893999, "score_std": 0.28770285958904573, "margin": 3.089867959893999},
"contributions": [
{"feature": "age", "value": "70", "score": 1.3517285041424543, "std": 0.2544911539901107},
{"feature": "city", "value": "north", "score": 0.8576651042270622, "std": 0.08806194055932723},
{"feature": "income", "value": "53", "score": 0.2693216373695486, "std": 0.10125355589519544}
],
"counterfactual": {
"changes": [
{"feature": "age", "from_value": "70", "to_value": "[18.5, 19.5)", "score_change": -3.7239215185041488},
{"feature": "income", "from_value": "53", "to_value": "[25.5, 26.4)", "score_change": -2.5776554527787674}
],
"new_decision": 0,
"new_output": 0.9612725381888545
},
"sufficient_reason": {"features": ["income", "age"], "guaranteed_margin": 0.5450951842389209, "minimality": "sorting_proof"},
"completions": [
{"fixed": [], "share": 0.6124},
{"fixed": ["income"], "share": 0.7017},
{"fixed": ["income", "age"], "share": 1.0},
{"fixed": ["income", "age", "city"], "share": 1.0}
],
"confidence_level": 0.95
},
"session": {"revision": "original", "head": "original", "edit_count": 0},
"texts": {
"prediction": "{\n \"predicted_class\": 1,\n \"contributions_largest_first\": [ ... ]",
"counterfactual": "{\n \"flip_possible\": true,\n \"changes\": [ ... ]",
"sufficient_reason": "...",
"completions": "..."
}
}
The facts say:
- The model predicts the class 1 with a probability of 0.956.
- Two changes flip the prediction: lower
ageto the interval [18.5, 19.5), and lowerincometo the interval [25.5, 26.4). - The values of
incomeandagefix the prediction. If the agent fixes them and leavescityfree, the prediction stays the class 1 for all completions (shareis 1.0).
Example session: describe with an LLM¶
The LLM tools exist only when the server starts with --llm. These calls send requests to the provider and can cost
money. A client that starts the server must give it the API key, because most clients start the server with a small
environment. With Claude Code, use --env:
claude mcp add --env OPENROUTER_API_KEY=sk-or-... ebaml -- ebaml-mcp --model /path/to/model.skops \
--llm openrouter/openrouter/free
The agent then calls describe_feature with the name of a feature. This result is the reply of a live call to
openrouter/free, shortened. The words of a model change from call to call.
{"name": "describe_feature", "arguments": {"feature": "age"}}
The predicted effect of age begins strongly negative for ages 18-22, with a mean around -2.5 and a wide 95 % confidence
interval that stays below zero. As age increases, the effect gradually rises, crossing from negative to near-zero
between ages 46-47. ...
The first call of describe_model describes the whole model and takes longer. The server keeps the text, so the next
calls return it at once and send no request.