API und MCP für Entwickler und KI-Agenten

Services at a glance

Rental equipment catalog (JSON API)

The API returns the same data as the catalog on stagelights.cz, read-only. prWeb is the price shown on the website: 1 unit for 1–2 days incl. VAT; longer rentals get the discounts of the price list. Availability on your dates is confirmed by the rental team.

• /api/catalog/list – search and listing with filters (q, category, manufacturer, sort = default, price, name, manufacturer, power, weight, dmx; dir, offset, limit)
• /api/catalog/product?slug=… or ?id=… – product detail
• /api/catalog/lookup?needles=… – lookup by names (tolerant to case and punctuation)
• /api/catalog/by-ids?ids=LEDFLATPAR,JBLEON612 – products by ID
• /api/catalog/status and /api/catalog/bootstrap – catalog status, categories and settings

Choose the language with lang=en|de|es (Czech is the default). The same API for the fixture library runs on gdtf-lights.com (English by default, no prices).

MCP server (Model Context Protocol)

A remote MCP server for AI assistants and agents runs at https://gdtf-lights.com/mcp (add ?lang=cs|de|es for another catalog language). It uses stateless Streamable HTTP with no login: send JSON-RPC 2.0 messages with POST; GET returns 405. Connect it in any MCP client that supports a remote HTTP server.

Tools:

• search_fixtures, get_fixture, get_gdtf_download, list_categories – fixture search, detail with all DMX modes and a link to the GDTF file
• match_dmx_channels – finds a fixture and its DMX mode from a channel list
• prepare_mvr_export – checks fixtures, counts and modes and returns a job for the generator and a link to the MVR export page
• generate_mvr and get_mvr_job – create the MVR file and return a download link (the only tool that creates anything)
• list_layouts, list_scene_templates, list_visualizers – layouts, scene templates and program profiles

MVR 3D scene generator

The public API creates the same file as generate_mvr: POST to https://gdtf-lights.com/mvr-generate.php with the job from prepare_mvr_export as the JSON body. GDTF files come from the catalog; your own can be added as the multipart field gdtf[]. The response carries download_url, report_url and expires: download within 2 hours (scenes over 50 MB within 30 minutes). Lists of programs and layouts are available with GET, e.g. ?action=visualizers. For people, the same generator is on the MVR export page.

DMX → GDTF (Fixture Finder)

Finding a fixture by its DMX channels has its own API (https://gdtf-lights.com/dmx-to-gdtf, POST with a channels field) and the MCP tool match_dmx_channels; a separate MCP server with only this tool runs at https://gdtf-lights.com/mcp/dmx-to-gdtf. Details and examples are next to the tool: gdtf-lights.com/dmx-to-gdtf#api.

Examples

curl -s 'https://stagelights.cz/api/catalog/list?q=led+par&sort=price&dir=asc&limit=5'

curl -s https://gdtf-lights.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

curl -s 'https://gdtf-lights.com/mvr-generate.php?action=visualizers'

Limits and errors

• Catalog API and MCP: 10 requests per second per IP address (bursts up to 60).
• MVR generation (API and generate_mvr together): 2,000 per day and 10 per minute per IP address.
• DMX → GDTF (API and match_dmx_channels): 20,000 per day and 300 per minute per IP address; for all clients together 500 per minute, 10,000 per hour and at most 3 searches at a time.
• Errors are machine-readable with a code field (e.g. rate_day, rate_minute, busy). 429 and 503 also carry Retry-After; wait that long. Daily limits reset at midnight UTC.
• Usage is counted in aggregate, without IP addresses.

For AI agents on the website

• Rules and price list for AI: llms.txt and llms-full.txt; machine description: openapi.json (OpenAPI 3.1, API catalog per RFC 9727 at /.well-known/api-catalog).
• Markdown versions of pages: index.md, navod.md, akce.md (or the header Accept: text/markdown).
• In-browser tools (WebMCP, a W3C proposal) as a prototype with ?webmcp=1: equipment search, list, dates, price, AI visualization and preparing an inquiry. Sending an inquiry and generating an image are always confirmed by the visitor.

Rules

An inquiry sent through the website or the AI chat is not a confirmed booking; availability and price are confirmed by the rental team. AI visualizations (images and videos) are generated only on the website with the visitor’s consent; the API does not offer them. For integration questions, use the contact page.