soldermaskdocs

MCP server

The MCP server lets another model drive the soldermask pipeline, stage by stage. It calls no model itself unless you turn on its datasheet reader. The client is the designer.

It builds a board on two copper layers or four. Set constraints.board.layers to 4 for four.

It speaks the Model Context Protocol, so Claude Code, Claude Desktop, Cursor, an Agent SDK loop or your own harness can use it.

Run it

CommandDoes
soldermask mcpServe on stdin and stdout
soldermask mcp --toolsPrint the tool list as JSON and stop
soldermask mcp --model-callsLet the resolver ask this tree's own models. Off by default.
SOLDERMASK_MCP_LOG=calls.jsonl soldermask mcpAlso write one JSON line per tool call

Register it the way your client registers any stdio server. For Claude Code:

claude mcp add soldermask -- soldermask mcp

For Claude Desktop, Cursor and the rest, put the same command in their mcpServers block:

{ "mcpServers": { "soldermask": { "command": "soldermask", "args": ["mcp"] } } }

The server reads the same environment as the command line, such as SOLDERMASK_PROJECTS for where versions are saved and SOLDERMASK_CACHE. Set them in the client's server entry, because the client starts the server with its own environment. No model key is needed, unless you turn on the datasheet reader. See Configuration.

For a client on another machine, the same server runs over HTTP with a key. See Serving it to others.

The order of a build

  1. Call status. It says which routers and judges this installation has.
  2. Call design_brief with the prompt. It returns the design stage's instructions, the schema and steps, the order a design is made in.
  3. Write the spec: every rail with its voltage and current, and every interface. Each rail becomes a power net.
  4. Decide what feeds each rail: a connector, a regulator, a battery or a charger.
  5. Choose parts with search_parts, and check what their pins are called with pins. A component carrying lcsc is ordered as chosen.
  6. Write the nets on the pin names pins returned.
  7. Call check_design. It resolves the parts, runs the ERC and reads back the power tree. Fix every error and call it again.
  8. If its notes name an IC with no datasheet record, call read_datasheet for it when the reader is on. Then call check_design again.
  9. Call place, or score_placement on a placement of your own. Loop here: each call takes seconds and routes nothing.
  10. Call build. It routes, pours, runs the DRC, writes the Gerbers and saves a version.
  11. Call verdict to read what the stored board says.

Most boards that fail here fail on a part that did not resolve, or a pin name the part does not have. Both show up before a build.

What the design check catches

The ERC in check_design and build includes the design check: what the parts' datasheets and the buses between them require. It catches a pin over its absolute maximum, an enable tied off and open USB-C CC pins. It also catches a missing I2C pull-up, missing bypass or bulk parts, and a diode wired backwards.

  • Errors fail the verdict. Warnings are yours to fix, or to answer in assumptions.
  • Each message names its source, such as the part's datasheet or a vendor's design guide.
  • A part with no datasheet record is checked by the bus and enable rules alone, and check_design names it in a note. The datasheet reader can write one.
  • SOLDERMASK_DESIGN_CHECK=0 turns every rule off.

Every rule, with its severity, is in The design check.

The idea

The client is the designer. The server calls no model, with one exception you turn on: read_datasheet. design_brief hands over what the design stage would have asked its own model, and build takes a design, never a bare prompt. So every other model call in a drive is the client's, and the result can be credited to it.

Nothing inside a stage calls a model either. When the server starts, it sets SOLDERMASK_MODEL_CALLS to none, over either transport:

  • A datasheet pin table that is not on disk is not fetched or transcribed.
  • Jev is not asked about a pin name, and a stored Jev answer is not read.
  • A design backend refuses before it is reached.

Pin tables transcribed earlier are data, like the catalogue, and are still read. status says how many are on disk. --model-calls lifts the switch, and status then says what may be asked.

The judge does not move. Each tool runs this pipeline's method or takes yours. Every result carries the same verdict, gaps and notes as a build from the app or the command line.

StageThis pipeline's methodYours
DesignNone: the server calls no modeldesign_brief gives you the design stage's system prompt, schema and constraints. You write the design.json, and check_design holds it to the schema.
PartsThe resolver turns each component's search into a part, or a gapsearch_parts shows the shelf the resolver picks from. pins names a part's pins. A component with lcsc is ordered as chosen.
Placementplace: the precedent, six anneals and the routability model's pickscore_placement rates your placement with nothing routed. build and rebuild take it as placement.
Routingbuild, with the router in rules.routerHand copper in constraints.tracks and constraints.vias, which the router keeps and routes around
JudgingAlways this pipeline's: workspace.verdict(), KiCad's DRC, the rubric and the routability modelNot offered

A placement is {ref: {x, y, rot, side}}. Turns are quarter turns only: 0, 90, 180 or 270.

A drive can be counted afterwards. SOLDERMASK_MCP_LOG names a file that gets one JSON line per tool call. Each line holds the tool, the arguments as sent, the text sent back, the seconds taken, and whether it was an error.

Tools

Six tools answer in lines: search_parts, pins, read_datasheet, place, score_placement and build. Their answer is text alone, with no structuredContent. Add format: "json" to get JSON instead.

Every other tool, and a refusal from any tool, returns JSON as text and the same object as structuredContent. Arguments are checked against each tool's inputSchema before it runs.

  • A result with ok: false and an errors list is a refusal the model can read, such as a design that misses the schema. It is marked isError.
  • A tool that could not run at all, such as one given no such project, is a tool error with one line saying why.
ToolTakesReturnsRuns
statusnothingThe routers and judges installed, and the shipped routability model with its training date and held-out numbers. The catalogue on disk, where projects and the cache go, and model_calls. Also datasheet_reader (on or off, and why), mould, offline and version. Call it first.nothing
design_briefpromptsystem: the design stage's system prompt, with the packages this tree can draw. schema: the accepted design schema. constraints: what the prompt says about the board, to pass to build. steps: the order a design is made in. then: what to do next. It also echoes prompt.nothing
search_partsquery?, kind?, value?, package?, limit?, in_stock?, format?Catalogue rows: LCSC code, part number, description, package, price, stock, pad count and footprint. With a kind, the rows are the resolver's own shelf in its order, and chosen is what a build would order. Without one, a text search.the resolver's ladder, and one resolve
read_datasheetlcsc, force?, format?The part's datasheet record: the external parts and limits the design check applies, each with its page and quote. Also where it came from, and what this call cost. Off, a part with no record gets a refusal saying how to turn the reader on.the disk, or two Azure models when the reader is on
pinslcsc, kind?, value?, format?What the part's pins are called once ordered. pins[].pin is the string a net's connection uses. Also the footprint and symbol they come from, every caveat, and component, the design line with the code pinned.one resolve
check_designdesign, constraints?, pins?, simulate?Every schema fault at once, by field and path. Each part resolved to an LCSC code, price and stock, or a gap. The ERC, with the design check's rules. power_tree: what feeds each rail and what it supplies. With pins, every part's pin names; with simulate, ngspice. Nothing placed.resolve, ERC, design check
placedesign, constraints?, seed?, candidates?, heat?, format?This pipeline's placement: every candidate's rating, the model's pick, the placement report, the rubric, notes and precedents. Pinned parts stay put. heat adds the model's 32×32 congestion picture.one realise(), no fab output
score_placementdesign, placement, constraints?, heat?, format?The same report for your placement, with every coordinate untouched. A placement short of a part is refused, with a note to pin instead. placement may be the gnm block from an earlier answer.one realise(), no fab output
precedentdesign, limit?The corpus boards sharing the most parts with this design, and the best match's placement keyed by your refs. pipeline_would_seed_from_it says whether the pipeline would use it.the corpus index
builddesign, prompt?, project?, placement?, constraints?, router?, seed?, pour?, precedent?, min_track_mm?, route?, simulate?, quantities?, note?, format?The whole build saved as a version: resolve, ERC, simulate, place, route, pour, DRC, rubric, fab files, KiCad file and price. Returns the verdict, the routing report and the files.one realise() and one commit()
rebuildproject, version?, placement?, constraints?, router?, seed?, pour?, precedent?, min_track_mm?, route_only?, route?, simulate?, note?The version's own design built again as a new version, under today's constraints plus this call's. route_only keeps the placement and routes once.one realise() and one commit()
verdictproject, version?What the stored board says: the verdict and why, the routing report with copper counted, the rubric, ERC, gaps, notes and filesnothing
drcproject, version?, dry_run?KiCad's DRC today on the version's KiCad file, zones filled, with the verdict rewritten where the answer movedkicad-cli
projectsarchived?Every project, with its version count and whether the current version passednothing

Asking for parts. Ask for a resistor, capacitor, inductor or crystal by kind and value, plus package if it matters. The parametric index answers that exactly. A footprint of "" means the pads come from the vendor's drawing of that exact code (package FROM_PART).

build and projects.

  • The project is created if it does not exist.
  • prompt is kept with the version as what the board was asked for. A prompt without a design builds nothing.
  • In a project that already has a constraints block, a constraints argument replaces it, as a rebuild after PUT /constraints does in the app.
  • A block inside the design is carried and set aside for the project's own, with a note saying so.

Two keys beyond the schema. DESIGN_SCHEMA is closed: every object refuses a field it does not name. A design you write may also carry two choices of yours:

  • the constraints block;
  • lcsc on a component, the catalogue code you chose. resolve() orders it as chosen rather than searching again. A code that is not C followed by digits is refused.

A placement you hand in. build and rebuild store it in the version's constraints.pinned with by: "import", so the workbench shows it and a rebuild keeps it. A whole placement also sets board.fixed, because it was made for that outline. A partial placement is pins, and the placer arranges the rest around them.

The knobs (router, seed, pour, precedent, min_track_mm) go into constraints.rules, where the workbench's rack puts them. The version records how it was built, and a rebuild repeats it. router is lightcycle (the default) or krt (the A* router). The rest of the block, such as board.layers, rules.mark or board.mounting_holes, goes in constraints. See design.json.

Reading a datasheet

read_datasheet returns what a part's datasheet requires around it. It reads the disk first. It calls a model only when the reader is on and the part has no record.

  1. Set SOLDERMASK_DATASHEET_READER=azure in the server's environment, and give it an Azure key. See Configuration. status then shows datasheet_reader.on as true.
  2. Call check_design. Its notes name each IC or module with no datasheet record.
  3. Call read_datasheet with that part's lcsc. It takes one to two minutes.
  4. Call check_design again. The datasheet rules now check that part.
A part withread_datasheetCost
A record in the shipped libraryReturns it. A shipped record always wins.nothing
A record the reader wrote beforeReturns it. force reads the sheet again.nothing, or a new read
No record, reader onReads the sheet, stores the record in the cache, returns itabout $0.07, at most SOLDERMASK_READER_MAX_USD
No record, reader offRefuses, and says how to turn the reader onnothing

How a sheet is read. Two reads run at once, and their answers are merged:

StepWhat happens
Read ADeepSeek-V4.1-Flash gets the careful reader's instructions and the sheet's chosen pages. It may search the sheet and fetch pages, eight times at most. It returns the whole record.
Read Bgpt-5.4 answers one question: every external part the chip needs, with its value, pins, page and a verbatim quote. It also sees the application pages as images.
MergeThe external parts of both reads, one item a part. Pins and limits come from read A.
Read COff unless SOLDERMASK_READER_DRAW is set. gpt-5.4-mini, or gpt-6-luna, lists every part in up to three of the sheet's drawings, at 300 dpi. It runs only when a figure value has no second reading yet.
Rulesmodule_internal drops a module's own crystal, flash or antenna listed as external. figure_agreement drops a value read off a figure by one read only, which no other read has and the text never prints.
AuditAn item is applied if its quote is on the sheet and every number is in its quote. A figure value another read confirmed is applied too.

Read C is a second reading only. A figure value it confirms says so in figure_confirmed. A part only read C found is never applied. If read C cannot run, the record is stored without it and says why.

Every record says how it was made under read: the reader's version, each model, the date, the tokens and the cost. What the audit or the rules held back is kept in the record and never applied.

On the 30 test sheets set aside for checking, the applied items found 82.1% of the external parts a chip requires. Of the items applied, 4.4% were wrong. Read C leaves both numbers as they are, so it is off by default. The CHANGELOG holds the evidence.

Not automatic

check_design and build never read a sheet. A read costs time and money, so it is the caller's choice.

How a catalogue answer reads

search_parts, pins and read_datasheet answer in lines, unless the call says format: "json". The data is the same either way. A search result:

search "" kind=resistor package=0603 value=10k "via=the resolver's ladder"
asked kind=resistor search=10k package=0603 value=10k
rows lcsc mfr package footprint kind stock price basic pads description category
* C98220 RC0603FR-0710KL 0603 0603 resistor 13677496 0.0035 - 2 "-55℃~+155℃ 100mW 10kΩ 75V ..." "resistors chip resistor surface mount"
- C99198 RC0603JR-0710KL 0603 0603 resistor 3993432 0.0037 - 2 "..." "..."
chosen C98220 drawn_as=0603
component kind=resistor search=RC0603FR-0710KL package=0603 value=10k lcsc=C98220
more 221 rows not shown; ask with a larger limit
note "..."
LineMeans
rowsThe column names, once. Each row after it is one line.
* rowThe part a build would order for the component as asked
- rowAnother part on the shelf
chosenThe * part, with the footprint it is drawn as
componentThe design line to copy, with the code pinned
moreHow many rows limit cut
note, gapWhat the JSON puts in those fields

basic is B or -, and prices are in USD. A value with a space in it is quoted. A pins result has a pins line, a pin pad name why header, one line per pin, then component and the notes. A refusal stays JSON and is marked as an error.

A read_datasheet result opens with a datasheet line: the code, part number, package, source, whether it was read now, and the cost. Then come:

  1. a provenance line;
  2. an external_parts header, and one - line for each applied part;
  3. a limits header, and one - line for each applied limit, with the quote last;
  4. held_back, uncovered, path, note and gap lines.

Lines are cheaper to read than JSON. Twenty catalogue rows are 1,628 tokens as lines and 3,036 as JSON, and a model answered questions from both equally well. soldermask/tables.py writes them, and tests/test_mcp.py reads them back to every field.

How a board answer reads

place, score_placement and build also answer in lines, unless the call says format: "json". The placement comes last, as a gnm block (soldermask/gnm.py). A score_placement answer on a four-part board, with the descriptions cut:

score_placement erc=[] precedents=[] routing=null unsupported=[] gaps=[] ok=true errors=[]
verdict passed=true why=[] erc_ran=true copper_judged=false parts_asked=4 parts_resolved=4 erc_errors=0 unrouted=0 pour_errors=0 dropped_nets=0 dropped_connections=0 hot_copper=0 routing_required=false
placement_report cost=8.73 worst_overlap_mm2=0.0 off_board_mm=0.0 antenna_copper_mm2=0 clean=true
predicted p_clean=0.926 unrouted=0.0 method=rudy model="analytic: ..." spread=0.0
candidates seed cost p_clean unrouted spread
- 1 8.73 0.926 0.0 0.0
board name=led-3v3 width_mm=15.0 height_mm=12.0
rubric graded=4 catalogue=82
rubric.rules rule verdict measured
- compactness bad "occupancy 17%"
- connector-on-edge good "1/1 seated"
parts asked=4 resolved=4
parts.list ref kind value lcsc mfr package price_each basic stock description
- R1 resistor "150" C22808 0603WAF1500T5E 0603 0.0026 true 789870 "..."
note "the parts were placed with 0.5mm of air between courtyards rather than packed; ..."
gnm 1 unit=mm
board 15x12
parts ref id kind x y [rot] [B]
C1 C15849 capacitor 8.306 9.288
D1 C19171390 led 11.019 8.201 90
J1 C358684 connector 4.776 9.46 90
R1 C22808 resistor 8.3 7.333
ShapeSections
The first lineThe tool's name, and the result's plain fields as key=value
One line of key=valueverdict, routing, routing.pour, placement_report, predicted, board, bom
A table: a header line, then one - line per row, ~ for an empty valuecandidates, erc, parts.list, precedents, rubric.rules, constraints.pinned
One line per itemwhy, gap, note, unsupported, error
One line of namesfiles

Anything else is one line of JSON after its name. A value with a space is quoted. gnm.result_decode() reads the lines back to the same data, field for field.

The pour's counts. In routing.pour, copper_errors is what the verdict counts. kicad_drc_errors is what KiCad's DRC shows a person who opens the board, including what the verdict sets aside. set_aside names those by kind, such as a starved thermal.

The gnm block is parts ref id kind x y [rot] [B]:

FieldMeans
x, yMillimetres to the micrometre, origin bottom-left, y up
idThe part's LCSC code
rotCounter-clockwise degrees, left out at 0
BThe part is on the back

A build given hand copper adds a copper section: t net F|B width_um x y x y ... for a track and v net x y for a via.

The block goes back in as placement, to score_placement, build or rebuild, alone or with the whole answer around it. Only where each part goes is read. These are refused, by ref:

  • a line whose kind, or pinned LCSC code, is not the design's (change a part in the design, not by moving it);
  • a block with nets or copper in it;
  • a block whose board line is larger than the design's outline, or a different shape. place grows an outline its parts do not fit, and says so. Set design.board to the outline the placement was made on.

place also cuts a roomy board down to its parts. A smaller board line is taken into the design, with a note, unless the size was fixed or asked for. The size is fixed by board.fixed or size_asked, or by a size or mains in the prompt.

A block you write may use integer units instead (gnm 1 unit=0.01mm, 831 for 8.31 mm). Answers use millimetres to the micrometre, because at 0.01 mm a placement read back was judged differently on 13 of 60 boards. As lines, a board answer is about 1.6 times smaller than its JSON.

Resources

URIContents
soldermask://schema/designThe accepted design schema: DESIGN_SCHEMA, with every object closed, plus lcsc on a component and the constraints block
soldermask://schema/constraintsCONSTRAINTS_SCHEMA: pins, hand copper and the knobs
soldermask://packagesThe footprint names a design may use, and FROM_PART
soldermask://docs/design-json, …/board-json, …/mcpThese pages. Only from a checkout, because an install does not carry docs/.
soldermask://projects/{slug}/{version}/{file}Any file a version holds: board.json, design.json, a Gerber, the .kicad_pcb, sim.json. Listed for each project's current version; the template is under resources/templates/list.
soldermask://projects/{slug}/{version}/fab.zipThe Gerbers, drill, BOM and CPL zipped, as the app's download is. Sent as a base64 blob, for a client that cannot reach this disk.

Progress

A build takes seconds to minutes. On the 305 saved designs of the replay pool, it averaged about 43 seconds. A board with 306 LEDs took 15 minutes. While a tool runs, the server sends notifications/message at level info, one line per stage: resolving parts, placing, routing, saving. When the call carries a progressToken in _meta, it also sends notifications/progress with the same text. That keeps a client's timeout from firing on a board that is still routing.

Serving it to others

soldermask mcp --http serves the same fourteen tools and the same judge to a client on another machine, with a URL and a key. Nothing ships to the client: not the code, the model, the catalogue or the corpus.

  1. Issue a key. It prints once, as sm_...; the keys file keeps only its SHA-256.

    soldermask mcp keys add alice
  2. Start the server. Keys and projects live under $SOLDERMASK_HOME (see Configuration), and one build runs at a time.

    soldermask mcp --http --port 8787
  3. Put TLS in front, such as a Cloudflare or Tailscale tunnel or a reverse proxy.

  4. Register it in the client, with the key as a bearer header:

    claude mcp add --transport http soldermask https://HOST/mcp --header "Authorization: Bearer sm_..."
    { "mcpServers": { "soldermask": { "url": "https://HOST/mcp",
                                      "headers": { "Authorization": "Bearer sm_..." } } } }
FlagDefaultDoes
--host127.0.0.1The address to bind
--port8787The port
--keys FILE$SOLDERMASK_HOME/mcp-keys.json, or SOLDERMASK_MCP_KEYSThe keys file
--projects DIR$SOLDERMASK_HOME/mcp-projects, or SOLDERMASK_MCP_PROJECTSOne directory per key under here
--builds N1, or SOLDERMASK_MCP_BUILDSHow many builds may run at once
--origin URLA browser Origin to allow. Repeat for several.

The keys have three commands. Each takes --keys FILE before the verb.

CommandDoes
soldermask mcp keys add NAMEIssues a key and prints it, once
soldermask mcp keys listEvery key's name, directory, date and state. Never the key.
soldermask mcp keys revoke NAMEThe key stops working on the next request

Before you open it

With the datasheet reader on, every key holder can start a read billed to your Azure account. Each read stops at SOLDERMASK_READER_MAX_USD, but nothing caps the total. Bind to localhost and put TLS in front. A bearer key sent over plain HTTP across a network is a key given away. Point SOLDERMASK_CORPUS at a directory of the server's own. Builds label their placements into the corpus, and other people's boards in your training data should be a decision.

The transport is the protocol's Streamable HTTP, on one endpoint:

RequestAnswer
POST /mcp, not a tool callJSON
POST /mcp, a tool call, with Accept: text/event-streamA text/event-stream: the progress and log notifications, a keepalive every 15 seconds, then the response
POST /mcp, a tool call without itJSON, when the call ends
initializeMints an Mcp-Session-Id
A forgotten session404. The client initialises again. Sessions are forgotten after a restart or a day of silence.
GET /mcp405
DELETE /mcpEnds the session
GET /One line naming the server, to test a tunnel

The server refuses a request:

AnswerWhen
401No key, or a key it does not know
403A browser Origin that --origin did not allow
400An MCP-Protocol-Version it does not speak, or no session on a call that is not initialize
413A body over 4 MB

A key is a directory. Each request under a key keeps its projects in <projects>/<name>/. build saves there, and projects and resources/list see only that. Reading another key's board answers "no such resource". The keys file is read again on every lookup, so keys add works on the next request and keys revoke on the one after.

One build at a time. place, score_placement, build and rebuild each take a build slot. A call that finds none says waiting for a build slot down its stream. After ten minutes it returns a result saying the server was busy. Every other tool runs at once.

What a remote client does not get.

  • A precedent's placement leaves the machine only under a permissive licence, such as MIT, BSD, Apache-2.0, CC0, CC-BY or CERN-OHL-P. Otherwise start.withheld names the licence, and matches still names the repository.
  • A server path means nothing over HTTP. So build, rebuild and verdict add resources: the URIs of the version's files, and fab.zip.
  • status names the transport, the key and the key's directory, and not the cache.

Not built yet

OAuth, which Claude Desktop's connector list wants (Claude Code, Cursor and the SDKs take a header). A rate limit or daily cap per key. A queue position for a call waiting on a slot.

What the score means

The routability model judges between boards. The shipped model was fitted on 14 Sep 2026, and scored AUC 0.916 on held-out boards and 0.914 on PCBench. Ordering one board's own placements is where it, and three other instruments, measured near chance. The model file stores 0.593 within a board, over 498 boards (meta.models.cnn.within_board in soldermask/assets/routability.json). status and score_placement return it as auc_within_board.

score_placement carries the model's numbers beside its rating for that reason. On a poured board, the rating is the analytic one, and says so. Use it to catch overlaps, off-board parts and rubric faults. Use build to find out whether a placement routes. See Routability.

Under the hood

  • The code is soldermask/mcp.py, and soldermask/mcp_http.py for the HTTP door.
  • The transport is JSON-RPC 2.0, one message per line.
  • The methods are initialize, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list (empty) and logging/setLevel.
  • It speaks protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, using the client's when it is one of those.
  • Only protocol goes to stdout. While the server runs, sys.stdout points at stderr.
  • Every build is one workspace.realise() call and one commit(), as on the command line. tests/test_mcp.py counts them.
  • The server is written by hand, without the mcp package, so the base dependencies stay at six.
  • The app's HTTP API is a different door, for the app's own clients.

On this page