From 63e37bcf8fdb1c496227918e7d64d7bc105861b9 Mon Sep 17 00:00:00 2001
From: Yannick Augenstein <yannick@flexcompute.com>
Date: Fri, 14 Nov 2025 09:55:06 +0100
Subject: [PATCH] docs: add flexagent mcp installation instructions

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 64 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 80eaa30a1c..f25373e231 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Name](https://img.shields.io/badge/pypi-tidy3d-blue?style=for-the-badge)](https:
 [![PyPI version shields.io](https://img.shields.io/pypi/v/tidy3d.svg?style=for-the-badge)](https://pypi.python.org/pypi/tidy3d/)
 [![Documentation Status](https://readthedocs.com/projects/flexcompute-tidy3ddocumentation/badge/?version=latest&style=for-the-badge)](https://flexcompute-tidy3ddocumentation.readthedocs-hosted.com/?badge=latest)
 [![Tests](https://img.shields.io/github/actions/workflow/status/flexcompute/tidy3d/tidy3d-python-client-tests.yml?branch=develop&style=for-the-badge)](https://github.com/flexcompute/tidy3d/actions/workflows/tidy3d-python-client-tests.yml)
-![License](https://img.shields.io/github/license/flexcompute/tidy3d?style=for-the-badge)
+[![License: LGPL-2.1](https://img.shields.io/badge/license-LGPL--2.1-blue?style=for-the-badge)](LICENSE)
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-5A4FCF?style=for-the-badge)](https://github.com/astral-sh/ruff)
 ![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/daquinteroflex/4702549574741e87deaadba436218ebd/raw/tidy3d_extension.json)
 
@@ -20,7 +20,6 @@ This repository contains the python API to allow you to:
 * Submit and manage simulations running on Flexcompute's servers.
 * Download and postprocess the results from the simulations.
 
-
 ![](https://raw.githubusercontent.com/flexcompute/tidy3d/main/img/snippet.png)
 
 ## Installation
@@ -74,6 +73,69 @@ To get started, our documentation has a lot of [examples](https://docs.flexcompu
 | FAQ                | https://docs.flexcompute.com/projects/tidy3d/en/latest/faq/docs/index.html       |
 
 
+## FlexAgent MCP
+
+FlexAgent adds an AI-assisted layer on top of Tidy3D via the Model Context Protocol (MCP); read more about [AI-assisted simulation in Tidy3D](https://hs.flexcompute.com/news/ai-assisted-simulation-in-tidy3d-ushering-in-a-new-era-of-photonic-design). Install the `tidy3d-mcp` server when you want that experience inside an MCP client without the Tidy3D extension for [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Cursor](https://open-vsx.org/extension/Flexcompute/tidy3d).
+
+These commands assume [uv](https://docs.astral.sh/uv/getting-started/installation/) is installed on your machine.
+
+**Register the server with your MCP client** - use the block below that matches your CLI.
+
+<details>
+<summary>Codex CLI / IDE</summary>
+
+```bash
+codex mcp add tidy3d -- uvx tidy3d-mcp --api-key "YOUR_TIDY3D_API_KEY"
+```
+
+</details>
+
+<details>
+<summary>Claude CLI / Desktop / Code</summary>
+
+```bash
+claude mcp add tidy3d -- uvx tidy3d-mcp --api-key "YOUR_TIDY3D_API_KEY"
+```
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Create or edit `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "tidy3d": {
+      "command": "uvx",
+      "args": ["tidy3d-mcp", "--api-key", "YOUR_TIDY3D_API_KEY"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Cursor CLI / IDE</summary>
+
+Cursor reuses the same schema across the editor and `cursor-agent`. Configure `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global) and then run `cursor-agent mcp list` to verify:
+
+```json
+{
+  "mcpServers": {
+    "tidy3d": {
+      "command": "uvx",
+      "args": ["tidy3d-mcp", "--api-key", "YOUR_TIDY3D_API_KEY"]
+    }
+  }
+}
+```
+
+</details>
+
+
 ## Related Source Repositories
 
 | Name              | Repository                                      |