Tidy3D MCP

tidy3d-mcp is the independently installable and released implementation of the Tidy3D MCP runtime. It exposes the remote FlexAgent tools and, when an authenticated compatible editor bridge is already active, Tidy3D local/editor tools over stdio.

The distribution and command are both named tidy3d-mcp. A separate tidy3d mcp command in the Tidy3D client may delegate to this package, but this package does not depend on that facade.

Run

uvx --from tidy3d-mcp==0.16.9 tidy3d-mcp

The server resolves the FlexAgent API key in this order:

1. --api-key
2. SIMCLOUD_APIKEY
3. TIDY3D_BASE_DIR config locations
4. ~/.config/tidy3d/config.toml under [web].apikey
5. ~/.tidy3d/config

TIDY3D_MCP_REMOTE_URL can replace the default https://flexagent.simulation.cloud/ endpoint. The URL is forwarded exactly, including a custom path. The generic REMOTE_MCP_URL variable is intentionally ignored so ambient configuration cannot redirect the Tidy3D API credential.

The established marketplace compatibility modes remain supported:

• Flex RF launches the default command and supplies package="flex-rf" to the remote documentation tools.
• PhotonForge launches tidy3d-mcp --product photonforge, which retains its branded remote documentation and feedback tools and never advertises Tidy3D editor tools.

Local editor tools

The server never installs, registers, recommends, bootstraps, or launches an editor extension. It starts normally when no bridge is present and exposes only the remote FlexAgent surface.

An editor publishes a private per-window discovery record with schemaVersion: 1, protocolVersion: 1, a loopback URL, a session token, workspace roots, and capabilities. The server authenticates POST /viewer/ping and advertises only tools whose complete capability requirements are present. Unknown capabilities are ignored. An unsupported protocol, malformed manifest, failed authentication, or unavailable bridge exposes no local tools.

The extension removes its registration during normal shutdown. If authenticated discovery instead proves that an unchanged private registration points to a refused or incompatible endpoint, the MCP consumer removes that exact stale record. It preserves timed-out, replaced, malformed, untrusted, and symlinked records.

The #19281 base bridge advertises viewer.open and viewer.control; the #19517 adapter adds python.detect, viewer.simulations, viewer.validate, and the receipt-backed viewer.file.open identity route. The package withholds open_simulation, rotate_viewer, capture_viewer, and set_structure_visibility unless the complete identity and operation requirements are present, rather than guessing an opaque viewer ID.

The extension bridge advertises viewer.generic.control only when its authenticated /viewer/control route can deliver the public version-1 @flexcompute/viewer-common VIEWER_CONTROL contract to an active validated setup viewer. A successful response confirms best-effort delivery through the extension and webview to the intended iframe; version 1 does not acknowledge that the viewer applied the operation. The eight viewer_* setup controls below also require the viewer.open capability plus the receipt-backed viewer.file.open identity route; without the complete set, all eight remain absent from tools/list.

The capability-backed local surface is:

detect_python             list_simulations          validate_simulation
open_simulation           rotate_viewer             capture_viewer
set_structure_visibility  viewer_cross_section      viewer_set_view
viewer_zoom               viewer_pan                viewer_visibility
viewer_layer              viewer_display            viewer_measure
render_report             open_report               get_report
set_report_step

Results inspection and annotation tools remain absent until their extension routes provide complete bounded contracts.

Source operations accept saved local .py or .ipynb paths only. They do not forward inline or base64 source. Validation may return session-scoped artifact receipts; open_simulation opens HDF5 only through an artifact ID or the exact registered artifact path/URI. Report operations accept a saved workspace .qmd and preserve the renderer command, working directory, environment, and bounded stdout/stderr in their structured result.

Explicit bridge override

Discovery is the normal path. Tests and controlled integrations may select one bridge explicitly, but URL and token must be supplied together:

tidy3d-mcp \
  --viewer-bridge http://127.0.0.1:5123 \
  --viewer-bridge-token "$TIDY3D_VIEWER_BRIDGE_TOKEN"

TIDY3D_VIEWER_BRIDGE_URL and TIDY3D_VIEWER_BRIDGE_TOKEN provide the same authenticated override. The legacy unauthenticated URL variable is ignored unless a token is also present.

Develop and release

uv sync --locked
uv run ruff format --check src tests
uv run ruff check src tests
uv run pyrefly check
uv run pytest
uv build
uv run tidy3d-mcp --version

The machine-readable local tools/list acceptance matrix lives at tests/fixtures/tools_list_matrix.json. Publishing is owned by .github/workflows/frontend_tidy3d-mcp.yaml, whose trusted publisher targets this directory.