---
title: Agent quickstart
description: Connect the factory as a tool, get a quote, place an order, verify ROI — end to end.
date: 2026-07-17
audience: technical
category: reference
---
The factory is an MCP server. Everything below is also discoverable at /.well-known/mcp.json, /llms.txt and /facts.json.

## Connect (stdio)
Add tng-factory to your MCP config: command `fastmcp`, args `run src/tng/mcp/server.py`. Start every session with **get_capabilities** — it is the machine-readable evaluation surface (materials, limits, pricing basis, locales, sandbox flag).

## Identify yourself
Send your key in the `X-API-Key` header. Tools that touch your account — **get_metrics**, **get_credit_balance** — read the key and never take an account name as an argument, so a key is the only way to reach your own data. Without one they answer `identity_required` and point at the page that issues keys.

## Evaluate before auth
POST /v1/try/review-stand needs no key: send line1/line2 (and optional logo), poll /v1/tasks/{id} or stream /v1/tasks/{id}/stream (SSE), and you get a preview URL plus a deterministic quote. Rate-limited 10/day/IP.

Generation from an image, a URL or a prompt is free for 3 models a day per visitor. Send your key and the cap does not apply. Over the cap you get `daily_limit_reached` and the page that issues keys — not a bare 429 to retry against.

## Describe a piece in words
`POST /v1/studio/from-words {"words": "a menu holder for my bistro with a QR to the wine list"}` returns a customizer graph, its price and its lead time — about a second, no key, 20 a day per visitor.

The vocabulary is closed and small, so the answer is either a graph you can send straight to `POST /v1/studio/build`, or `{"cannot": "<one sentence>"}`. It refuses rather than approximating: ask for a phone case or a gear and you get the sentence, never a blank plate dressed up as the thing you asked for.

## Take the file
- `GET /preview/{product_id}.stl` — look-grade mesh, free, no key, no email. This is what the 3D viewer loads.
- `GET /files/{product_id}.stl` — the print-grade file. Send `X-API-Key`, or `?email=` an address left via `POST /v1/previews/recall`. Without either it answers `email_required` and names both ways through.

## Buy
- **quote** — machine-readable price for a mesh or product; pass ship_to_country (ISO-2) for regional currency.
- **order_production** — the purchase leg; send your key and the order lands in your metrics, which is what makes re-buying work. Guest orders without a key still go through. Sandbox until checkout keys are live.
- **get_credit_topup_link / get_credit_balance** — the credit buy leg without leaving the tool surface.
- Retries: pass request_id on create tools; retries are safe.

## Operate and re-buy
**get_metrics** (or GET /v1/metrics with X-API-Key) returns your orders, paid spend, objects in the wild, scan totals and credit balance — verify value on evidence, then re-buy.

## Earn
**join_affiliate_program** mints your referral link (20% of every paid referred order, in credits). **publish_listing** puts your model on the marketplace at a 30% creator royalty. Both stack: creation and distribution are paid separately.