GemstoneAI for Agents

Jewelry intelligence for AI assistants.

Understand a piece, explore relevant market evidence, and save it to a collection, from inside the assistant someone already uses.

Connect your assistant Developer reference

https://api.gemstoneaiapp.com/mcp

A rose-cut diamond cluster ring photographed from above on a pale grey ground — Photo: The Metropolitan Museum of Art, Open Access (CC0), object 6863, standing in for a family ring.

One conversation, start to finish

“I inherited this ring. Help me understand it, find comparable pieces, and save what we learn.”

Everything below is a single real run of the four tools on 2026-10-10, quoted from the output. Analysis took 26 seconds; comparables were ready 41 seconds later.

Photos in
Assistants that can pass attached photos send them straight to the tool. Where one cannot, GemstoneAI returns an upload link the person opens on their phone. Public photo links work too. Location data is removed from every photo.
02
A preliminary identification, with its doubts left in
Set low in an oxidized silver halo, the oval center stone has a rose cut with a flat base, low dome, and triangular crown facets. The stones read as old-style diamonds with a faint brown-gray cast, visible internal haze, and softer return than a modern brilliant cut.
Identification
Diamond, status unconfirmed. Also consistent with Cubic Zirconia or Clear Quartz.
As read from the photos
Carat
0.9-1.3 ct (est., center stone)
Cut · Shape
Rose cut · Oval
Setting
Closed-back halo
Stones
1 center + 12 accent
Unknowns
Diamond value depends on confirmation and grading. Treatment and identity can't be confirmed from images, so verify with a lab report before high-value transactions.
Next evidence
- Look for a stamp inside the band or on the clasp (for example 14K, 585, 750, 925, PT950) and photograph it close up.
- A gemologist's in-person test or a lab report (GIA, AGL, Gübelin) is how to confirm Diamond and whether it is natural, lab-grown or treated.
The museum catalogues this ring as gold and diamonds. The photos read as silver, which is common for silver-topped gold of the period, and it is why every metal and stone is labelled as read, not tested.
03
Market evidence, labelled for what it is
- .925 Sterling Silver 1-1/8 Cttw Diamond Cluster Triple Halo Knot Cocktail Ring
  1stDibs · fair match · Stated 1.14-1.19 ct total diamonds and a multi-halo design; a cluster cocktail model rather than an antique rose cut.
  $775
  Asking price
- David Yurman 17mm Albion Prasiolite Sterling Silver Diamond Halo Ring
  eBay · loose match · Completed sale; large prasiolite center and a designer model, so useful mainly as a sterling-silver halo resale floor.
  $549.99
  Realized sale
2 retailer search links were found and left out: a search page is not a comparable. When nothing priced turns up, the answer is “none found”, never a value of zero.
Price context, three numbers that are not the same number
Retail purchase
$1,250 to $2,165
Derived at a 1.85 retail multiple
Private sale
$675 to $1,170
GemstoneAI model estimate
Resale proceeds
$540 to $935
Derived at 0.8; not an offer
When GemstoneAI's own reads disagree about what the stone is, the figures are withheld with the reason, because a value that depends on an unsettled identity is not supported.
Saved, and waiting in the app
Saved only after the person asks. The tool returns collection item 6922 and gemstoneaiapp.com/gem/6922, which opens the same piece in the GemstoneAI app on their phone. Saving twice returns the same item.

What it will not tell you

It is not an appraisal, and it does not establish authenticity, treatment or origin.
It gives no confidence percentages. Uncertainty comes as alternatives, unknowns and the evidence that would settle them.
An asking price is never presented as a sale, and retail is never presented as what an owner would be paid.
It never buys, sells, lists or contacts anyone, and it saves only when asked.
Results are preliminary. For insurance or a sale, get an in-person appraisal.

Connect your assistant

Add the server URL to any client that supports remote MCP servers. Sign in with the email you use in the GemstoneAI app so your collection is the same; new emails get a free account. Each new analysis uses a scan from that account's plan, the same as in the app.

https://api.gemstoneaiapp.com/mcp

Client	Support	How
Claude Code	Planned	`claude mcp add --transport http gemstoneai https://api.gemstoneaiapp.com/mcp`
MCP Inspector	Planned	`npx @modelcontextprotocol/inspector, Streamable HTTP, URL below`
Claude (web, desktop, mobile)	Planned	`Settings, Connectors, Add custom connector, paste the URL`
ChatGPT	Planned	`Plugins, Add custom MCP server, paste the URL (developer mode)`
Cursor, VS Code, other MCP clients	Planned	`Add a remote HTTP server with the URL; sign in when prompted`

Tested means the full journey (photo, analysis, comparables, save, reopen) passed in that client. Planned means it speaks the same standard but has not been through that test yet.

For developers

For collection, resale and estate-inventory assistants. One remote MCP server, four tools, standard OAuth discovery, so any MCP client can connect with nothing but the URL. The Claude Code plugin and the full reference are on GitHub.

analyze_jewelry

Preliminary analysis of 1 to 5 photos of one piece: observations, identification with alternatives, unknowns, next evidence, price context when supported.

Input: photos (attached files) or image_urls (public https), optional idempotency_key. No photos returns an upload link.

Annotations: writes (stores the analysis); not destructive; idempotent; open world

get_jewelry_analysis

Status or completed result. Waits up to about 40 seconds while processing.

Input: analysis_id

Annotations: read-only

find_jewelry_comparables

Photographed market listings and sales with source, link, price, price type, date found and material differences.

Input: analysis_id

Annotations: read-only; open world (third-party listing text)

save_collection_item

Saves the analysed piece to the signed-in person's collection; returns the item id and a link that opens it in the app.

Input: analysis_id

Annotations: writes; not destructive; idempotent

Call it

# After OAuth sign-in (PKCE), every call is one JSON-RPC POST to the server.
import httpx

MCP = "https://api.gemstoneaiapp.com/mcp"
headers = {"Authorization": f"Bearer {access_token}",
           "Accept": "application/json, text/event-stream",
           "MCP-Protocol-Version": "2025-06-18"}

def call(name, arguments):
    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
            "params": {"name": name, "arguments": arguments}}
    return httpx.post(MCP, json=body, headers=headers, timeout=90).json()["result"]["structuredContent"]

a = call("analyze_jewelry", {"image_urls": ["https://example.com/ring.jpg"]})
while a["status"] == "processing":
    a = call("get_jewelry_analysis", {"analysis_id": a["analysis_id"]})
comps = call("find_jewelry_comparables", {"analysis_id": a["analysis_id"]})

What comes back (excerpt of the run above)

{
  "analysis_id": "ana_VKC7cgSFsCRurRxz",
  "status": "completed",
  "identification": {
    "preliminary": "Diamond",
    "status": "unconfirmed",
    "alternatives": [
      "Cubic Zirconia",
      "Clear Quartz"
    ]
  },
  "next_evidence": [
    "Look for a stamp inside the band or on the clasp (for example 14K, 585, 750, 925, PT950) and photograph it close up."
  ],
  "price_context": {
    "status": "available",
    "basis": "model_estimate",
    "private_sale_estimate": {
      "low": 675,
      "high": 1170,
      "currency": "USD"
    },
    "resale_proceeds": {
      "low": 540,
      "high": 935,
      "method": "derived: private-sale estimate x 0.8"
    }
  },
  "result_url": "https://gemstoneaiapp.com/gem/6922"
}

Transport: Streamable HTTP, stateless, JSON responses. Accepts initialize-based clients (2025-03-26 to 2025-11-25) and 2026-07-28 clients.
Authentication: OAuth 2.1 with PKCE (S256). Client ID Metadata Documents or dynamic registration. Tokens are bound to one person and one client; an integration reaches a collection only after its owner signs in and allows it.
Latency: The underlying scan typically takes 20 to 45 seconds. analyze_jewelry waits up to about 40 seconds, then returns processing with a retry interval. Comparables usually follow within a minute.
Limits: Scans come from the signed-in person's GemstoneAI plan. During the pilot there are also daily evaluation caps per account and per integration. Repeating the same photos is not charged twice.

Privacy and use

Photos are used to analyze the piece and are kept with it in the person's GemstoneAI account, like a scan in the app. Location data is stripped. Deleting the piece in the app deletes what any assistant can read.

Access tokens are stored only as hashes and expire after an hour. GemstoneAI records which integration made each request, its timing and outcome, to run and improve the service; it does not sell this data.

Analyses are informational. Do not rely on them alone to buy, sell, insure or authenticate anything. Use is subject to the Terms and Privacy Policy.

Developer pilot

Building for collectors, resellers or estates? Pilot access raises the evaluation limits for your integration while we learn what it costs to serve well. There is no paid plan for agents yet.

Jewelry intelligence for AI assistants.

One conversation, start to finish

Photos in

A preliminary identification, with its doubts left in

Identification

As read from the photos

Unknowns

Next evidence

Market evidence, labelled for what it is

Price context, three numbers that are not the same number

Saved, and waiting in the app

What it will not tell you

Connect your assistant

For developers

Call it

What comes back (excerpt of the run above)

Privacy and use

Developer pilot