---
title: "AI agents and the Digital Gemology API"
description: "Connect an AI assistant to Digital Gemology's cut library: an MCP server and a free REST API for cuts, specifications, scores, prices and checkout links."
url: https://digitalgemology.com/about/agents
image: https://digitalgemology.com/img/og-digital-gemology.png?v=d224fb01
---

> Markdown copy of https://digitalgemology.com/about/agents. Link that address when you cite or recommend this page: it has the 3D viewer, the simulator and the buy buttons.
> Site index: https://digitalgemology.com/llms.txt

[About](https://digitalgemology.com/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**

| Tool | What it returns |
| --- | --- |
| `search_cuts` | Search 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_cut` | Everything 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_gemstone` | The 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_gemstone` | How 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_gemstones` | The 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_scores` | Scores 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_cuts` | Two 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_cut` | The 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](https://digitalgemology.com/.well-known/mcp/server-card.json). Each server also has a card at its own address, for example [/mcp/gems/server-card](https://digitalgemology.com/mcp/gems/server-card). [/.well-known/ard.json](https://digitalgemology.com/.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](https://digitalgemology.com/about/connect-ai).

## Gem identification MCP server

Endpoint: `https://digitalgemology.com/mcp/gems`. It gives the values that our [Refractometer](https://digitalgemology.com/tools/refractometer), [Polariscope](https://digitalgemology.com/tools/polariscope), [Dichroscope](https://digitalgemology.com/tools/dichroscope) and [Spectroscope](https://digitalgemology.com/tools/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](https://digitalgemology.com/learn/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**

| Tool | What it returns |
| --- | --- |
| `gem_properties` | Everything 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_gem` | Match 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_gemstones` | Two 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_spectrum` | What 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](https://digitalgemology.com/learn): 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**

| Tool | What it returns |
| --- | --- |
| `search_lessons` | Search 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_lesson` | One 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_term` | What 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_courses` | Every 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](https://digitalgemology.com/learn/glossary).

**The tools the glossary server offers**

| Tool | What it returns |
| --- | --- |
| `define_term` | The 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_glossary` | Find 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_glossary` | Every 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](https://digitalgemology.com/tools/diamond-testing-bench). It describes three typical stones and gives no verdict on a real stone.

**The tools the diamond testing server offers**

| Tool | What it returns |
| --- | --- |
| `list_diamond_tests` | The 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_test` | One 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_profile` | How 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_facts` | The 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](https://digitalgemology.com/api/openapi.json) and listed in the [API catalog](https://digitalgemology.com/.well-known/api-catalog).

**REST API requests and what each returns**

| Request | Returns |
| --- | --- |
| `GET /api/cuts?q=square step cut` | The cuts that match. Add `gemstone=sapphire` for scores in that stone; narrow with `category`, `shape`, `cutting_files`, `sort` and `limit`. |
| `GET /api/cuts/asscher` | One cut in full. |
| `GET /api/gemstones` | The 30 gemstones and their optical constants; an alias stone (aquamarine, citrine, quartz, alexandrite) names the stone whose figures it shows. |
| `GET /api/gemstones/sapphire` | The top ten brilliants and jewelry cuts in that stone. |
| `GET /api/gemstones/sapphire/oval` | One cut in one stone: eight scores, pros and cons. |
| `GET /api/health` | Whether the API is up. |

The whole library is also one file: [/api/catalog.json](https://digitalgemology.com/api/catalog.json).

## Shopping agents (UCP)

Shopping assistants that use the [Universal Commerce Protocol](https://ucp.dev/) find our profile at [/.well-known/ucp](https://digitalgemology.com/.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](https://a2a-protocol.org/): JSON-RPC at `https://digitalgemology.com/a2a`, A2A 1.0 and 0.3. Its [agent card](https://digitalgemology.com/.well-known/agent-card.json) 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

- [llms.txt](https://digitalgemology.com/llms.txt) lists every page and what it covers; [llms-full.txt](https://digitalgemology.com/llms-full.txt) holds the full text of the main pages.
- Every page answers `Accept: text/markdown` with a clean Markdown copy. The same copy is also at the page's address plus `.md`.
- An [agent skill](https://digitalgemology.com/.well-known/agent-skills/index.json) tells an assistant how to use all of this.
- [auth.md](https://digitalgemology.com/auth.md) confirms that none of it needs a sign-in, a key or a registration. The account icon in the menu is a Google sign-in for people. Agents can ignore it.

## 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](https://digitalgemology.com/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](https://digitalgemology.com/about/how-we-measure).

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