FlexAgent MCP

FlexAgent MCP#

AI-powered simulation assistance for Tidy3D through Model Context Protocol

FlexAgent MCP is a Model Context Protocol (MCP) server that brings physics-aware AI assistance to Tidy3D workflows. Unlike generic coding assistants, FlexAgent understands electromagnetic simulation concepts, Tidy3D’s API, and can interact with the 3D Viewer to provide comprehensive, context-aware support for your simulation projects.

📹 Watch the demo: FlexAgent MCP Introduction Video

Overview#

FlexAgent enables natural language interaction with Tidy3D simulations across multiple platforms, including Cursor, VS Code, and other MCP-compatible environments. Through structured workflows that leverage Tidy3D’s trusted documentation, FlexAgent transforms your AI assistant into a knowledgeable simulation partner capable of:

  • Learning – Understanding Tidy3D concepts and workflows: “Explain how Tidy3D FDTD updates the fields in this notebook”

  • Troubleshooting – Diagnosing and resolving simulation issues: “I want to fix the structure-related validation error”

  • Customization – Modifying existing simulations: “Replace the FluxMonitor with a ModeMonitor”

  • Build from Scratch – Creating new simulation setups: “Create a y-junction waveguide simulation setup”

  • Result Analysis – Interpreting and visualizing simulation data: “Plot all the electric field components”

For a comprehensive introduction to the Tidy3D + AI ecosystem, see the Tidy3D + AI overview.

Installation#

FlexAgent MCP is available through the Flexcompute plugin marketplace, the Tidy3D IDE extensions, or direct MCP server launch.

Agent Plugins#

For AI coding agents, install the Tidy3D plugin from the Flexcompute plugin marketplace. The plugin provides Tidy3D guidance and MCP registration; for now, configure MCP clients to launch the Python package runtime through uvx tidy3d mcp.

Claude Code:

In Claude Code:

/plugin marketplace add flexcompute/plugin-marketplace
/plugin install tidy3d@flexcompute

If Claude Code is already running, reload plugins after installation:

/reload-plugins

Codex:

Add the Flexcompute marketplace:

codex plugin marketplace add flexcompute/plugin-marketplace

Then open Codex, run /plugins, choose the Flexcompute marketplace, and install Tidy3D.

Configure Tidy3D through uvx:

uvx tidy3d configure

You can also set SIMCLOUD_APIKEY instead of running the configure command.

Tidy3D Extensions#

FlexAgent MCP is integrated within the Tidy3D extensions for Cursor and Visual Studio Code. When you install and configure these extensions, FlexAgent is automatically set up and ready to use.

For detailed installation and setup instructions, see:

The extensions handle all FlexAgent configuration automatically, including API key management, MCP server deployment, and integration with the 3D Viewer.

Standalone MCP Client#

For advanced manual setup with other MCP-compatible clients, use uvx to run Tidy3D without binding the MCP server to the client’s project environment.

Prerequisites:

  • uvx available on PATH

  • A Tidy3D API key (get one free here)

  • Tidy3D configured with that key via uvx tidy3d configure, or SIMCLOUD_APIKEY set

Launch the server manually with:

uvx tidy3d mcp

For raw MCP client config, run the same command:

{
  "mcpServers": {
    "tidy3d": {
      "command": "uvx",
      "args": ["tidy3d", "mcp"]
    }
  }
}

AI Collaboration Best Practices#

To get the most out of FlexAgent, follow these proven strategies for effective AI-assisted simulation development:

Leverage FlexAgent Rules#

For optimal results, explicitly reference the integrated FlexAgent rules in your prompts. When using the Tidy3D extensions, these rules are automatically loaded:

  • Cursor: Rules are in .cursor/rules/ (automatically loaded)

  • VS Code: Rules are in .github/instructions/ (enable in Copilot settings)

Example: “Follow the FlexAgent rules in flexagent.mdc for all responses. These rules take priority over other instructions.”

Start Simple, Build Incrementally#

Begin with basic simulations and gradually add complexity. This approach makes debugging easier and helps you understand each component before moving to the next level. Ask FlexAgent to explain concepts as you build.

Provide Rich Context#

The more specific your prompts, the better FlexAgent’s assistance. Instead of generic requests like “help with mode analysis,” provide detailed context:

Better prompt: “I’m studying photonic integrated circuits. How can I use Tidy3D to analyze the fundamental TE mode of a 220 nm thick silicon strip waveguide?”

Use the Viewer for Real-Time Iteration#

Keep the 3D Viewer open while editing your simulation code. Changes to geometry, materials, sources, or monitors update automatically, letting you immediately visualize the impact of parameter tweaks without re-running the code. This creates a powerful feedback loop for rapid iteration.

Be Specific When Troubleshooting#

Instead of vague requests like “fix all errors,” provide targeted information:

  • “Fix the boundary condition warning for structure[0]”

  • “Resolve the mesh refinement issue near the waveguide core”

  • “Clear the validation error related to ModeSolver plane”

Understand Before Proceeding#

Take time to comprehend the generated code and simulation setup. Ask FlexAgent to explain concepts you’re unfamiliar with before building upon them. This ensures you maintain control and understanding of your simulation.

Use Incremental Validation#

After each major change, ask FlexAgent to “validate and explain the simulation changes” before proceeding. This helps ensure physical accuracy and catches issues early.

Document Your Simulation Intent#

Add comments explaining the physics you’re trying to model. This helps both you and FlexAgent understand the simulation goals:

# Modeling evanescent coupling between two strip waveguides separated by 200 nm

Specify Your Python Environment#

When working with multiple Python environments, explicitly tell FlexAgent which one to use:

“Run this code using my tidy3d_latest conda environment located at /home/user/miniconda3/envs/tidy3d_latest.”

Prompt Examples#

The following examples demonstrate effective ways to interact with FlexAgent across different use cases. These prompts leverage FlexAgent’s understanding of Tidy3D workflows and its ability to access documentation and control the 3D Viewer.

Learning#

Use FlexAgent to understand Tidy3D concepts, methods, and best practices:

  • “How to set up a GaussianBeam source”

  • “Explain how the FDTD method works”

  • “How can I perform a mode analysis?”

  • “What’s the difference between a FluxMonitor and a ModeMonitor?”

  • “Explain the relationship between mesh refinement and simulation accuracy”

Troubleshooting#

Get help diagnosing and fixing simulation issues:

  • “Fix the warning related to ‘structures[0]’ extending exactly to simulation edges”

  • “Fix the code to avoid the warning related to Bloch vector”

  • “Clear the validation error related to ModeSolver plane”

  • “Why is my simulation diverging, and how do I fix it?”

  • “Help me resolve the boundary condition warning for my periodic structure”

Customization#

Modify existing simulations to explore different configurations:

  • “Add a mode source at the position (-4, 0, 0) to inject the fundamental TE waveguide mode at 1.55 micrometers”

  • “Build a mode simulation setup to analyze the dispersion parameters of the first 2 optical modes at the source plane of my FDTD simulation setup”

  • “Perform a parameter sweep to vary the unit cell period between 0.3 to 0.5 micrometers”

  • “Replace the FluxMonitor with a ModeMonitor and update the analysis code”

  • “Change the simulation boundary conditions from PML to periodic in the x-direction”

Build From Scratch#

Create complete simulation setups from natural language descriptions:

  • “Create a simple FDTD simulation setup to simulate a silicon strip waveguide with dimensions (0.5, 0.22, 10) and refractive index of 3.47”

  • “I am interested in PIC devices. Build a setup to obtain the modal power at the outputs of a y-junction waveguide. Add s-bends to the output waveguides”

  • “I want to build a simulation setup to investigate structural color generation”

  • “Create a ring resonator simulation with a 5 Îźm radius and 220 nm waveguide thickness”

  • “Build a metasurface simulation for beam steering at 1.55 Îźm wavelength”

Analysis#

Interpret results and create visualizations:

  • “Plot the field intensity profile obtained from the FieldMonitor at the central frequency”

  • “Considering my parameter sweep simulation, plot the |E|^2 field profile for all the modes in the largest waveguide”

  • “Plot the reflectance spectrum of all unit cell period values in the parameter sweep simulation in a single chart”

  • “Analyze the transmission spectrum and identify the resonance frequencies”

  • “Create a 2D plot showing the electric field distribution in the x-y plane at z=0”