MCP Server Quickstart¶

ZapTrace MCP enables LLMs (Claude, Copilot, Codex, Gemini) to design PCBs through the Model Context Protocol. The default expert surface exposes 96 tools: 93 design tools plus 3 session-administration tools.

Protocol compatibility¶

ZapTrace uses MCP protocol 2026-07-28 as the current protocol path. Modern clients may call server/discover but do not perform the legacy initialize / initialized handshake, and modern HTTP requests do not use Mcp-Session-Id. The MCP protocol layer is stateless; client identity, capabilities, and protocol version travel with each modern request.

ZapTrace can still maintain design state. session_id is a ZapTrace application-level handle returned by session_create and passed explicitly to tools that need isolated design state. It is not an MCP transport session and does not require sticky routing or a transport session header.

Existing legacy MCP clients remain supported through the upstream SDK compatibility path. ZapTrace tests the same server surface in both 2026-07-28 and legacy client modes. Protocol compatibility is software interoperability evidence; it does not prove electrical correctness, fabrication readiness, or hardware safety.

Task-oriented tool surfaces¶

ZapTrace defaults to the expert MCP tool surface, which preserves the complete registry. For common workflows, set ZAPTRACE_MCP_TOOL_SURFACE before server startup to reduce tools/list to a deterministic task-oriented view:

inspect — read-only design, library, rule/result, analysis, audit, and rendering tools.
design — parsing, synthesis, placement/routing, component, footprint, calculator, and transaction tools.
verify — ERC/DRC, simulation, engineering review, proof, and evidence-inspection tools.
repair — patching, bounded design mutation, re-verification, rollback, and transaction tools.
release — sign-off checks, proof, manufacturing/export, and release-evidence tools.

For example:

ZAPTRACE_MCP_TOOL_SURFACE=verify uv run zaptrace-mcp

The profile changes discovery/visibility only. It does not grant new capabilities, bypass capability checks or OAuth scopes, bypass object authorization, weaken transaction approval, or move ZapTrace application state into MCP transport state. Session administration remains available in every surface. Use expert when a client genuinely needs the full low-level registry.

1. Starting the Server¶

# Option A: Install verified release from PyPI (recommended)
uv pip install zaptrace-eda

# Option B: Install from source (pre-1.0 development)
git clone https://github.com/oaslananka/zaptrace.git && cd zaptrace && uv sync --all-extras

# Start MCP server (stdio transport)
uv run zaptrace-mcp

# Optional authenticated loopback HTTP deployment uses the separate entry point.
# See docs/mcp-http-deployment.md before enabling it.
uv run zaptrace-mcp-http

2. Claude Desktop Configuration¶

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "zaptrace": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/zaptrace", "zaptrace-mcp"],
      "env": {}
    }
  }
}

3. Testing with MCP Inspector¶

npx @modelcontextprotocol/inspector uv run --project /absolute/path/to/zaptrace zaptrace-mcp

Opens browser UI to test individual tools.

4. Available Tools¶

Tool	Description
`design_parse_file`	Parse a design YAML file
`design_parse_str`	Parse a YAML string
`design_inspect`	Inspect a parsed design
`design_list_nets`	List all nets in a design
`synthesize_design`	Synthesize from intent
`erc_validate`	Run electrical rule checks
`drc_run`	Run design rule checks
`place_components`	Auto-place all components
`route_nets`	Route all nets (MST)
`design_route_smart`	Net-class-aware smart routing
`export_gerber`	Generate Gerber RS-274X files
`export_bom_csv`	Generate BOM as CSV
`board_update`	Update board configuration
`component_add`	Add a component
`footprint_generate`	Generate parametric footprint
`proof_run`	Run a Proof Pack
96 tools total	93 design tools plus `session_create`, `session_list`, and `session_destroy`

Full reference: docs/mcp/tools-reference.md

For Claude Code plugin packaging, first-phase skills, and marketplace activation gates, see docs/agent-plugin-publication.md.

5. Example Workflow¶

1. design_parse_file("project.yaml")         → load design
2. design_inspect("my_design")               → see what's there
3. place_components("my_design")             → auto-place all components
4. design_route_smart("my_design")           → route with net-class awareness
5. drc_run("my_design")                      → check for violations
6. export_gerber("my_design", "output/")     → generate Gerber files