GemstoneAI

What the GemstoneAI MCP server does

The GemstoneAI MCP server gives an AI assistant access to a person's jewelry research workflow in the GemstoneAI app. It accepts one to five photos of a single piece, either as attached files or public HTTPS image URLs, and returns a preliminary identification. The result can include possible alternatives, unknowns, and evidence that could resolve the uncertainty.

It can also retrieve photographed market listings and sales related to the analyzed piece. Each comparable includes its source, a link, price, whether that price is an asking price or a completed sale, the date it was found, and material differences from the user's item. After analysis, the assistant can save the piece to the signed-in person's GemstoneAI collection and return a link that opens it in the app.

How it works

The service is hosted at https://api.gemstoneaiapp.com/mcp and communicates over stateless Streamable HTTP with JSON responses. A compatible MCP client adds the endpoint as a remote server and discovers the sign-in flow. Authentication uses OAuth 2.1 with PKCE. The signed-in identity is tied to the same account used by the GemstoneAI app, so saved collection items remain available there.

The normal sequence is to submit photos with analyze_jewelry, check or retrieve the result with get_jewelry_analysis, request market context with find_jewelry_comparables, and optionally call save_collection_item. An analysis commonly takes 20 to 45 seconds. The first tool waits for about 40 seconds and can return a processing state with a retry interval; comparables generally become available within about a minute.

Setup and configuration

No local installation or process is required. Add the remote MCP URL to a client that supports remote Streamable HTTP servers, then sign in when prompted. Claude Code can install the repository's plugin, which includes the server configuration and a jewelry-research skill, or add the server directly with its HTTP transport.

OAuth discovery is available through the protected-resource and authorization-server well-known endpoints on api.gemstoneaiapp.com. The server supports client registration through Client ID Metadata Documents or dynamic registration. Access tokens last one hour, and rotating refresh tokens are used. The available scopes are jewelry:analyze and collection:write.

Tools and capabilities

• analyze_jewelry accepts attached photos or public HTTPS image URLs. Without photos, it returns an upload link that can be opened on a phone. An optional idempotency key supports repeat-safe requests.
• get_jewelry_analysis returns the status or completed result and may wait while processing.
• find_jewelry_comparables returns photographed listings and sales with pricing context and differences from the analyzed item.
• save_collection_item writes the analyzed piece to the user's collection and returns an app link.

Repeated photos or a repeated idempotency key return the same analysis without charging twice. The API does not provide numeric confidence scores. If its readings disagree about the stone, it withholds price context and explains why. When no priced comparables exist, it reports that none were found rather than treating the result as zero value.

Limitations and notes

Outputs are preliminary interpretations of photographs, not appraisals. They do not confirm authenticity, treatment, origin, or certified value. The service does not buy, sell, list, or contact other people, and it saves an item only when requested.

Photos are retained with the jewelry item in the person's GemstoneAI account for analysis, similar to a scan in the app. Location data is removed from each photo. During the pilot, daily evaluation limits apply per account and per integration, and pilot access can be requested through the product page.

The GemstoneAI MCP server supports MCP clients using protocol versions from 2024-11-05 through 2025-11-25 and version 2026-07-28. Client support is tested only after the full photo, analysis, comparables, save, and app-reopen journey succeeds in that client.