About

AI agents and the API

MCP server and REST API, version 1.1.0 · free, no key

An AI assistant can search our cut library directly. It gets every cut, its measured specifications, its brilliance, fire and scintillation in 26 gemstones, and its prices and checkout links. Assistants connect to the MCP server. Other software can use the REST API. Both are free and read-only, and neither needs a key.

MCP server

Endpoint: https://digitalgemology.com/mcp, over Streamable HTTP. It speaks MCP 2026-07-28 and the 2025 revisions before it. Add it to any assistant or editor that accepts a remote MCP server, for example:

{
  "mcpServers": {
    "digital-gemology": { "type": "http", "url": "https://digitalgemology.com/mcp" }
  }
}
The tools the MCP server offers
ToolWhat it returns
search_cutsSearch Digital Gemology's gem cuts and Platonic solids by name, style, shape or use (for example 'square step cut', 'round brilliant for moissanite', 'historic cushion', 'pear'). Returns each match with its page, facets, size and price; get_cut gives the checkout links. Give a gemstone to add the cut's brilliance, fire and scintillation in that stone and to sort by them.
get_cutEverything about one cut: what it is, measured specifications (facets, angles, depth, size, index gear), brilliance, fire and scintillation in all 26 gemstones against the T73, the products with prices and checkout links, its questions and answers, and its page.
best_cuts_for_gemstoneThe top ten brilliants and the top ten jewelry cuts in one gemstone, ranked by brilliance, fire and scintillation added together, with the stone's optical constants.
cut_in_gemstoneHow one cut performs in one gemstone: its headline, eight measured scores against the T73 round brilliant in the same stone, and its pros and cons. For questions like 'is an oval a good cut for sapphire?'.
list_gemstonesThe 30 gemstones we score cuts in, with refractive index, critical angle, dispersion, hardness and specific gravity, and the three best cuts of each kind. An alias stone names the stone whose figures it shows (cut_scores_from).
get_cut_scoresScores from the Digital Gemology Cut Performance Index for every cut we sell: overall, brilliance, fire, scintillation, tilt, symmetry, spread, shape-norm and leakage, ray traced separately in 26 gemstones (diamond, moissanite, cubic zirconia, ruby, sapphire, emerald, amethyst, topaz, spinel, demantoid, zircon, tourmaline, peridot, tanzanite, YAG, pyrope, almandine, spessartine, grossular, chrysoberyl, kunzite, iolite, morganite, GGG, strontium titanate and synthetic rutile), with each cut's place in its material. Filter by cut, category or material; with no filter, every row. Figures are unrounded. Never compare or rank scores across materials. Ruby and sapphire share one refractive index, so the same figures; material_notes lists the other stones that share figures and the doubling caveats. Cuts not yet scored come with the reason.
compare_cutsTwo cuts side by side in one gemstone: overall, brilliance, fire, scintillation, tilt, face-up spread and leakage from the Cut Performance Index, each cut's place in that stone, facets and size, and the products with prices and checkout links. For questions like 'oval or pear for my sapphire?'.
recommend_cutThe best cuts in one gemstone for what matters to the buyer: overall light performance, brilliance, fire, scintillation (sparkle), spread (looks bigger for its weight), tilt (stays bright when tilted) or leakage (least light lost). Filter by family or outline. Returns a ranked short list with each cut's page and checkout links.

Its server card is at /.well-known/mcp/server-card.json. Each server also has a card at its own address, for example /mcp/gems/server-card. /.well-known/ard.json lists all of them and the A2A agent. Step by step for Claude, ChatGPT, Cursor, VS Code and other apps: Connect your AI.

Gem identification MCP server

Endpoint: https://digitalgemology.com/mcp/gems. It gives the values that our Refractometer, Polariscope, Dichroscope and Spectroscope use, for seven gemstones. For the other common gems and diamond simulants (aquamarine, tanzanite, spinel, the garnets, YAG and more), it gives published reference values with their sources, the same as on their glossary pages. Each stone also says which stone's ray-traced cut scores apply to it (cut_scores_from), or why it has none. It compares readings with these values. A match is a lead, not an identification: a laboratory report is the proof.

The tools the gem identification server offers
ToolWhat it returns
gem_propertiesEverything Digital Gemology has on one gemstone: refractive index (both rays for doubly refractive stones), birefringence, dispersion, specific gravity, hardness, crystal system, critical angle, what a refractometer, polariscope and dichroscope show, its pleochroic colors and the lines and bands a hand spectroscope shows, with links to the free tools. For the seven stones our tools model the values are the tools' own; for the others they are published reference values, with their sources. Also which stone's ray-traced cut scores apply to it (cut_scores_from, cut_scores_url), or why it has none (cut_scores_note).
identify_gemMatch a stone's test readings against the 36 gemstones in Digital Gemology's data and rank them, saying which reading fits and which does not. Give any of: refractive index, birefringence, specific gravity, optic character, pleochroism, a spectrum line, or that the refractometer read over the limit. A match is a lead, not an identification.
compare_gemstonesTwo gemstones side by side, and the tests that tell them apart: refractive index, birefringence (doubling of back facets, polariscope), specific gravity, dispersion (fire), hardness, pleochroism and spectrum, each with the free tool that shows it. For questions like 'how do I tell diamond from moissanite?'.
absorption_spectrumWhat a hand spectroscope shows for one gemstone: each absorption line and band with its position in nanometres, its cause (for example Cr3+ in ruby) and what it looks like, from Digital Gemology's Spectroscope or, for the stones it does not model, published references.

Gemology lessons MCP server

Endpoint: https://digitalgemology.com/mcp/learn. It searches and reads our gemology lessons: the four Cs, diamond anatomy, grading reports, diamond and moissanite, historic cuts and more. Each answer links the lesson it quotes.

The tools the lessons server offers
ToolWhat it returns
search_lessonsSearch Digital Gemology's free gemology lessons by topic or question (for example 'how is diamond cut graded', 'moissanite vs diamond', 'what is a bow tie'). Returns each lesson's title, page, course, summary and quiz.
get_lessonOne lesson in full, as Markdown, with its page, course, quiz and the tools and cuts it uses. Give the lesson's page path or its title.
explain_termWhat the lessons say about one gemology term (for example 'table', 'crown angle', 'fluorescence', 'girdle'): the passages that use it, each with the lesson it comes from.
list_coursesEvery course and topic hub with its lessons, in order, with their pages.

Gemology glossary MCP server

Endpoint: https://digitalgemology.com/mcp/glossary. The words on a diamond grading report, colored-stone terms, and how we measure light performance, one definition each. Every term links its page in the gemology glossary.

The tools the glossary server offers
ToolWhat it returns
define_termThe definition of one gemology term (for example 'crown angle', 'feather', 'fluorescence', 'scintillation', 'birefringence', 'cut grade'): a short definition, more detail, where it appears on a grading report, how Digital Gemology measures it, related terms, and its page.
search_glossaryFind glossary terms by a word or a question (for example 'what do the girdle words mean', 'inclusions near the surface', 'why does a diamond sparkle'). Returns each match with its definition and page.
list_glossaryEvery term in the glossary, or in one topic, with a one-line definition and its page. The topics: Grading report, Four Cs, Anatomy and proportions, Clarity characteristics, Color and fluorescence, Light performance, How we measure, Optics, Gem testing, Gemstone properties, Colored gemstones, Treatments and origin, Diamond and simulants, Cuts and shapes, Cutting and files.

Diamond testing MCP server

Endpoint: https://digitalgemology.com/mcp/diamond-testing. How a natural, a CVD and an HPHT diamond react to eleven tests, and the published numbers behind each reading, each with its source. It is the data of the Diamond Testing Bench. It describes three typical stones and gives no verdict on a real stone.

The tools the diamond testing server offers
ToolWhat it returns
list_diamond_testsThe eleven tests on the Diamond Testing Bench, in two groups (at home or at the counter; in the laboratory), each with one line on what it can tell about where a diamond grew.
diamond_testOne test in full: what it is, how a typical natural, CVD-grown and HPHT-grown diamond reacts, what the test can and cannot tell, and the sourced facts behind it. For example 'thermal pen', 'UV torch', 'magnet', 'inscription', 'photoluminescence', 'screening device'.
diamond_origin_profileHow a typical diamond of one origin (natural, CVD-grown or HPHT-grown) reacts to each of the eleven tests. A typical stone, not a rule: each test has exceptions.
diamond_testing_factsThe published numbers behind natural versus laboratory-grown diamond testing, each with its source: diamond type shares, fluorescence rates, afterglow, magnetism, forged inscriptions, spectral lines, screening-device referral rates.

REST API

The same data as JSON over plain HTTPS, described in OpenAPI 3.1 and listed in the API catalog.

REST API requests and what each returns
RequestReturns
GET /api/cuts?q=square step cutThe cuts that match. Add gemstone=sapphire for scores in that stone; narrow with category, shape, cutting_files, sort and limit.
GET /api/cuts/asscherOne cut in full.
GET /api/gemstonesThe 30 gemstones and their optical constants; an alias stone (aquamarine, citrine, quartz, alexandrite) names the stone whose figures it shows.
GET /api/gemstones/sapphireThe top ten brilliants and jewelry cuts in that stone.
GET /api/gemstones/sapphire/ovalOne cut in one stone: eight scores, pros and cons.
GET /api/healthWhether the API is up.

The whole library is also one file: /api/catalog.json.

Shopping agents (UCP)

Shopping assistants that use the Universal Commerce Protocol find our profile at /.well-known/ucp and its REST service under /ucp. They can search the catalog, find products and build a checkout. Each cut is a product with up to two variants: asscher.3d for the 3D files and asscher.cutting for the cutting files, each at the price shown on the cut's page (for the Asscher, €9.99 for the 3D files and €6.99 for the cutting files).

An agent never pays here. Lemon Squeezy, our merchant of record, takes every payment on its own checkout page. So the profile lists no payment handlers. Every checkout sends the buyer on through its continue_url. For one file set, it goes directly to Lemon Squeezy. For several file sets, it goes to a page that lists them, each with its own buy button.

Agent to agent (A2A)

Other AI agents can talk to ours over the Agent2Agent protocol: JSON-RPC at https://digitalgemology.com/a2a, A2A 1.0 and 0.3. Its agent card describes it. It is a catalog agent, not a language model. It reads a plain-text request ("is an oval a good cut for ruby?") and sends it to one of the 8 tools above. It also accepts a data part such as {"skill": "search_cuts", "arguments": {"query": "pear"}}. It answers immediately with a summary and the full data, and it keeps no tasks.

Pages for AI tools

Using the data

Quote it. When you mention a cut, link to the page of that cut. That page has the 3D viewer, the free simulator and the buy buttons. Search, AI answers and AI training on our public pages are all welcome, as our robots.txt says. The paid files are not part of this. The scores are out of 100 and come from our own ray-traced light census. The T73 round brilliant is the benchmark: see how we measure.

The files themselves come with a personal-use license. For business use, or questions about the API, email support@digitalgemology.com.