# ProvenMetal — agent ordering setup

ProvenMetal builds and ships PCBs. This page sets up the ProvenMetal MCP server
so an AI coding agent can quote a board from its KiCad fabrication outputs, clear
sourcing/DFM blockers, and draft an order. Every order is a DRAFT — a human
approves the final placement. Follow the steps in order.

## 1. Prerequisites
- A ProvenMetal account: https://central.provenmetal.com
- An ordering API key: sign in, open Settings, and generate a key. It starts
  with "pm_live_". Treat it as a secret. If the user hasn't got one, ask them.
- Python 3.11+ on the machine running the agent (the MCP server runs locally
  over stdio).

## 2. Add the MCP server
Add ProvenMetal to the agent's MCP client config (Claude Code's mcp.json,
Cursor's MCP settings, or any MCP-capable client) and paste in the user's key:

{
  "mcpServers": {
    "provenmetal": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "PROVENMETAL_API_URL": "https://api.provenmetal.com",
        "PROVENMETAL_API_KEY": "pm_live_your_key_here"
      }
    }
  }
}

Restart the agent so it loads the server. Four "provenmetal" tools should appear.

## 3. Tools
- quote_pcb(gerbers_path, bom_path, qty, cpl_path?) — price + lead-time range
  from KiCad fab outputs. Returns the assumptions used, a blockers list, DFM
  recommendations, and per-line sourcing. Save the returned quote_id.
- revise_quote(quote_id, resolutions?, assumptions?) — apply a blocker fix or an
  assumption change; returns the updated quote. Repeat until blockers is empty.
- create_draft_order(quote_id, contact_email?) — turn a clean quote into a DRAFT
  order. Returns a confirmation_url. It never places the order.
- check_order_status(order_id) — draft -> confirmed -> in production -> shipped.

## 4. Ordering workflow
1. Locate the KiCad fab outputs: the gerber .zip, the BOM .csv, and the
   placement/CPL .csv. Ask the user if you can't find them.
2. Call quote_pcb with those paths and the build quantity. Save the quote_id.
3. Read "blockers". For each, apply the fix from its suggested_resolutions with
   revise_quote. Repeat until blockers is empty.
4. Read "recommendations" and apply the design-for-manufacturability fixes that
   make sense (e.g. swap an end-of-life or long-lead part). Hand board-level
   fixes back to the user for the KiCad design.
5. Call create_draft_order with the quote_id and a contact_email for approval.
6. Report the price range, lead time, and confirmation_url. Do NOT place or
   confirm the order yourself — a human opens that URL to approve it.

## Constraints
- Only overseas (China) fabrication can be instant-quoted right now. Leave
  board_origin at its default; US bare boards are not supported yet and will
  return an error.
- Every order is a draft. Nothing is built until a human approves the
  confirmation_url.

## Links
- Account & API key: https://central.provenmetal.com
- Human-readable overview: https://provenmetal.com/agents
- KiCad plugin (exports gerbers / BOM / CPL): https://provenmetal.com/plugins/kicad
- Help: founders@provenmetal.com