Optlens

What optlens MCP server does

The optlens MCP server examines an optimization model that has already been built. It can identify conflicting constraints, estimate the smallest changes that restore feasibility, and report the cost of those changes. It also supports feasibility relaxation, what-if edits, why-not questions, sensitivity and marginal values, suspicious data checks, and comparisons between model versions.

Results are returned as text for both agents and people. The server is useful when a model is infeasible or when a solver returned an answer that needs explanation. It does not write or construct models.

Supported model types include LP and MILP, along with quadratic objectives in QP and MIQP models. Convex QP models run on HiGHS; mixed-integer or non-convex quadratic models are sent to SCIP automatically. Sensitivity ranges do not apply to quadratic models, and shadow prices are unavailable for non-convex objectives.

How it works

The server opens a model before other questions are asked. An MCP client can then use the model overview, compute an IIS, request a repair menu, apply changes as new versions, and resolve the modified model. Each solve runs in a worker process with a hard time limit, helping prevent a solver call from blocking indefinitely. Results identify the solver used and indicate when a time limit affected the result.

HiGHS is included with the core package. SCIP and Gurobi are optional solvers. With automatic selection, optlens chooses an available solver and can fall back when a solver cannot perform a particular step. A model explicitly assigned to Gurobi does not silently switch if Gurobi cannot run it. IIS results are checked and rebuilt when necessary to avoid accepting an invalid conflict set.

For source files, the loader can inspect a Python file that builds a Pyomo, gurobipy, or PuLP model. It stops at the first solve call and reads the model without solving it during loading. Models can also be supplied directly as objects or loaded from LP and MPS files.

Setup and configuration

Install Python 3.12 or later with the MCP extra:

pip install "optlens[scip,mcp]"

The scip extra adds SCIP through PySCIPOpt, while gurobi adds Gurobi support and requires a compatible Gurobi installation and license. The pyomo and pulp extras enable loading those model types. Installation provides the optlens-mcp command.

Connect a client by starting optlens-mcp as a stdio server. Claude Code can install the repository plugin, while Codex CLI, Cursor, VS Code Copilot, and Claude Desktop each provide documented MCP configuration entries. Other MCP clients can launch the command directly. If the executable is not on the client's PATH, configure its full path.

Set OPTLENS_SOLVER to highs, scip, gurobi, or auto; auto is the default. Tool calls allow up to 45 seconds for solves by default. OPTLENS_CALL_LIMIT controls the maximum duration of one tool call and must be at least 30 seconds. A tool-level time_limit can request less time than the call limit.

Tools and capabilities

The Python API exposes session methods, and optlens.session.TOOLS contains the corresponding JSON schemas for agents. The documented capabilities include:

• Inspecting model size, status, and constraint families
• Computing irreducible infeasible subsets
• Finding candidate repairs and their costs
• Applying right-hand-side and other what-if changes
• Resolving modified model versions
• Running feasibility relaxations
• Answering why-not questions
• Reporting sensitivity, marginal values, and suspicious data values
• Comparing versions or separate models

Limitations and notes

The optlens MCP server rejects quadratic constraints, indicator constraints, other general constraints, and SOS when loading a model. Large mixed-integer models may not finish within client or server time limits; partial results report the plan, bound, and gap when available. Windows scripts that launch solves need an if __name__ == "__main__" guard because worker processes re-import the script.

Gurobi requires a matching client version and usable license. Large-model testing includes one 279,000-row hotel model, but other large models are not documented as tested. A model loaded from a Python file is read at its first optimize() or solve() call, so model-building code must be structured accordingly.