MCP server
Gerbtrace runs a Model Context Protocol (MCP) server, so AI assistants and other approved apps can read and change your projects with exactly the permissions you have. Newmatik's assistant Moth uses it, and any MCP client that supports OAuth can connect the same way.
https://www.gerbtrace.com/mcp
This is the only address you need. Give it to your assistant as written,
including www..
Connect your assistant
The assistant registers itself, sends you to Gerbtrace to sign in, and then shows the Authorize access screen (see Sign-in and consent).
| Assistant | How to add it |
|---|---|
| Claude (web and desktop) | Settings → Connectors → Add custom connector, paste the URL, then Connect. On Team and Enterprise plans an owner adds it once under Organization settings → Connectors, and each member connects their own account. |
| Claude Code | claude mcp add --transport http gerbtrace https://www.gerbtrace.com/mcp (add --scope user to use it in every project), then run /mcp in Claude Code and choose Authenticate. |
| ChatGPT | Settings → Apps → Advanced settings, turn on Developer mode, then Create app with the URL and OAuth authentication. |
| Codex | codex mcp add gerbtrace --url https://www.gerbtrace.com/mcp, then codex mcp login gerbtrace. |
| Cursor | Add "gerbtrace": { "url": "https://www.gerbtrace.com/mcp" } under mcpServers in ~/.cursor/mcp.json. |
| VS Code | Add "gerbtrace": { "type": "http", "url": "https://www.gerbtrace.com/mcp" } under servers in .vscode/mcp.json, then start the server from the file. |
| Moth | Settings → Integrations → Gerbtrace → Connect. |
Sign-in and consent
- Sign in to Gerbtrace if you are not signed in already. If your account uses two-factor authentication, complete it when Gerbtrace asks; the assistant cannot use your account without it.
- The Authorize access screen names the app, your account, what the app
will be able to do, and where access will be sent:
- a known assistant by its address, for example
claude.aiorchatgpt.com; - "an app on this computer" for Claude Code, Codex and other local tools;
- the full address for anything else, such as
cursor://…orvscode://…, with a warning that Gerbtrace does not recognise it.
Any app can call itself anything, so check the destination, not the name. Allow access only if you just started connecting from that app. - a known assistant by its address, for example
- When you allow it, the app receives a token that identifies you. Every request it makes is checked against your team roles, space memberships and project status. It can never see or change more than you can in Gerbtrace.
- Tokens expire after an hour and are refreshed silently while the connection stays authorized.
Tools
Read tools only look. Write tools change data you could change in
Gerbtrace yourself. Tools marked Needs confirm change nothing unless the
assistant passes confirm: true; without it they return a preview of what
would happen, so the assistant can ask you first.
| Tool | What it does | Type | Needs confirm |
|---|---|---|---|
whoami | Your profile, teams with roles, and spaces | Read | |
list_teams | Your teams with role and plan | Read | |
get_team | Team details and defaults (never secrets) | Read | |
update_team | Team name, currency, time format, panel defaults, auto-join domain (admins) | Write | Only for the auto-join domain |
create_team | Create a team with you as admin | Write | |
list_team_members | Members, roles and pending invitations | Read | |
invite_team_member | Invite someone by email (admins); sends the invitation email | Write | Yes |
update_team_member | Change a member's role or status (admins) | Write | Yes |
remove_team_member | Remove a member from a team (admins) | Write | Yes |
list_spaces | Spaces in a team | Read | |
create_space | Create a space (admins) | Write | |
get_team_usage | This month's metered usage | Read | |
list_projects | List and search projects | Read | |
get_project | Project overview: workflow, people, files, documents, assembly variants | Read | |
create_project | Create a project | Write | |
update_project | Rename or reassign a project | Write | |
delete_project | Permanently delete a project and its files | Write | Yes |
transition_project_workflow | Set in progress, request approval, approve (a team admin also straight from draft or in progress), request changes, reopen an approved project for revision (with a reason), revert to draft | Write | |
get_project_settings | Project settings as stored; with variant, also the variant's own process settings | Read | |
update_project_settings | Change project settings; part_patches changes single parts of the pick-and-place fields (rotation, DNP, packages, polarity, notes, …) without overwriting what others change at the same time; with variant, the variant's process settings (process_overrides) | Write | |
update_pcb_data | PCB parameters: size, stack-up, finish, mask, legend, IPC class | Write | |
update_panel | Production panel; preset: "aa-en-034" sets the Newmatik standard panel from the board size | Write | |
update_assembly_documentation | Assembly drawing title block, steps, labels per stage and target (with the text in a board label's red box, marker, default BC), notes with callouts and a colour each (orange, green, black; the older purple is read as black) or as text boxes on the board with a rotation (0/90/180/270°), edge arrows, pin 1 picked on the board, designator tags | Write | |
list_project_files | Gerber, drill, pick-and-place and BOM files | Read | |
get_project_file | Download a file as text, in pages | Read | |
create_upload_url | A link to send a file from disk (curl -X PUT) for the upload tools and import_archive, so no file bytes go through the chat | Write | |
upload_project_file | Add or replace a file in a draft project | Write | |
upload_project_document | Attach or replace a PDF in a draft project | Write | |
upload_project_model | Attach or replace the STEP 3D model | Write | |
upload_project_render | Store a 3D render image | Write | |
get_project_model | 3D model and renders with short-lived download links | Read | |
delete_project_file | Remove a file from a draft project | Write | Yes |
delete_project_document | Remove a PDF from a draft project | Write | Yes |
get_bom | BOM lines with manufacturers and DNP; with variant (id or item code), that assembly variant's BOM, DNP set and designators without a placement | Read | |
set_bom | Replace the BOM line list | Write | |
list_project_messages | Project conversation | Read | |
post_project_message | Post a comment, optionally mentioning members | Write | |
list_notifications | Your inbox | Read | |
mark_notifications_read | Mark notifications as read | Write | |
list_team_packages | Custom SMD and THT packages | Read | |
get_team_package | One custom package in full | Read | |
upsert_team_package | Create or replace a custom package | Write | |
generate_assembly_documentation | Render the assembly drawing PDFs, one per ERP step (<item>-<site>-<step>_Assembly-Drawing.pdf, with the BOM revision stamp), and store them in a draft or in-progress project, or in an approved project or variant, where they carry the approval (team editors); with variant, the drawings of that assembly variant; with step, one step's PDF | Write | |
import_archive | Import a customer ZIP (Gerber, drill, pick-and-place, BOM, PDFs, STEP) into a draft project in one call, sent with create_upload_url, as an https link or inline | Write | |
analyze_project | Board size, copper layers, placements per side, SMT classes, unique part numbers, BOM/pick-and-place mismatches and the ERP Assembly Specification counts and processes; with variant, of that assembly variant | Read | |
render_board_images | Render the bare board as <name>_PCB-Image-TOP / -BOT (SVG or PNG) and store them in a draft project | Write | |
export_panel_fabrication | Write the panel as <name>_PCB-Data-Panel.zip and <name>_Panel-Image-TOP.png and store them in a draft project | Write |
Sending files
Assistants copy long pasted text and base64 unreliably, so a ZIP, PDF or STEP
pasted into a tool call can arrive corrupt. create_upload_url returns a link
and a ready curl command: the assistant sends the file from disk with an
HTTP PUT, then passes the returned upload_id to import_archive,
upload_project_file, upload_project_document, upload_project_model or
upload_project_render instead of the file contents. An upload belongs to
one draft project, takes files up to 10 MB (gzip a larger STEP model first),
can be used for 15 minutes and is deleted once it is stored. Assistants
without a shell (a chat app with no file access) can still paste small text
files.
Customer data packages
import_archive expands a ZIP on the server and stores each file the way the
Files import does: Gerber and drill files by name (extensionless ones by
content), pick-and-place files (CSV, TXT, XLS, XLSX; a file with both sides
becomes PnP Top + Bot), BOM files, PDFs as documents and the STEP file as
the 3D model. System files (__MACOSX, .DS_Store, Thumbs.db), Altium
drill reports and unrecognised files are skipped and listed with a reason.
ODB++ archives are converted in the browser only: drop them on the Files
tab instead.
analyze_project reads the stored files and returns the numbers a quote
needs. The board is the smallest closed outline contour that holds the
placed parts, so round boards, boards in a panel frame and outline layers
that also carry a title block are measured correctly; the panel frame is
reported separately. Copper is reported as the copper files present:
assembly data often leaves inner layers out, so confirm the layer count from
the fabrication spec. Pick-and-place rows without a BOM line count as not
fitted. Every count says which evidence it used (a THT pick-and-place file, a
mount column, the BOM type or the package name; the BOM's SMD class, the
package library or the package name), and fallbacks appear as warnings, so
check warnings and the per-package table before you quote. The fine-pitch
class holds parts with a lead pitch of 0.5 mm or less and leadless
bottom-terminated packages (QFN, DFN, LGA), as the ERP buckets them.
The analysis also returns the assembly processes (electrical test, coating
and its sides, inspection, soldering, depanelization) as the ERP Assembly
Specification checkboxes: what the Assembly tab declares, else what the
data suggests. A soldering process that is off counts no components. With
variant (its item code or id) the analysis is that assembly variant's: its
BOM and DNP set, and the process settings it sets itself on top of the
project's. To change those, call update_project_settings with variant and
{ "process_overrides": { "processes": { "electricalTest": true }, "coating": { "method": "elpeguard", "sides": "both" } } }; leave a setting out to follow
the project.
Board images
render_board_images draws the bare board from the stored Gerber and drill
files the way Export Image draws the realistic board without
components: solder mask, surface finish and legend in the colours of the
PCB tab (default green, ENIG, white), holes cut out, the bottom seen from
below. It returns one SVG per side (<name>_PCB-Image-TOP.svg,
<name>_PCB-Image-BOT.svg) with its size in millimetres, its SHA-256 and a
15-minute download link, and keeps a copy with the project. The project needs
an Outline (or Keep-Out) layer and copper on each side you ask for; ask for
sides: ["top"] on a single-sided board. Ask for format: "png" for a bitmap
(12 px/mm, at most 6000 px on the longest side). An SVG that would exceed the
10 MB storage limit, such as a very large board or a whole panel imported as
one board, is stored as PNG instead and the result says so in warnings.
Production panel
update_panel with preset: "aa-en-034" sets the Newmatik standard panel
(see Panel) for the board size
you pass as board_width_mm / board_height_mm (the board as drawn, e.g.
from analyze_project), or the PCB data's sizeX / sizeY. label_text
becomes the panel label; max_panel_width_mm (default 150) decides how many
boards fit. A panel object in the same call is applied on top of the
preset.
export_panel_fabrication then writes what Export Panel Gerber and
Export Panel Image for PCB Specification write in the viewer:
<name>_PCB-Data-Panel.zip and <name>_Panel-Image-TOP.png (add
image_sides: ["top", "bottom"] for the mirrored bottom view). Both are stored
with the project and returned as 15-minute download links with their SHA-256,
together with the panel size, board count, label and the fiducial and tooling
hole positions in millimetres from the panel's bottom-left corner. Name the
project with the item code: the files carry the project name.
Safety model
- Your permissions, nothing more. The server acts as you, through the same Row Level Security rules as the web app. It has no administrator access of its own.
- Confirmation for risky changes. Deleting projects, files or documents, inviting, changing or removing team members, and setting an auto-join domain all need an explicit confirmation, and assistants are told to ask you first.
- Approved projects are frozen. Files, documents and settings change
only while a project is in draft. Workflow steps (including approve) need
no confirmation because they are reversible: the approver or an admin
reopens an approved project with
reopen, an admin withrevert_to_draft. - Limits per call. Long lists are paged at 100 to 500 rows per call;
uploads are limited to 10 MB (3D models to 10 MB compressed) and archives
for
import_archiveto 25 MB, 2,000 entries and 256 MB expanded;set_bomtakes up to 5,000 lines,mark_notifications_readup to 500 ids, and a message up to 50 mentions. - Short-lived links. Download links for 3D models, renders, board images
and generated PDFs expire after 15 minutes. An upload from
create_upload_urlis accepted for 15 minutes. Tokens, secrets and other teams' data are never returned. - Every change is attributable. Writes are recorded with your account and the connected app.
- Rate limits. There is no separate per-connection quota yet; the limits of Gerbtrace's hosting apply, and Newmatik may revoke a connection that overloads the service.
Revoke access
Open Profile → Connected apps and choose Revoke next to the app. Revoking immediately invalidates the app's tokens; the app has to ask for your consent again to reconnect. Removing the server in the assistant itself does not revoke the grant, so revoke it in Gerbtrace too.
Technical details
- Transport: Streamable HTTP, stateless; every request gets one JSON
response, and
GETfor an event stream answers 405. - Protocol versions: 2025-11-25, 2025-06-18 and 2025-03-26.
- Authorization: OAuth 2.1 with PKCE and dynamic client registration.
Protected-resource metadata is at
https://www.gerbtrace.com/.well-known/oauth-protected-resource/mcp; the authorization server is Gerbtrace's Supabase Auth.
Support
Questions or problems: software@newmatik.com.
For developers
The server lives in supabase/functions/mcp/ and reuses the web app's Row
Level Security. The web Worker relays https://www.gerbtrace.com/mcp and the
metadata URL to the Edge Function (server/routes/mcp.ts). Work that needs
the app's parsers or package libraries runs on the Worker with the caller's
token: generate_assembly_documentation, import_archive,
analyze_project and render_board_images call
/api/projects/:id/assembly-documentation, /api/projects/:id/import-archive,
/api/projects/:id/analysis and /api/projects/:id/board-images (ADR-013,
ADR-014).