Collaboration

MCP server

Connect Claude, ChatGPT, Codex, Cursor, VS Code or Moth to Gerbtrace through the Model Context Protocol, with your own permissions.

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).

AssistantHow 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 Codeclaude 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.
ChatGPTSettings → Apps → Advanced settings, turn on Developer mode, then Create app with the URL and OAuth authentication.
Codexcodex mcp add gerbtrace --url https://www.gerbtrace.com/mcp, then codex mcp login gerbtrace.
CursorAdd "gerbtrace": { "url": "https://www.gerbtrace.com/mcp" } under mcpServers in ~/.cursor/mcp.json.
VS CodeAdd "gerbtrace": { "type": "http", "url": "https://www.gerbtrace.com/mcp" } under servers in .vscode/mcp.json, then start the server from the file.
MothSettings → Integrations → Gerbtrace → Connect.
  1. 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.
  2. 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.ai or chatgpt.com;
    • "an app on this computer" for Claude Code, Codex and other local tools;
    • the full address for anything else, such as cursor://… or vscode://…, 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.
  3. 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.
  4. 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.

ToolWhat it doesTypeNeeds confirm
whoamiYour profile, teams with roles, and spacesRead
list_teamsYour teams with role and planRead
get_teamTeam details and defaults (never secrets)Read
update_teamTeam name, currency, time format, panel defaults, auto-join domain (admins)WriteOnly for the auto-join domain
create_teamCreate a team with you as adminWrite
list_team_membersMembers, roles and pending invitationsRead
invite_team_memberInvite someone by email (admins); sends the invitation emailWriteYes
update_team_memberChange a member's role or status (admins)WriteYes
remove_team_memberRemove a member from a team (admins)WriteYes
list_spacesSpaces in a teamRead
create_spaceCreate a space (admins)Write
get_team_usageThis month's metered usageRead
list_projectsList and search projectsRead
get_projectProject overview: workflow, people, files, documents, assembly variantsRead
create_projectCreate a projectWrite
update_projectRename or reassign a projectWrite
delete_projectPermanently delete a project and its filesWriteYes
transition_project_workflowSet 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 draftWrite
get_project_settingsProject settings as stored; with variant, also the variant's own process settingsRead
update_project_settingsChange 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_dataPCB parameters: size, stack-up, finish, mask, legend, IPC classWrite
update_panelProduction panel; preset: "aa-en-034" sets the Newmatik standard panel from the board sizeWrite
update_assembly_documentationAssembly 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 tagsWrite
list_project_filesGerber, drill, pick-and-place and BOM filesRead
get_project_fileDownload a file as text, in pagesRead
create_upload_urlA link to send a file from disk (curl -X PUT) for the upload tools and import_archive, so no file bytes go through the chatWrite
upload_project_fileAdd or replace a file in a draft projectWrite
upload_project_documentAttach or replace a PDF in a draft projectWrite
upload_project_modelAttach or replace the STEP 3D modelWrite
upload_project_renderStore a 3D render imageWrite
get_project_model3D model and renders with short-lived download linksRead
delete_project_fileRemove a file from a draft projectWriteYes
delete_project_documentRemove a PDF from a draft projectWriteYes
get_bomBOM lines with manufacturers and DNP; with variant (id or item code), that assembly variant's BOM, DNP set and designators without a placementRead
set_bomReplace the BOM line listWrite
list_project_messagesProject conversationRead
post_project_messagePost a comment, optionally mentioning membersWrite
list_notificationsYour inboxRead
mark_notifications_readMark notifications as readWrite
list_team_packagesCustom SMD and THT packagesRead
get_team_packageOne custom package in fullRead
upsert_team_packageCreate or replace a custom packageWrite
generate_assembly_documentationRender 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 PDFWrite
import_archiveImport 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 inlineWrite
analyze_projectBoard 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 variantRead
render_board_imagesRender the bare board as <name>_PCB-Image-TOP / -BOT (SVG or PNG) and store them in a draft projectWrite
export_panel_fabricationWrite the panel as <name>_PCB-Data-Panel.zip and <name>_Panel-Image-TOP.png and store them in a draft projectWrite

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 with revert_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_archive to 25 MB, 2,000 entries and 256 MB expanded; set_bom takes up to 5,000 lines, mark_notifications_read up 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_url is 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 GET for 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).