Skip to content

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.


ComponentRequirement
Python3.12 or newer
uvinstalls 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-pythoninstalled 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.

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.


Terminal window
uv tool install --compile-bytecode novomodelo-mcp # isolated, on-PATH CLI (recommended)
pipx install novomodelo-mcp # alternative
pip install novomodelo-mcp # into the current environment

The 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).

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".

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.

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:

Terminal window
novomodelo-mcp configurar --cliente claude-code --workspace ~/studies --mostrar # print the change only
novomodelo-mcp configurar --cliente claude-code --workspace ~/studies # write it
OptionEffect
--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.
--irrestritoWrite the entry with no workspace: the server reads and writes any folder. Cannot be combined with --workspace.
--mostrarPrint only the part of each file that would change, and touch nothing.
--instrucoesAlso 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.

ClientConfiguration fileRead-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 DesktopmacOS ~/Library/Application Support/Claude/claude_desktop_config.json; Windows %APPDATA%\Claude\claude_desktop_config.json; Linux ~/.config/Claude/claude_desktop_config.jsonno list: choose “always allow” on a tool’s first callprints 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.

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.

KindTools
Read onlyserver_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 filescase_init, schema_export, bridge_convert_*, bridge_compare_*, bridge_dashboard, include_folders
Changes or stopsdeck_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_* and bridge_convert_* check and convert a case from another planning tool with novomodelo-bridge (one tool per source format; see Case Conversion). case_validate validates a case through the novomodelo-python bindings; with output_dir, it also checks the output of an earlier run for a resume. case_summary lists the case as Novomodelo loads it: counts per entity type and the {id, name} of each entity.
  • Cases and decks. deck_list maps a case: its input files with their schema type, and one line per run folder. deck_read_json, deck_read_parquet and deck_describe_parquet read input files. deck_edit_json and deck_edit_parquet edit them with a backup and an atomic write; with ensure_valid=True, deck_edit_json revalidates the case and reverts the edit if validation fails. deck_sql runs read-only DuckDB SQL (SELECT, WITH, DESCRIBE, SUMMARIZE) over the Parquet, CSV and JSON files of a case or of its results.
  • Running. case_init creates a case from a bundled template (novomodelo init). run_plan writes 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_cabe or indeterminado) with suggested settings. run_apply applies those settings to config.json. run_start starts novomodelo run in the background and returns a job id at once; it refuses a case whose plan is nao_cabe, unless called with override=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 in suggested_output, and overwrite=True replaces the earlier run. run_status, run_logs and run_cancel follow and stop the job. A job survives a restart of the server.
  • Results. results_status reads the run status, bounds, gap, iterations and cost; results_convergence the convergence record; results_list_entities and results_query the simulation output; results_stochastic the inflow-model coefficients and the opening tree (it needs exports.stochastic: true in the run’s config.json); results_policy a summary of the trained policy. bridge_compare_* compares a converted case’s results with the source tool’s published results, and bridge_dashboard writes an HTML dashboard of a case.
  • Reference. schema_list and schema_get return the JSON Schemas of the input files (also available as the resource novomodelo://schema/{type}); schema_export writes them to a folder. docs_list, docs_search and docs_read read the bundled documentation (see Documentation and changelogs).
  • Diagnostics. server_info and solver_version describe the installation; install_novomodelo installs the novomodelo executable; include_folders adds folders to the workspace.

Responses that carry rows or lists are capped in size; a capped response says so in size_truncation.


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.

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.

Three forms of call override a safety check, and each needs NOVOMODELO_MCP_ALLOW_FORCE=1 in the server environment:

CallEffect
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

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.


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; for novomodelo-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 through NOVOMODELO_MCP_BRIDGE_BIN or on PATH, 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 a server_info call 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.


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:

  1. 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.
  2. docs_read(page, section) reads one section of a page (or the whole page without section). page also 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 in note which page it read and how to cite it. docs_list(prefix) lists the pages with their titles.
  3. 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:

ClientWhere 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 Desktopthe + menu below the message box, under “novomodelo”

configurar writes NOVOMODELO_MCP_WORKSPACE; the other variables are optional and go in the env of the client entry.

VariableDefaultPurpose
NOVOMODELO_MCP_WORKSPACEunset (unrestricted)allowed root folders, separated by : (; on Windows)
NOVOMODELO_MCP_ALLOW_FORCE01 enables the forced writes
NOVOMODELO_MCP_SOLVER_BINnovomodelo on PATH, then in ~/.cargo/binpath of the novomodelo executable
NOVOMODELO_MCP_BRIDGE_BINthe package’s, then PATHanother novomodelo-bridge executable; takes precedence over the package’s
NOVOMODELO_MCP_SCHEMAS_DIRunsetfolder of *.schema.json files, first in the schema sources
NOVOMODELO_MCP_DOCS_DIRunsetfor 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_TIMEOUT900timeout, in seconds, of each CLI call
NOVOMODELO_MCP_MAX_JOBS1runs that run_start allows at the same time
NOVOMODELO_MCP_STATE_DIRper operating system (below)persistent state: background runs and solve-time calibration
NOVOMODELO_MCP_MAX_RESPONSE_KB50size cap of a response with rows or lists
NOVOMODELO_MCP_MAX_READ_BYTES5000000largest 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_BYTES1073741824 (1 GiB)largest policy on disk that results_policy loads
NOVOMODELO_MCP_MAX_DIAGNOSTICS50cap on diagnostic items
NOVOMODELO_MCP_MAX_SUMMARY_CHARS20000cap on the length of a summary
NOVOMODELO_MCP_LOG01 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.


  • Run planning is an estimate. run_plan estimates time from runs already measured on the same machine; on a machine with no measured run yet, the verdict is indeterminado, 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_search finds 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.