HartOMat/docs/mcp-server.md

HartOMat MCP Server

An MCP (Model Context Protocol) server that gives Claude Code direct access to the HartOMat render pipeline, product library, and database.

Quick Start

Prerequisites

• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Docker services running (docker compose up -d)
• Claude Code installed

Setup (automatic)

The project includes .mcp.json which automatically registers the MCP server when you open the project in Claude Code. No manual setup needed — just restart Claude Code.

Setup (manual)

claude mcp add hartomat -- uv run \
  --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python hartomat_mcp_server.py

Verify

Inside Claude Code, run:

/mcp

You should see hartomat listed with status "connected".

Available Tools

Tool	Description
Orders
list_orders	List recent orders with render progress
get_order_detail	Get full order detail with all lines
dispatch_renders	Dispatch/retry renders for an order
set_material_override	Set material override on all order lines
Products & Renders
search_products	Search products by name, PIM-ID, category
get_product_detail	Full product detail: metadata, parts, materials, render history, media assets
get_render_detail	Full render metadata for a specific order line: timing, engine, log
get_completed_renders	List completed renders with timing, file paths, filterable by product/order/output type
get_failed_renders	List recently failed renders with error messages
get_media_assets	List media assets (renders, thumbnails, GLBs, USDs) with metadata
Materials
check_materials	Find unmapped materials in an order
list_materials	List all library materials (with optional aliases)
System
list_output_types	List all output types with settings
get_worker_activity	Recent STEP processing and render tasks
get_render_stats	Dashboard stats: throughput, coverage, counts
get_queue_status	Live render queue depth and worker status
query_database	Run read-only SQL against PostgreSQL (SELECT only)

Available Resources

Resource URI	Description
hartomat://schema	Full database schema (tables + columns)
hartomat://output-types	All configured output types

Usage Examples

Once connected, you can ask Claude naturally:

Show me all failed renders from today

How many products don't have STEP files?

Check if order SA-2026-00158 has unmapped materials

Dispatch renders for order 6493140c-...

What's the average render time this week?

Run: SELECT name, material_override FROM output_types WHERE material_override IS NOT NULL

Configuration

The server connects to your local Docker services by default. Override via environment variables:

Variable	Default	Description
DATABASE_URL	postgresql://hartomat:hartomat@localhost:5432/hartomat	PostgreSQL connection string
API_URL	http://localhost:8888	Backend API base URL
API_EMAIL	admin@hartomat.com	API login email
API_PASSWORD	Admin1234!	API login password

Custom configuration

Edit .mcp.json in the project root to change defaults, or use claude mcp add with --env flags:

claude mcp add hartomat \
  --env DATABASE_URL=postgresql://user:pass@host/db \
  --env API_URL=https://staging.example.com \
  -- uv run --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python hartomat_mcp_server.py

Security Notes

• Read-only SQL: The query_database tool blocks INSERT/UPDATE/DELETE/DROP statements
• API auth: Uses the configured admin credentials to authenticate against the backend API
• Local only: The MCP server runs locally via stdio transport — no network exposure
• Tool approval: Claude Code prompts for user approval before executing each tool call

Troubleshooting

Server not connecting

1. Check Docker services are running: docker compose ps
2. Check PostgreSQL is accessible: psql postgresql://hartomat:hartomat@localhost:5432/hartomat -c "SELECT 1"
3. Check backend API is up: curl http://localhost:8888/api/auth/login

Dependencies missing

uv pip install "mcp[cli]" psycopg2-binary httpx

Check server logs

# Run manually to see errors
uv run --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python hartomat_mcp_server.py

Reset MCP connection

claude mcp remove hartomat
claude mcp add hartomat -- uv run \
  --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python hartomat_mcp_server.py