AI Agents (novomodelo-mcp)
novomodelo-mcp is a local Model Context Protocol (MCP) server for Novomodelo. Through it, an AI agent in an MCP client that runs local servers validates, converts, compares, runs and reads the results of cases with a fixed set of tools, and answers methodology questions from the pages of this site. Depending on the client, it works in a terminal (such as Claude Code or Codex), in a desktop application (such as Claude Desktop) or in an IDE (such as Kiro, or GitHub Copilot in VS Code).
The server is a facade over the programs Novomodelo already ships. The tools that
validate, summarize, convert, compare and run a case call a subcommand of the
novomodelo CLI or of novomodelo-bridge (with --json
where the subcommand has it), or the novomodelo-python bindings, and relay the
result: the server carries no conversion, validation, comparison or solving logic of
its own. The other tools read the case files, the run outputs and the bundled
documentation, and run_plan computes its own estimate of a run’s time and memory.
The server speaks MCP over stdio: the client starts it as a subprocess, and it opens no network port. Its messages and response fields are in Portuguese, and the bundled documentation is this site, in English. The language model in the client translates both ways, so a person can ask in their own language and read the answer in it, which makes Novomodelo easier to use.
Requirements
Seção intitulada “Requirements”| Component | Requirement |
|---|---|
| Python | 3.12 or newer |
| uv | installs the server as an isolated tool |
novomodelo (the CLI) | installed separately (see Installation), or by the agent with the install_novomodelo tool |
novomodelo-bridge, novomodelo-python | installed with the server |
The server runs on Windows, macOS and Linux, including containers.
On Linux, the pre-built novomodelo executable needs a recent glibc and its
installer needs xz; Installation
gives the versions and the crates.io install for older systems.
One version for every component
Seção intitulada “One version for every component”The server, the novomodelo executable, novomodelo-python and novomodelo-bridge
share one version number: novomodelo-mcp X.Y.Z works with novomodelo X.Y.Z. The
package pins novomodelo-bridge at that version, and the bridge pins
novomodelo-python at it. A fix to the server
alone is released as X.Y.Z.postN. Keep the novomodelo executable at the same
version too: the solver loads only a policy written by the same version.
Version warnings reports any component that differs.
Installation
Seção intitulada “Installation”uv tool install --compile-bytecode novomodelo-mcp # isolated, on-PATH CLI (recommended)pipx install novomodelo-mcp # alternativepip install novomodelo-mcp # into the current environmentThe first two put the novomodelo-mcp executable on your PATH, with
novomodelo-bridge and novomodelo-python in an environment of its own; pip installs
the three into the active Python environment. On a
corporate network whose proxy re-signs certificates, uv may fail to reach PyPI
with UnknownIssuer; add --system-certs (or set UV_SYSTEM_CERTS=1) so uv
uses the system certificates.
To upgrade, run uv tool upgrade novomodelo-mcp (or pipx upgrade novomodelo-mcp, or pip install --upgrade novomodelo-mcp).
Installing with an AI agent
Seção intitulada “Installing with an AI agent”The agent in the client can install and configure the server for the person. Paste this request into the agent:
I want to install the Novomodelo MCP server (the novomodelo-mcp package, on PyPI) on this machine. Follow the steps below, in order.
How to work:- Answer in the language I usually use with you. If you are not sure which one I prefer, ask me first.- If you can run commands on this machine, run them yourself, but show each command first and wait for my approval.- If you cannot, guide me step by step: one command at a time, waiting for me to paste the output before going on.- If a step fails, stop and explain the error before trying anything else.
Steps:1. Find out the operating system: Windows, macOS or Linux. On Windows, use PowerShell. On Linux, also run `ldd --version` and `xz --version`. If glibc is older than the version the Novomodelo installation page asks for (https://docs.modelossetoreletrico.org.br/docs/getting-started/installation/), tell me that the MCP server installs but the pre-built novomodelo executable does not run, and point me to that page. If xz is missing, tell me to install the xz-utils or xz package.2. Check whether uv is installed (`uv --version`). If it is missing, install it with the official installer (https://docs.astral.sh/uv/getting-started/installation/) and reload the terminal.3. Install the server: `uv tool install --compile-bytecode novomodelo-mcp`. If uv cannot reach PyPI and reports UnknownIssuer (a corporate proxy that re-signs certificates), run it again with `--system-certs`. If novomodelo-mcp is not found afterwards, reload the terminal.4. Ask me which MCP client I use, and which folders the server may read and write: where my studies, decks and cases are. There can be several. Do not suggest or choose folders for me: wait for my paths and check that they exist. - For Claude Code, Claude Desktop or Kiro, build the command with one --workspace per folder and run it first only to show what would be written: novomodelo-mcp configurar --cliente <claude-code, claude-desktop or kiro> --workspace "<folder 1>" --workspace "<folder 2>" --mostrar Show me the result. After I approve, run the same command without --mostrar. If you are Claude Code yourself, do not run it: Claude Code rewrites ~/.claude.json while it is open. Give me the command with ! in front, for me to paste here, and then ask me to quit Claude Code and open it again. - For any other client, find in its documentation where it keeps its MCP servers and add an entry named novomodelo: the command is the absolute path of the novomodelo-mcp executable (`which novomodelo-mcp` on macOS and Linux, `where.exe novomodelo-mcp` on Windows), with no arguments, and NOVOMODELO_MCP_WORKSPACE holds my folders, separated by : on macOS and Linux and by ; on Windows. Show me the change before writing it.5. Ask me to quit the client, open it again and, in a new conversation, ask "run server_info". If the novomodelo server does not show up, go back to step 4.6. If server_info says the novomodelo executable is missing, tell me to ask, in the same conversation: "install the novomodelo executable".Configuring a client
Seção intitulada “Configuring a client”Every MCP client starts the server from one entry in its configuration. The entry is the same in every client; the file that holds it, and the key that lists the servers, depend on the client and are described in its documentation:
{ "mcpServers": { "novomodelo": { "command": "/absolute/path/to/novomodelo-mcp", "args": [], "env": { "NOVOMODELO_MCP_WORKSPACE": "/path/to/your/studies" } } }}command is the absolute path of the novomodelo-mcp executable: which novomodelo-mcp
on macOS and Linux, or where.exe novomodelo-mcp on Windows, prints it. NOVOMODELO_MCP_WORKSPACE holds the
folders the server may read and write (see Workspace). The agent in the
client can also be asked to add the entry.
Run on its own in a terminal, novomodelo-mcp starts the server and waits for a client
on standard input, so it shows nothing; the client starts it, and a person does not
need to.
Writing the entry with configurar
Seção intitulada “Writing the entry with configurar”For Claude Code, Claude Desktop and Kiro, novomodelo-mcp configurar writes the entry,
and the list of read-only tools where the client has one. With Claude Code as the
example:
novomodelo-mcp configurar --cliente claude-code --workspace ~/studies --mostrar # print the change onlynovomodelo-mcp configurar --cliente claude-code --workspace ~/studies # write it| Option | Effect |
|---|---|
--cliente <client> | Required. One of claude-code, claude-desktop or kiro. |
--workspace <folder> | A folder the server may read and write (see Workspace). Repeat it for more than one folder; a folder that does not exist is created when the entry is written. |
--irrestrito | Write the entry with no workspace: the server reads and writes any folder. Cannot be combined with --workspace. |
--mostrar | Print only the part of each file that would change, and touch nothing. |
--instrucoes | Also write a line that tells the agent to use the server for methodology questions (see the table below). |
The workspace has no default. Without --workspace or --irrestrito, the command
asks for the studies folder when it runs in a terminal; with no terminal it exits
with code 2 and writes nothing.
The entry is named novomodelo. The command changes only that entry (and, where the
client has one, the list of read-only tools it runs without asking) and keeps the
rest of the file. An existing novomodelo entry is replaced whole. Before writing,
the command saves a backup next to the file as <file>.bak-YYYYMMDD-HHMMSS; running
it again with nothing to change writes nothing. If the client is not installed on
the machine, the command says so and writes the entry anyway, ready for when the
client is installed.
| Client | Configuration file | Read-only tools | --instrucoes writes to |
|---|---|---|---|
| Claude Code | ~/.claude.json (user scope) | one permissions.allow rule per tool in ~/.claude/settings.json | ~/.claude/CLAUDE.md |
| Claude Desktop | macOS ~/Library/Application Support/Claude/claude_desktop_config.json; Windows %APPDATA%\Claude\claude_desktop_config.json; Linux ~/.config/Claude/claude_desktop_config.json | no list: choose “always allow” on a tool’s first call | prints the line, to paste into the preferences |
| Kiro | ~/.kiro/settings/mcp.json (a workspace’s .kiro/settings/mcp.json takes precedence) | Kiro asks for approval and ignores an autoApprove list in the server entry | ~/.kiro/steering/novomodelo.md |
Claude Code rewrites ~/.claude.json while it is open: close it before configurar
writes its entry.
Checking the setup
Seção intitulada “Checking the setup”After adding the entry, quit the client completely and start it again. Then ask the
agent to call the server_info tool: it reports the server version, the executables
it found, the version of each component, the workspace and where the documentation
comes from. The client prefixes each tool with the server name, as in
mcp__novomodelo__case_validate.
Each tool declares, through the MCP annotations readOnlyHint, destructiveHint and
openWorldHint, whether it only reads or also writes. A client can use these hints
to run the read-only tools without asking; the client and the organization’s policy
make the final decision.
| Kind | Tools |
|---|---|
| Read only | server_info, solver_version, schema_list, schema_get, docs_list, docs_read, docs_search, deck_list, deck_read_json, deck_read_parquet, deck_describe_parquet, deck_sql, case_validate, case_summary, bridge_check_*, results_status, results_convergence, results_list_entities, results_query, results_stochastic, results_policy, run_plan, run_status, run_logs |
| Writes new files | case_init, schema_export, bridge_convert_*, bridge_compare_*, bridge_dashboard, include_folders |
| Changes or stops | deck_edit_json, deck_edit_parquet, run_apply, run_start, run_cancel, install_novomodelo |
novomodelo-mcp configurar --cliente claude-code --workspace <folder> --mostrar
prints the list of read-only tools that configurar writes, read from the server
itself.
By stage of a study:
- Before a run.
bridge_check_*andbridge_convert_*check and convert a case from another planning tool with novomodelo-bridge (one tool per source format; see Case Conversion).case_validatevalidates a case through thenovomodelo-pythonbindings; withoutput_dir, it also checks the output of an earlier run for a resume.case_summarylists the case as Novomodelo loads it: counts per entity type and the{id, name}of each entity. - Cases and decks.
deck_listmaps a case: its input files with their schema type, and one line per run folder.deck_read_json,deck_read_parquetanddeck_describe_parquetread input files.deck_edit_jsonanddeck_edit_parquetedit them with a backup and an atomic write; withensure_valid=True,deck_edit_jsonrevalidates the case and reverts the edit if validation fails.deck_sqlruns read-only DuckDB SQL (SELECT,WITH,DESCRIBE,SUMMARIZE) over the Parquet, CSV and JSON files of a case or of its results. - Running.
case_initcreates a case from a bundled template (novomodelo init).run_planwrites nothing and runs nothing: it estimates the time and memory of a local run from solve times measured on the same machine, and returns a verdict (cabe,cabe_com_ajustes,nao_cabeorindeterminado) with suggested settings.run_applyapplies those settings toconfig.json.run_startstartsnovomodelo runin the background and returns a job id at once; it refuses a case whose plan isnao_cabe, unless called withoverride=True. It also refuses an output folder that holds a finished run, because running there again deletes that run: the refusal (exit code 17) gives a free folder insuggested_output, andoverwrite=Truereplaces the earlier run.run_status,run_logsandrun_cancelfollow and stop the job. A job survives a restart of the server. - Results.
results_statusreads the run status, bounds, gap, iterations and cost;results_convergencethe convergence record;results_list_entitiesandresults_querythe simulation output;results_stochasticthe inflow-model coefficients and the opening tree (it needsexports.stochastic: truein the run’sconfig.json);results_policya summary of the trained policy.bridge_compare_*compares a converted case’s results with the source tool’s published results, andbridge_dashboardwrites an HTML dashboard of a case. - Reference.
schema_listandschema_getreturn the JSON Schemas of the input files (also available as the resourcenovomodelo://schema/{type});schema_exportwrites them to a folder.docs_list,docs_searchanddocs_readread the bundled documentation (see Documentation and changelogs). - Diagnostics.
server_infoandsolver_versiondescribe the installation;install_novomodeloinstalls thenovomodeloexecutable;include_foldersadds folders to the workspace.
Responses that carry rows or lists are capped in size; a capped response says so in
size_truncation.
Security
Seção intitulada “Security”Workspace
Seção intitulada “Workspace”The case, deck and result tools take paths chosen by the agent.
NOVOMODELO_MCP_WORKSPACE holds the allowed root folders, separated by the system
path separator (: on macOS and Linux, ; on Windows), and
configurar --workspace writes it into the client entry. With it set, the server
refuses any path outside those roots, after resolving symbolic links and ...
Without it, the server runs unrestricted, and server_info reports
irrestrito.
A refused path returns exit code 13, the folder of the path in suggested_folder, and
an instruction to the agent: do not read the path through other tools, and ask the
person whether the folder may be added. With the person’s consent, the agent calls
include_folders with every folder at once. The folders take effect at once, with no
client restart, and are stored in pastas.json in the server’s state folder,
added to the roots of NOVOMODELO_MCP_WORKSPACE. include_folders is never on
the read-only list, so the client asks for approval on every call. It refuses a path
that is not a folder, the home folder or any folder above it, the root of a disk,
the configuration folders of programs (names starting with ., AppData,
Library) and the state folder. An unreadable pastas.json allows nothing.
Approval for writes
Seção intitulada “Approval for writes”The tools that write or change files are not on the read-only list that
configurar writes, so the client asks for approval before each call.
Forced writes
Seção intitulada “Forced writes”Three forms of call override a safety check, and each needs
NOVOMODELO_MCP_ALLOW_FORCE=1 in the server environment:
| Call | Effect |
|---|---|
deck_edit_json(force=True) | writes a file that violates its JSON Schema |
case_init(force=True) | overwrites existing files |
bridge_convert_*(force=True) | deletes the destination case before converting |
Network
Seção intitulada “Network”The server uses the network only to check for newer releases of Novomodelo,
novomodelo-bridge and the server itself (server_info, at most once every six hours
in a running server, with a timeout of a few seconds) and to install the executable
(install_novomodelo), and only to these destinations:
github.com/ons-ccee-epe/*, api.github.com/repos/ons-ccee-epe/*,
pypi.org/pypi/novomodelo-bridge/*, pypi.org/pypi/novomodelo-mcp/* and, as a
download destination,
release-assets.githubusercontent.com. HTTPS uses the system certificate store,
so the requests pass a corporate proxy that re-signs certificates. Without a
network, the tools still answer, and server_info says the check could not be made
and where to look. The documentation and the schemas are bundled and need no
network.
The release check and the installer read the GitHub API without a token, and GitHub
allows a limited number of such requests per hour from one IP address. On a network
where many people share one address, a call can be refused for a while: the tools
still answer, install_novomodelo reports não foi possível consultar o release oficial with the manual command, and a later call works again.
install_novomodelo installs the official executable of the expected version with
the release installer, after checking its SHA-256. Without confirm=True it only
shows the plan: the URL, the hash, the destination folder and the manual command. On
Windows, the official .ps1 installer does not check the hash of the archive it
downloads.
The official installer also adds the executable’s folder to the PATH: on Linux and
macOS it edits the shell profile (such as .bashrc or .profile), and on Windows the
user’s PATH. The plan reports this in modifies_path. To leave the profile untouched,
set NOVOMODELO_CLI_NO_MODIFY_PATH=1 in the env of the client entry; the server
still finds the executable in ~/.cargo/bin, the installer’s default folder.
Version warnings
Seção intitulada “Version warnings”When the novomodelo executable, novomodelo-python or novomodelo-bridge is
missing, or one of them or the bundled documentation is at a version other than the
server’s, every tool response carries version_warnings: one line per component,
with the commands that align it. The call still runs; the server’s instructions ask the agent to tell
the person and to offer to run the commands, with the person’s consent.
- A component older than the server is upgraded to the server’s version: for
the executable, the agent can call
install_novomodelo, or the person runs the release installer of that version; fornovomodelo-python, the bundled documentation and the package’s own novomodelo-bridge,uv tool install --force --compile-bytecode novomodelo-mcp==X.Y.Z, which brings them along; for a novomodelo-bridge found throughNOVOMODELO_MCP_BRIDGE_BINor onPATH,uv tool install --force novomodelo-bridge==X.Y.Z. - A component newer than the server has two ways out, because without a network
the server cannot tell whether a server of that version exists: install the server
of the component’s version, if it is released
(
uv tool install --force --compile-bytecode novomodelo-mcp==X.Y.Z), or bring the component back to the server’s version. For the executable and novomodelo-bridge, the warning ends with the release notes of the component’s version: its changes, when aserver_infocall in the same running server fetched them in the last six hours, or else a link to the notes.
server_info also reports in new_version whether a newer release of novomodelo,
novomodelo-bridge or the server exists. For novomodelo and novomodelo-bridge it gives
the items of the “Changed”, “Removed” and “Fixed” sections of the release notes,
topic subheadings included, with every item that starts with BREAKING: first,
whatever its section; the list is capped in length. It also gives a link to the
notes and no command of their own: installing one component alone would put it out
of step with the others, so the note says to install the server of that version once
it is released, which brings every component along. For a newer server it gives the
install command, uv tool install --force --compile-bytecode novomodelo-mcp==X.Y.Z,
and the link to the release notes.
Documentation and changelogs
Seção intitulada “Documentation and changelogs”The server bundles the pages of this site at the version that matches its own, with
the input JSON Schemas. The documentation version and commit appear in
server_info under docs. The schemas come from the first source that exists:
NOVOMODELO_MCP_SCHEMAS_DIR, then novomodelo schema export from the installed
executable, then the bundled copy.
The server’s instructions tell the agent to answer questions about the methodology and the use of Novomodelo from these pages, not from the web or from memory, since Novomodelo’s definitions may differ from the literature:
docs_search(query, k)searches the pages by word and returns the page, the section and an excerpt. Searches work best in English; the Portuguese terms of the Glossary are translated.docs_read(page, section)reads one section of a page (or the whole page withoutsection).pagealso takes a page as this site links to it, such as/en/running/configuration/#training(the anchor becomes the section), the page’s address on the site, or the pt-BR page: the server reads the English page and says innotewhich page it read and how to cite it.docs_list(prefix)lists the pages with their titles.- The answer cites the page and section it came from, as
page#section. When the pages do not cover the subject, the agent says so.
Two further pages hold the changelogs: changelog/novomodelo and
changelog/novomodelo-bridge, with one section per version from 0.18.0 onward. The
agent reads what changed in a version with docs_read("changelog/novomodelo", "X.Y.Z").
The server also offers the MCP prompt metodologia(tema), a conversation about the
methodology grounded in these pages. tema is optional, a single word; without it,
the question comes in the next message. A client that supports MCP prompts lists it in
its prompt or command menu; for example:
| Client | Where the prompt appears |
|---|---|
| Claude Code | /novomodelo:metodologia CVaR (or /mcp__novomodelo__metodologia CVaR); arguments are separated by spaces |
| Kiro | # in the chat opens the context menu; the prompt has the MCP icon and a form for tema |
| Claude Desktop | the + menu below the message box, under “novomodelo” |
Environment variables
Seção intitulada “Environment variables”configurar writes NOVOMODELO_MCP_WORKSPACE; the other variables are optional and
go in the env of the client entry.
| Variable | Default | Purpose |
|---|---|---|
NOVOMODELO_MCP_WORKSPACE | unset (unrestricted) | allowed root folders, separated by : (; on Windows) |
NOVOMODELO_MCP_ALLOW_FORCE | 0 | 1 enables the forced writes |
NOVOMODELO_MCP_SOLVER_BIN | novomodelo on PATH, then in ~/.cargo/bin | path of the novomodelo executable |
NOVOMODELO_MCP_BRIDGE_BIN | the package’s, then PATH | another novomodelo-bridge executable; takes precedence over the package’s |
NOVOMODELO_MCP_SCHEMAS_DIR | unset | folder of *.schema.json files, first in the schema sources |
NOVOMODELO_MCP_DOCS_DIR | unset | for documentation development only: a folder of this site’s pages, read instead of the bundled documentation; every response then carries a line in version_warnings |
NOVOMODELO_MCP_TIMEOUT | 900 | timeout, in seconds, of each CLI call |
NOVOMODELO_MCP_MAX_JOBS | 1 | runs that run_start allows at the same time |
NOVOMODELO_MCP_STATE_DIR | per operating system (below) | persistent state: background runs and solve-time calibration |
NOVOMODELO_MCP_MAX_RESPONSE_KB | 50 | size cap of a response with rows or lists |
NOVOMODELO_MCP_MAX_READ_BYTES | 5000000 | largest file loaded whole into memory by the JSON readers, deck_describe_parquet and deck_edit_parquet; a larger one is refused, and the two Parquet tools, which also refuse a folder, point to deck_sql |
NOVOMODELO_MCP_MAX_POLICY_BYTES | 1073741824 (1 GiB) | largest policy on disk that results_policy loads |
NOVOMODELO_MCP_MAX_DIAGNOSTICS | 50 | cap on diagnostic items |
NOVOMODELO_MCP_MAX_SUMMARY_CHARS | 20000 | cap on the length of a summary |
NOVOMODELO_MCP_LOG | 0 | 1 logs each call to standard error |
The default state folder is %LOCALAPPDATA%\novomodelo-mcp on Windows,
~/Library/Application Support/novomodelo-mcp on macOS and
$XDG_STATE_HOME/novomodelo-mcp on Linux (~/.local/state/novomodelo-mcp when
XDG_STATE_HOME is unset), never the system’s temporary folder.
Known limitations
Seção intitulada “Known limitations”- Run planning is an estimate.
run_planestimates time from runs already measured on the same machine; on a machine with no measured run yet, the verdict isindeterminado, and the first run supplies the measurement. The time range is approximate. - Memory is a lower bound. The memory check counts only the space of the cuts, not the LPs, the scenario tree or the buffers, so it rejects a run that clearly does not fit but does not guarantee that a large case fits in RAM.
- Documentation search matches words.
docs_searchfinds pages by the words in the question, not by meaning. Searches work best in English; the Portuguese terms of the Glossary are translated, and a term outside it may find nothing.
See also
Seção intitulada “See also”- Converting a case: Case Conversion (novomodelo-bridge) — the program behind the
bridge_*tools - Running studies: Running Studies — the workflow the run tools drive
- Installing the executable: Installation
- Source code, issues and release notes: ons-ccee-epe/novomodelo-mcp