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.12 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 marketplace product modes are explicit so their runtime surfaces stay separate:

• Flex RF launches tidy3d-mcp --product flex-rf. It exposes the branded remote surface without Tidy3D editor tools; callers still supply package="flex-rf" to its 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 reach an active validated setup viewer. Version 2 negotiates the public @flexcompute/viewer-common setup-viewer protocol and returns viewer_applied only after a correlated application acknowledgement. Viewers that cannot complete this handshake are unavailable; the MCP never treats fire-and-forget delivery as application. 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
viewer_results_members    viewer_results_select_member
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. When the active viewer is bound to a native Batch or BatchData file, viewer_results_members lists its session-admitted result names and opaque member receipts; viewer_results_select_member switches within that exact collection without accepting paths, indexes, or result payloads. 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. Provider-backed colormap and animation tools appear only when the exact live result viewer advertises them.

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.