▸ v0.3 — set up once, launch from anywhere

Client-neutral by design: Codex, Claude Code, Cursor, VS Code/Copilot and any other conforming local stdio MCP client connect to the same unprefixed server tools.

Quickstart

1 — Set up the machine, once.

plaxis-mcp.exe setup

Profiles land in %LOCALAPPDATA%\Caros\PLAXIS-MCP\profiles (override with --profile-dir). Add --skip-credentials to generate profiles now and store passwords later with plaxis-mcp.exe credentials set --profile <profile.toml>.

The directory name is historical — it is where the first supported installer wrote — and is kept because credential_target is derived from it.

2 — Run each role as its own process.

plaxis-mcp.exe serve --role input
plaxis-mcp.exe serve --role output

--config <profile.toml> names a profile explicitly and is equivalent. Either way serve takes every endpoint setting from the profile and the password from Windows Credential Manager, and it fails to start if any PLAXIS_* endpoint environment override is present — so a client cannot silently redirect an endpoint or inject a password.

3 — Point a client at it. See Clients; the host never connects at startup, so call the connect tool once PLAXIS is running.

Getting the host

Both expose the same setup, serve, credentials and profiles commands and enforce the same profile binding and environment-override rejection — so PyPI is not a weaker runtime posture. It simply carries no supply-chain attestation of its own beyond PyPI's, and it is not what an organization requiring signed binaries should deploy.

Do not install plxscripting into the host environment under either.

py -3.13 -m pip install .
$env:PLAXIS_ROLE = "input"
$env:PLAXIS_INPUT_HOST = "127.0.0.1"
$env:PLAXIS_INPUT_PORT = "10000"
$env:PLAXIS_BUNDLE_PYTHON = "C:\Path\To\PLAXIS\python.exe"
py -3.13 -I -u -m plaxis_mcp.server

Tools

Each process has one immutable role. A client registers Input and Output as separate MCP servers when it needs both.

34 Input tools · 11 Output tools.

• connect() takes no endpoint or credential arguments. It uses only the pinned role configuration, so an agent cannot redirect a stored password to an arbitrary host.
• Role status resources live at plaxis://input/status and plaxis://output/status.
• get_results(phase, result_type_path, fem_type="node", offset=0, limit=200) paginates losslessly. limit is 1–5,000; responses report count, offset, limit, returned_count, has_more, next_offset and results.
• Every object in a result carries path — the exact string to pass back to any reference parameter. list_objects(kind) lists a whole kind that way, with a geometry summary (coordinates, or a parsed bounds for objects that report a bounding box).
• model_state() reports mesh status, the phase table and unassigned materials before a calculate is attempted. It separates blocking (a fault in this model) from unknown (a check that could not run here) and caveats (something PLAXIS does not expose at all — on 2D V22, whether the mesh still matches the geometry), so an empty blocking is never mistaken for a clean bill of health.
• Results live on the Output server, which reads whatever the PLAXIS Output application has open. view_results(phase) on the Input server is what puts a calculated phase there.
• When PLAXIS rejects a call, its own message travels beside ours in plaxis_message (sanitised: no filesystem paths, no frames, capped with the truncation flagged out of band). A failing calculate also carries a per-phase table in details.

Clients

All shipped examples are secret-free and use two server entries, one per role. Replace the command with wherever plaxis-mcp.exe lives, or with uvx plaxis-mcp for a PyPI install. Nothing else needs editing — --role finds the shared profiles by itself.

The generic mcp-client-config.json is a minimal mcpServers example for clients using that conventional JSON shape.

Never add a PLAXIS password to version control, command-line arguments, logs, or a profile file.

Security model

• Profiles are bound to one installation. credential_target is derived from installation_root, and worker_python must be an interpreter that discovery links to that same root. Editing any of the three by hand makes the profile fail to load. This is what stops a profile from handing a stored PLAXIS password to an arbitrary executable.
• Environment overrides are rejected, not merged: serve refuses to start when a PLAXIS_* endpoint variable is set.
• Uncertified pairings fail closed. The Python match is exact — a 3.7-series interpreter at any other patch level is a different, uncertified ABI, so it is rejected rather than assumed compatible.
• Ask before mutation. All clients should prompt before call_method and project/file mutators. Do not set an Always Allow-style rule for call_method, open_project or save_project: client approval is generally tool-wide, not argument-scoped.
• Mutation is not undoable. Absolute local and UNC .p2dx paths reachable by PLAXIS are allowed only after user approval. Client approvals and client-side checkpointing cannot restore in-memory PLAXIS state — use disposable projects and backups for all mutation testing.

Architecture

PLAXIS-MCP separates the MCP host from PLAXIS's vendor-managed Python runtime:

  MCP client  ──stdio──▶  host (CPython 3.13, mcp 1.26.0)
                              │
                              ├─ private local pipe
                              ▼
                          role-pinned worker (PLAXIS bundled Python)
                              │
                              ▼
                          PLAXIS Remote Scripting @ 127.0.0.1

• Client traffic is always MCP over stdio; normal logs and diagnostics go to stderr.
• PLAXIS-MCP never installs packages into, upgrades, or redistributes the PLAXIS Python bundle.

The split is required because the MCP host needs a current Python runtime while PLAXIS ships version-specific scripting environments.

V20 and V21 share the legacy profile: their end-of-life Python is isolated inside the loopback worker and requires organizational security acceptance.

Requirements

• Windows, with a supported local PLAXIS 2D installation and Remote Scripting enabled.
• CPython 3.13 for the MCP host. Supported host range: >=3.13,<3.14.
• One PLAXIS Input and/or Output server listening only on loopback — defaults Input 127.0.0.1:10000, Output 127.0.0.1:10001.
• A selected, certified PLAXIS bundled-Python profile. Do not install plxscripting into the MCP host environment.

C:\ProgramData\Seequent\PLAXIS Python Distribution V2\python\Lib\site-packages
C:\ProgramData\Bentley\Geotechnical\PLAXIS Python Distribution V2\python\Lib\site-packages

Docker, WSL, remote MCP transports, and PLAXIS bundles copied into a Python environment are not supported deployment paths for v0.3. The former Docker artifacts were removed intentionally.

Development & verification

# unit suite, from the CPython 3.13 host environment
py -3.13 -m unittest discover -s tests

# inspect the split host/worker configuration without starting PLAXIS
py -3.13 scripts/smoke_test.py

Before a release: verify the host wheel/installer in a clean environment, confirm pip check, scan the artifact for vendor files, validate the MCP contract at protocol 2025-03-26, and complete live certification with a disposable calculated project for every enabled PLAXIS profile.

References

MCP Python SDK · Codex · Claude Code · Cursor · VS Code