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
| Command | Does |
|---|---|
soldermask mcp | Serve on stdin and stdout |
soldermask mcp --tools | Print the tool list as JSON and stop |
soldermask mcp --model-calls | Let the resolver ask this tree's own models. Off by default. |
SOLDERMASK_MCP_LOG=calls.jsonl soldermask mcp | Also 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 mcpFor 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
- Call
status. It says which routers and judges this installation has. - Call
design_briefwith the prompt. It returns the design stage's instructions, the schema andsteps, the order a design is made in. - Write the spec: every rail with its voltage and current, and every interface. Each rail becomes a power net.
- Decide what feeds each rail: a connector, a regulator, a battery or a charger.
- Choose parts with
search_parts, and check what their pins are called withpins. A component carryinglcscis ordered as chosen. - Write the nets on the pin names
pinsreturned. - Call
check_design. It resolves the parts, runs the ERC and reads back the power tree. Fix every error and call it again. - If its notes name an IC with no datasheet record, call
read_datasheetfor it when the reader is on. Then callcheck_designagain. - Call
place, orscore_placementon a placement of your own. Loop here: each call takes seconds and routes nothing. - Call
build. It routes, pours, runs the DRC, writes the Gerbers and saves a version. - Call
verdictto 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_designnames it in a note. The datasheet reader can write one. SOLDERMASK_DESIGN_CHECK=0turns 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.
| Stage | This pipeline's method | Yours |
|---|---|---|
| Design | None: the server calls no model | design_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. |
| Parts | The resolver turns each component's search into a part, or a gap | search_parts shows the shelf the resolver picks from. pins names a part's pins. A component with lcsc is ordered as chosen. |
| Placement | place: the precedent, six anneals and the routability model's pick | score_placement rates your placement with nothing routed. build and rebuild take it as placement. |
| Routing | build, with the router in rules.router | Hand copper in constraints.tracks and constraints.vias, which the router keeps and routes around |
| Judging | Always this pipeline's: workspace.verdict(), KiCad's DRC, the rubric and the routability model | Not 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: falseand anerrorslist is a refusal the model can read, such as a design that misses the schema. It is markedisError. - A tool that could not run at all, such as one given no such project, is a tool error with one line saying why.
| Tool | Takes | Returns | Runs |
|---|---|---|---|
status | nothing | The 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_brief | prompt | system: 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_parts | query?, 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_datasheet | lcsc, 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 |
pins | lcsc, 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_design | design, 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 |
place | design, 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_placement | design, 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 |
precedent | design, 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 |
build | design, 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() |
rebuild | project, 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() |
verdict | project, version? | What the stored board says: the verdict and why, the routing report with copper counted, the rubric, ERC, gaps, notes and files | nothing |
drc | project, version?, dry_run? | KiCad's DRC today on the version's KiCad file, zones filled, with the verdict rewritten where the answer moved | kicad-cli |
projects | archived? | Every project, with its version count and whether the current version passed | nothing |
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.
promptis 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
constraintsargument replaces it, as a rebuild afterPUT /constraintsdoes 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
constraintsblock; lcscon a component, the catalogue code you chose.resolve()orders it as chosen rather than searching again. A code that is notCfollowed 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.
- Set
SOLDERMASK_DATASHEET_READER=azurein the server's environment, and give it an Azure key. See Configuration.statusthen showsdatasheet_reader.onastrue. - Call
check_design. Its notes name each IC or module with no datasheet record. - Call
read_datasheetwith that part'slcsc. It takes one to two minutes. - Call
check_designagain. The datasheet rules now check that part.
| A part with | read_datasheet | Cost |
|---|---|---|
| A record in the shipped library | Returns it. A shipped record always wins. | nothing |
| A record the reader wrote before | Returns it. force reads the sheet again. | nothing, or a new read |
| No record, reader on | Reads the sheet, stores the record in the cache, returns it | about $0.07, at most SOLDERMASK_READER_MAX_USD |
| No record, reader off | Refuses, and says how to turn the reader on | nothing |
How a sheet is read. Two reads run at once, and their answers are merged:
| Step | What happens |
|---|---|
| Read A | DeepSeek-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 B | gpt-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. |
| Merge | The external parts of both reads, one item a part. Pins and limits come from read A. |
| Read C | Off 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. |
| Rules | module_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. |
| Audit | An 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 "..."| Line | Means |
|---|---|
rows | The column names, once. Each row after it is one line. |
* row | The part a build would order for the component as asked |
- row | Another part on the shelf |
chosen | The * part, with the footprint it is drawn as |
component | The design line to copy, with the code pinned |
more | How many rows limit cut |
note, gap | What 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:
- a
provenanceline; - an
external_partsheader, and one-line for each applied part; - a
limitsheader, and one-line for each applied limit, with the quote last; held_back,uncovered,path,noteandgaplines.
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| Shape | Sections |
|---|---|
| The first line | The tool's name, and the result's plain fields as key=value |
One line of key=value | verdict, routing, routing.pour, placement_report, predicted, board, bom |
A table: a header line, then one - line per row, ~ for an empty value | candidates, erc, parts.list, precedents, rubric.rules, constraints.pinned |
| One line per item | why, gap, note, unsupported, error |
| One line of names | files |
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]:
| Field | Means |
|---|---|
x, y | Millimetres to the micrometre, origin bottom-left, y up |
id | The part's LCSC code |
rot | Counter-clockwise degrees, left out at 0 |
B | The 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
boardline is larger than the design's outline, or a different shape.placegrows an outline its parts do not fit, and says so. Setdesign.boardto 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
| URI | Contents |
|---|---|
soldermask://schema/design | The accepted design schema: DESIGN_SCHEMA, with every object closed, plus lcsc on a component and the constraints block |
soldermask://schema/constraints | CONSTRAINTS_SCHEMA: pins, hand copper and the knobs |
soldermask://packages | The footprint names a design may use, and FROM_PART |
soldermask://docs/design-json, …/board-json, …/mcp | These 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.zip | The 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.
-
Issue a key. It prints once, as
sm_...; the keys file keeps only its SHA-256.soldermask mcp keys add alice -
Start the server. Keys and projects live under
$SOLDERMASK_HOME(see Configuration), and one build runs at a time.soldermask mcp --http --port 8787 -
Put TLS in front, such as a Cloudflare or Tailscale tunnel or a reverse proxy.
-
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_..." } } } }
| Flag | Default | Does |
|---|---|---|
--host | 127.0.0.1 | The address to bind |
--port | 8787 | The port |
--keys FILE | $SOLDERMASK_HOME/mcp-keys.json, or SOLDERMASK_MCP_KEYS | The keys file |
--projects DIR | $SOLDERMASK_HOME/mcp-projects, or SOLDERMASK_MCP_PROJECTS | One directory per key under here |
--builds N | 1, or SOLDERMASK_MCP_BUILDS | How many builds may run at once |
--origin URL | A browser Origin to allow. Repeat for several. |
The keys have three commands. Each takes --keys FILE before the verb.
| Command | Does |
|---|---|
soldermask mcp keys add NAME | Issues a key and prints it, once |
soldermask mcp keys list | Every key's name, directory, date and state. Never the key. |
soldermask mcp keys revoke NAME | The 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:
| Request | Answer |
|---|---|
POST /mcp, not a tool call | JSON |
POST /mcp, a tool call, with Accept: text/event-stream | A text/event-stream: the progress and log notifications, a keepalive every 15 seconds, then the response |
POST /mcp, a tool call without it | JSON, when the call ends |
initialize | Mints an Mcp-Session-Id |
| A forgotten session | 404. The client initialises again. Sessions are forgotten after a restart or a day of silence. |
GET /mcp | 405 |
DELETE /mcp | Ends the session |
GET / | One line naming the server, to test a tunnel |
The server refuses a request:
| Answer | When |
|---|---|
| 401 | No key, or a key it does not know |
| 403 | A browser Origin that --origin did not allow |
| 400 | An MCP-Protocol-Version it does not speak, or no session on a call that is not initialize |
| 413 | A 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.withheldnames the licence, andmatchesstill names the repository. - A server path means nothing over HTTP. So
build,rebuildandverdictaddresources: the URIs of the version's files, andfab.zip. statusnames 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, andsoldermask/mcp_http.pyfor 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) andlogging/setLevel. - It speaks protocol versions
2025-06-18,2025-03-26and2024-11-05, using the client's when it is one of those. - Only protocol goes to stdout. While the server runs,
sys.stdoutpoints at stderr. - Every build is one
workspace.realise()call and onecommit(), as on the command line.tests/test_mcp.pycounts them. - The server is written by hand, without the
mcppackage, so the base dependencies stay at six. - The app's HTTP API is a different door, for the app's own clients.