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.10 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
viewer_annotation         set_structure_visibility  viewer_cross_section
viewer_set_view           viewer_zoom               viewer_pan
viewer_visibility         viewer_layer              viewer_display
viewer_measure            viewer_results_open       viewer_results_list
viewer_results_select     viewer_results_view       viewer_results_coordinate
render_report             open_report               get_report
set_report_step

viewer_annotation requires the complete viewer identity, control, file receipt, and annotation capability set. Result opening requires viewer.results.open; list, select, view, and coordinate require viewer.results.state. The current version-1 extension advertises those result capabilities only on macOS and Linux. It withholds them on Windows because sandbox validation cannot satisfy the viewer's fixed 60-second data-plane deadline. Result animation remains absent.

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.