Simten

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:

  1. Writes the circuit to a TypeScript file in your repo
  2. Draws it in a browser tab
  3. 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/mcp

3. 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:

ToolWhat it does
get_startedOrientation and the bundled examples (Snake, a RISC-V computer, an ALU, ...). With example, writes one to circuits/<id>.circuit.ts. No setup needed.
get_grammarReturn the circuit() builder API (inputs/outputs, nodes, connect) with worked examples.
list_componentsReturn the full catalog of stdlib components, each with its ports and constructor options (e.g. Register({ width })).
get_verify_apiReturn how to write a .verify.ts testbench: simulate(top, { memory }), set for ports and switches, verify.exhaustive/verify.check, declareOracle, and worked examples.
check_circuitCompile a circuit and report whether it builds, with the location of a compile error.
simulate_circuitCompile 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_circuitPaint 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_projectMake a folder ready for verify_circuit: writes package.json and installs @simten/core, fast-check and tsx. Only verify needs it.
verify_circuitRun 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:

  1. MCP tool provider: the assistant calls tools via the standard MCP protocol (stdio transport).
  2. Local studio: a single HTTP + WebSocket server on localhost:19847 serves 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 viewer

Session & 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:

  1. Writes the circuit: Register + Adder + Constant + HexDisplay
  2. Calls show_circuit, and the circuit appears in your browser
  3. Calls simulate_circuit or verify_circuit to check it counts

You: "Can you add a reset button?"

The assistant:

  1. Edits the circuit file it already wrote
  2. Adds a Switch and Mux for reset logic
  3. Calls show_circuit again, and the viewer repaints with the reset switch

Everything else in Simten works without an assistant.

On this page