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.

Prerequisites

• Python >=3.10
• The nextmv package installed
• The MCP server extra installed (see below)
• A Nextmv Cloud account with an API key (for cloud tools)

Install the MCP server

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

pip install "nextmv[mcp]==1.3.1.dev4"

MCP server help

The MCP server is a subcommand of the Nextmv CLI. Normally, an agent runs and manages the server for you. Subcommand-specific help is available through the CLI.

nextmv mcp -h

Integration with AI assistants

To use the MCP server with the hosted Nextmv Platform, you must configure the nextmv CLI.

nextmv configuration create --api-key "your-nextmv-api-key"

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.

• Codex
• Cursor
• VS Code

Examples

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

Run and analyze:

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

Manage apps:

• "Create a new app called demand-forecasting"
• "Push the code in ./my-app to the forecasting app"
• "List all versions of my-routing-app"

Experiments:

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

Local development:

• "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 nextmv is installed inside a virtual environment. In this case, the MCP server works fine in the terminal but ails 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.

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