Part III · Chapter 17

MCP Integration

An AI coding agent such as Claude Code or Codex can operate 3DOptix for you through the Model Context Protocol (MCP). Once connected, you describe what you want in plain language, and the agent builds the setup, places parts, runs the simulation and reads the results.

The MCP integration and the Python API (see API Interface) drive the same engine. Use MCP for a conversation with an agent; use the API from your own code.

What you need

Requirement	Detail
A 3DOptix account	Sign up at 3doptix.com. A new account starts with a full trial.
An MCP client	Claude Code and Codex are supported. Any client that speaks MCP over HTTP can connect, see manual configuration below.
No API key	Sign-in uses OAuth 2.0; there is nothing to paste into a configuration file.

Installing the plugin

The 3doptix plugin bundles the MCP server with a skill that teaches the agent how to work with optics: units, default materials, and when to ask you before acting.

Claude Code

claude plugin marketplace add 3doptix/skills
claude plugin install 3doptix@3doptix

Codex

codex plugin marketplace add 3doptix/skills
codex plugin add 3doptix@3doptix

To add only the server, without the skill:

claude mcp add --transport http 3doptix https://mcp.3doptix.com

The server is also listed in the MCP Registry as com.3doptix/optical-design.

Manual configuration for other clients

Any MCP client can connect to the server directly. There is nothing to download or run locally.

Setting	Value
Server URL	`https://mcp.3doptix.com`
Transport	HTTP
Authentication	OAuth 2.0; the client opens a browser window for sign-in
Name	`3doptix`

Most clients keep their servers in a settings file with an mcpServers block:

{
  "mcpServers": {
    "3doptix": {
      "type": "http",
      "url": "https://mcp.3doptix.com"
    }
  }
}

Some clients name the transport field transport instead of type; check your client's documentation. Restart the client after saving, then sign in when it asks.

If your client cannot sign in by itself, connect anyway and ask the agent to sign you in. The server provides 3doptix_client_login_url, which returns a sign-in link, and 3doptix_client_exchange_oauth_for_api_key, which completes the sign-in; 3doptix_client_status then shows which account is connected.

Signing in

Claude Code: run /mcp, select 3doptix and sign in in the browser window that opens.
Codex: run codex mcp login 3doptix.

The client stores and refreshes the token; you do not need to sign in again.

Checking the connection

Ask the agent to:

Run a health check (3doptix_api_healthcheck).
Show which account is connected (3doptix_client_status).
List your setups (3doptix_setup_list).

If the list is empty although your account has setups, the wrong account is connected. Sign out and sign in again.

Problem	What to do
"Needs authentication" after signing in	The client did not store the token. Sign in again and watch for an error in the browser.
The browser does not open	Copy the link the client printed and open it yourself.
Sign-in works but tools fail	The account may have no active subscription or an expired trial. Check at simulation.3doptix.com.
Codex reports a client-registration error	Codex needs dynamic client registration. If your organization's identity provider requires a registered client, contact support@3doptix.com.

What the agent can do

Setups and parts: create, list and open setups; place, move, inspect and remove parts.
Catalog: search optics, optomechanics and CAD parts by brand, subtype and dimensions; look up materials and refractive indices.
Custom parts: create lenses, mirrors, gratings, apertures and multiplets from a specification, such as a target focal length.
Light sources: configure plane wave, Gaussian, point, LED and ray-file sources.
Simulation and analysis: run ray traces; run spot, aberration, MTF, PSF, wavefront and spectral analyses; fetch per-ray hit data.
Import: Zemax files (.ZMX fully, .ZMF best effort, .ZOS not supported), STEP files and .opt setups.
Templates: start from a starter template.
Optimization: refine a layout one variable at a time, with your approval at each step. There is no automatic optimizer.

Example prompts

Build a 2-lens beam expander for a 5 mm 632 nm beam, 3x magnification,
then run a spot diagram on the output.

Import my Zemax file into 3DOptix and tell me where the aberrations are worst.

The agent proposes a layout, creates the setup, places the parts, sources and detectors, asks before running the simulation, and presents the results.

What to expect from the agent

It asks before running a simulation or analysis.
It does not skip a failed step or resolve a contradiction in your specification on its own; it asks.
It tells you when it substitutes a part or makes an assumption that affects the result.
It pauses for your confirmation between major steps.

Limitations

Limitation	What it means
No automatic optimizer	Optimization is a guided, step-by-step process.
Paraxial estimates	For fast or wide-angle systems, the agent's estimates can drift; it should take smaller steps.
`.ZOS` files	Not supported; use `.ZMX`.
Few rays	Statistics such as RMS spot size are flagged as unreliable below about 1,000 traced rays.

Support

Need	Contact
Product, accounts, subscriptions	support@3doptix.com
A bug in the integration or the skill	Open an issue in the 3doptix/skills repository
Privacy	3DOptix privacy policy

The integration is released under the MIT license.