MCP Integration
Drive Simten from any MCP-compatible AI assistant. Build, simulate, and verify circuits from your terminal
@simten/mcp lets an AI assistant build circuits: Claude Code, Codex CLI, Gemini CLI, Cursor, or any other MCP client. When you ask it for a circuit, it:
- Writes the circuit to a TypeScript file in your repo
- Draws it in a browser tab
- Simulates it, or runs a testbench, to check it works
The browser tab only displays what the assistant sends. Nothing you do there goes back to the assistant (see Security).
Setup
1. Install a client
Any MCP client works. This page uses Claude Code in its examples.
2. Add the MCP server
Pick your client:
$ claude mcp add --scope user simten npx @simten/mcp3. Ask for a circuit
The first time the assistant draws one, the server opens a viewer in your browser, served from localhost. You don't need to visit simten.dev.
Available tools
The assistant gets these tools:
| Tool | What it does |
|---|---|
get_started | Orientation and the bundled examples (Snake, a RISC-V computer, an ALU, ...). With example, writes one to circuits/<id>.circuit.ts. No setup needed. |
get_grammar | Return the circuit() builder API (inputs/outputs, nodes, connect) with worked examples. |
list_components | Return the full catalog of stdlib components, each with its ports and constructor options (e.g. Register({ width })). |
get_verify_api | Return how to write a .verify.ts testbench: simulate(top, { memory }), set for ports and switches, verify.exhaustive/verify.check, declareOracle, and worked examples. |
check_circuit | Compile a circuit and report whether it builds, with the location of a compile error. |
simulate_circuit | Compile and simulate; return signal traces and the steady-state cycle. Observation only: shows what the circuit does, not whether it's correct. Never touches the canvas. |
show_circuit | Paint a circuit on the browser canvas, opening the viewer if needed. The file is read once, not watched: the assistant calls it again to repaint. |
setup_project | Make a folder ready for verify_circuit: writes package.json and installs @simten/core, fast-check and tsx. Only verify needs it. |
verify_circuit | Run a self-checking .verify.ts testbench at a declared oracle tier. This is the correctness gate (see Verifying circuits). |
simulate_circuit and show_circuit start a run the same way. inputs maps input port names, or the paths of Switch and Input nodes, to numbers, as simulate(top).set() takes them. memoryData maps exact node paths to { address: value } contents, as simulate(top, { memory }) does. A key or path that doesn't resolve is an error.
Inside a checkout of the Simten repo, the server also registers run_on_fpga (build, flash and capture a project on a ULX3S board). It works on files under hardware/ulx3s, so it isn't listed anywhere else.
get_grammar, list_components, and get_verify_api exist because clients cap an MCP server's instructions and each tool description at 2 KB, too small to inline the circuit API, the component catalog, or the testbench-writing guide. The assistant calls these on demand to get the authoritative part names, signatures, and simulate() API rather than guessing.
How the connection works
The MCP server runs locally alongside your assistant and serves two roles:
- MCP tool provider: the assistant calls tools via the standard MCP protocol (stdio transport).
- Local studio: a single HTTP + WebSocket server on
localhost:19847serves the bundled viewer and hosts the socket the viewer connects back on. The page and the socket share one origin, which is what sidesteps the browser's Local Network Access block.
When the assistant calls show_circuit, the data flows one way to the viewer for display. The viewer sends back only a boolean render acknowledgment, and there is no channel for the page to drive the assistant or read host state.
Assistant (terminal)
↕ MCP (stdio)
MCP Server (local)
↓ WebSocket push
Browser viewerSession & security
- Loopback only: the server binds
127.0.0.1, so it isn't reachable from your network. - Per-process token: a fresh token each time the MCP starts, handed to the viewer via the URL fragment; connections without it are rejected.
- Origin allowlist: only localhost-origin browser connections are accepted, so a web page you happen to be visiting can't open the socket.
- Viewer-only: the studio accepts nothing actionable from the browser; untrusted page data never reaches a tool result.
- Auto-reconnect & cache replay: the viewer reconnects automatically and receives the most recent pushed circuit on connect; each tab is its own session.
Example workflow
You: "Build me a 4-bit counter with a hex display"
The assistant:
- Writes the circuit: Register + Adder + Constant + HexDisplay
- Calls
show_circuit, and the circuit appears in your browser - Calls
simulate_circuitorverify_circuitto check it counts
You: "Can you add a reset button?"
The assistant:
- Edits the circuit file it already wrote
- Adds a Switch and Mux for reset logic
- Calls
show_circuitagain, and the viewer repaints with the reset switch
Everything else in Simten works without an assistant.