Best practices

Use these recommended patterns for PyAEDT-MCP to avoid common pitfalls, improve performance, and build more robust workflows.

Session management

Reuse the AEDT connection.

Keep the same AEDT session open across multiple tool calls. Each launch_aedt or connect_to_aedt call incurs a non-trivial startup cost; only reconnect when genuinely necessary.

Check AEDT status before every workflow.

Always call check_aedt_status at the start of a workflow to confirm whether an AEDT connection already exists. Use the result to decide between launch_aedt (no session) and connect_to_aedt (existing session).

Shut down cleanly.

Disconnect properly when done. Abrupt termination can leave AEDT processes running and files in an inconsistent state. The active AEDT session stays tied to the MCP server until you explicitly release it. If you do not release it first, AEDT might not close normally from the UI. Use disconnect_from_aedt for a graceful release or clear_aedt to also close all open projects.

Check for errors.

Check the text returned by every tool for error messages before proceeding. Most tools return a human-readable error string rather than raising an exception, so the next step in a workflow can act on the result.

Scripting with run_python_code

Use the persistent session.

run_python_code and run_python_script share a persistent Python interpreter. Break complex workflows into several short run_python_code calls instead of one large script so you can inspect intermediate state.

Note

By default, PyAEDT-MCP applies settings.release_on_exception = False in the execution session. This keeps the AEDT session alive when generated code fails, which allows the AI agent to iterate and retry fixes instead of losing the whole session.

Choose run_python_code over run_python_script.

Use run_python_code for short inline tasks. Reserve run_python_script for files that already exist on disk (for example, customer-provided scripts or parametric templates).

Use get_guidelines_for before you generate code.

When --include-context is active, call get_guidelines_for with the relevant topic before writing PyAEDT code. The returned guidelines contain correct API patterns, avoiding common mistakes.

Warning

AI-generated code can still close or destabilize a project unexpectedly in some cases. Save your project frequently and keep a backup copy before running larger generated code blocks.

Data handling

Extract only what you need.

Query specific design properties or result values rather than loading entire result sets. AEDT result files can be large; targeted extraction is faster and less likely to hit tool timeouts.

Cache extracted data.

Store extracted data in Python variables within the persistent session so subsequent analysis steps can reuse it without re-querying AEDT.

Note

A recommended workflow is to extract the data you need, then disconnect from AEDT when possible. This reduces risk, frees Desktop resources, and lets you continue post-processing in Python without keeping AEDT open longer than necessary.

Visualization

Capture screenshots after key steps.

Call screenshot after geometry creation, after meshing, and after analysis to give the AI assistant a visual checkpoint. This helps detect geometry errors before solving.

Note

Screenshots need the project to be saved beforehand. If the project is unsaved, the screenshot tool returns an error.

Use run_python_code for custom plots.

For plots beyond what AEDT produces natively, use PyAEDT’s report API or Matplotlib inside run_python_code. The persistent session keeps previously imported libraries available.

Export artifacts for documentation.

Save high-quality screenshots and result plots with meaningful file names so they can be included directly in engineering reports.

Workflow design

Break complex tasks into steps.

A well-structured workflow calls one dedicated tool per logical step (connect → create design → set up geometry → analyze → export). This keeps each tool call focused, makes errors easier to diagnose, and avoids timeout issues.

Validate input before sending to AEDT.

Check parameter values (for example, frequencies, dimensions, materials) in a run_python_code call before passing them to the solver. Early validation avoids long solve runs that fail for trivial reasons.

Design for recovery.

Structure workflows so that individual steps can be re-run without starting over. Use save_project after expensive geometry or mesh steps to create recovery points.

Performance

Minimize AEDT restarts.

Relaunching AEDT adds tens of seconds of overhead. Reuse the existing session across as many operations as possible.

Run independent analyses in parallel.

When running multiple independent designs (for example, a geometry sweep), consider using AEDT’s built-in parametric solver rather than running designs sequentially from the MCP server.

Process results in Python.

Extract result data into Python arrays or DataFrames and analyze it there rather than issuing repeated AEDT queries. The persistent session retains the data between calls.