Skip to content

MCP server

The Nextmv MCP server is an MCP (Model Context Protocol) server that exposes Nextmv Cloud and local functionality as tools for AI coding assistants. It helps enforce Nextmv best practices when building and managing decision models with AI agents, and comes with a workflow guide for using Nextmv effectively. Use it to manage applications, submit runs, analyze results, and run experiments using natural language in your editor, terminal, or custom agent. The MCP server works across all configured Nextmv profiles, letting you switch between environments during a session.

These are the prerequisites for the MCP server:

Install the MCP server

The MCP server is an opt-in dependency, not included with the default CLI installation. Install it with the mcp extra:

uv tool install "nextmv[mcp]"

pip install "nextmv[mcp]"

pipx install "nextmv[mcp]"

Info

On macOS (zsh), the quotes around "nextmv[mcp]" are required. Without them, the shell interprets the brackets as a glob pattern.

To check if the installation was successful, run the following command to show the help menu:

nextmv mcp --help

Integration with AI assistants

Claude Code

Register the server as an MCP provider with Claude Code. By default, claude mcp add scopes the server to the current project directory.

claude mcp add nextmv -- nextmv mcp serve

To make the server available across all projects on your machine (~/.claude/settings.json), register it to your user:

claude mcp add -s user nextmv -- nextmv mcp serve

Start a new Claude Code session after registering the server and it will be available to the coding agent.

Other coding agents

To use the Nextmv MCP server with other coding agents and editors, refer to their documentation on MCP integration.

Examples

Here are some things you can ask your AI assistant to do once the MCP server is connected:

  • "Run my-routing-app with the input in data/input.json and summarize the solution"
  • "What were the logs from the last run?"
  • "Show me the input that was used for run abc-123"
  • "Create a new app called demand-forecasting"
  • "Push the code in ./my-app to the forecasting app"
  • "List all versions of my-routing-app"
  • "Create a batch experiment comparing solve durations of 5s and 30s"
  • "Run an acceptance test comparing the production and candidate instances"
  • "Set up a shadow test mirroring production traffic to the new instance"
  • "Run the app in ./my-app locally with the sample input"
  • "Sync my local runs to the cloud app"
  • "Clone the python-ortools-routing community app"

Troubleshooting

"Executable not found in $PATH" in VSCode extensions

When using Claude Code as a VSCode extension or Cursor, the extension may not inherit your shell's PATH. This may happen if the CLI is installed inside a virtual environment. In this case, the MCP server works fine in the terminal but fails in the extension with an error like:

MCP server "nextmv" Connection failed: Executable not found in $PATH: "nextmv"

To diagnose: check the extension's output panel. In VSCode, open View / Output and select Claude VSCode (or Cursor) from the dropdown to see MCP connection errors.

To fix: use the full path to the nextmv binary. Find it with:

which nextmv

Then update your MCP configuration to use the absolute path. For example, for a mamba environment:

{
  "mcpServers": {
    "nextmv": {
      "type": "stdio",
      "command": "/Users/you/.local/share/mamba/envs/nextmv-env/bin/nextmv",
      "args": ["mcp", "serve"]
    }
  }
}

Alternatively, install the CLI globally (outside any virtual environment) so it's available on your system PATH.

MCP server not available after registration

MCP servers are loaded when a session starts. If you register a server in an active session, you need to start a new session for it to take effect.

Project-scoped server not found

In Claude Code, claude mcp add registers the server for the current project directory. If you switch to a different directory, the server won't be available. Either register it globally with claude mcp add -s user, or register it again from the new directory.