Simten

Claude Code Integration

How to use Claude as an AI tutor for building circuits

Simten integrates with Claude Code via MCP (Model Context Protocol). You talk to Claude in your terminal; Claude writes TypeScript circuit files, pushes them to a live viewer in your browser, and runs simulations and verification — so you watch the circuit take shape on a canvas as Claude builds it.

What it looks like

You run Claude Code in your terminal. When you ask Claude to build something, it:

  1. Writes the TypeScript circuit definition to a file
  2. Pushes it to a live viewer in your browser — the circuit appears on the canvas instantly
  3. Runs a simulation, or a self-checking testbench, to confirm it behaves correctly

The browser is a viewer: Claude pushes circuits, waveforms, and test results to it for display. It is one-way by design — the page shows what Claude built and sends nothing actionable back (see Security). You drive the conversation from the terminal, where Claude Code already lives.

Setup

1. Install Claude Code

Follow the Claude Code installation guide if you haven't already.

2. Add the MCP server

claude mcp add simten npx @simten/mcp

This registers the Simten MCP server with your Claude Code installation. Claude now has access to circuit design tools.

3. That's it — the viewer opens itself

When Claude calls show_circuit, the MCP serves a small bundled editor from localhost and opens it in your browser automatically. Because the page and its WebSocket share a single localhost origin, there's no "Local Network Access" prompt and it works in every browser (including Safari). You don't need to visit simten.dev.

Available tools

Once the MCP server is registered, Claude has access to these tools:

ToolWhat it does
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 — the simulate() stepper API, verify.exhaustive/verify.check, declareOracle, and worked examples.
show_circuitPush a circuit file to the browser viewer and open a live preview. Watches the file for changes.
check_circuitValidate circuit source (syntax, semantic, type, structural) without running it.
simulate_circuitCompile and simulate; return signal traces and the steady-state cycle. Observation only — shows what the circuit does, not whether it's correct.
verify_circuitRun a self-checking .verify.ts testbench at a declared oracle tier. This is the correctness gate (see Verifying circuits).
read_waveformQuery a VCD waveform for specific signals over a cycle window.
run_on_fpgaBuild and run the circuit on a connected FPGA board.

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. Claude 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 Claude Code and serves two roles:

  1. MCP tool provider — Claude 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 Claude calls show_circuit (or pushes traces / test results), the data flows one way to the viewer for display. The viewer sends back only a boolean render acknowledgment — there is no channel for the page to drive Claude or read host state.

Claude Code (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"

Claude:

  1. Writes the circuit: Register + Adder + Constant + HexDisplay
  2. Calls show_circuit — the circuit appears in your browser viewer
  3. Calls simulate_circuit (or verify_circuit) to confirm it counts correctly
  4. Replies in the terminal: "I've built a 4-bit counter. Click play to watch it count from 0 to F."

You: "Can you add a reset button?"

Claude:

  1. Edits the circuit file it already wrote
  2. Adds a Switch and Mux for reset logic
  3. Calls show_circuit again — the viewer updates live, and you see the reset switch appear

Running without Claude

The app works without Claude Code. You can:

  • Write circuit code directly in the editor
  • Explore the interactive blog posts
  • Embed circuits in your own React app

Claude is an enhancement, not a requirement. The MCP server adds an AI tutor to the experience, but all the tools and content work standalone.

Building custom UIs

Four tiers — from drop-in <CircuitEmbed /> to full composition with useCircuitSimulator + CircuitCanvas.

Security Architecture

How Simten isolates untrusted circuit code in both the browser and the MCP server

On this page

What it looks likeSetup1. Install Claude Code2. Add the MCP server3. That's it — the viewer opens itselfAvailable toolsHow the connection worksSession & securityExample workflowRunning without Claude