---
name: ada-diamonds-mcp
description: Connect to the Ada Diamonds MCP servers (catalog at https://www.adadiamonds.com/mcp, documentation at https://www.adadiamonds.com/mcp/docs) from Claude Code, Claude Desktop, Cursor, ChatGPT, or any Streamable HTTP MCP client, and use their tools and resources well. Use when setting up an MCP connection to Ada Diamonds, listing what the servers expose, or choosing between a tool call and a resource read.
license: MIT
metadata:
  author: Ada Diamonds
  homepage: https://www.adadiamonds.com/developers
  version: "1.0.0"
---

# Ada Diamonds MCP servers

Two Streamable HTTP servers, both anonymous for catalog and content. No OAuth handshake before `tools/list`.

| Server | URL | Purpose |
| --- | --- | --- |
| `ada-diamonds` | `https://www.adadiamonds.com/mcp` | Live catalog: diamonds, settings, jewelry, guides, company info, consultations |
| `ada-diamonds-docs` | `https://www.adadiamonds.com/mcp/docs` | Read-only: the developer documentation itself (`search_docs`, `read_doc`, `list_docs`) |

Registry name: `com.adadiamonds/ada-diamonds`. Server cards: `https://www.adadiamonds.com/.well-known/mcp/server-card.json` (also `/mcp/server-card`) and `https://www.adadiamonds.com/.well-known/mcp/docs-server-card.json` (also `/mcp/docs/server-card`). Registry manifest: `https://www.adadiamonds.com/server.json`. A plain `GET` on either server URL describes it.

This repository ships both in `mcp.json` (Agent Plugins format), so a client that installs the plugin gets them without further configuration.

## Connect

### Claude Code

```bash
claude mcp add --transport http ada-diamonds https://www.adadiamonds.com/mcp
claude mcp add --transport http ada-diamonds-docs https://www.adadiamonds.com/mcp/docs
```

Or in `.mcp.json` at the project root:

```json
{
  "mcpServers": {
    "ada-diamonds": { "type": "http", "url": "https://www.adadiamonds.com/mcp" },
    "ada-diamonds-docs": { "type": "http", "url": "https://www.adadiamonds.com/mcp/docs" }
  }
}
```

### Claude Desktop and claude.ai

Either add it as a connector (Settings, Connectors, "Add custom connector", URL `https://www.adadiamonds.com/mcp`), or put it in `claude_desktop_config.json` (Settings, Developer, Edit Config) and restart:

```json
{
  "mcpServers": {
    "ada-diamonds": { "type": "http", "url": "https://www.adadiamonds.com/mcp" }
  }
}
```

No OAuth prompt appears for the public tools; `request_consultation` asks for consent when first used.

### Cursor

`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "ada-diamonds": { "url": "https://www.adadiamonds.com/mcp" },
    "ada-diamonds-docs": { "url": "https://www.adadiamonds.com/mcp/docs" }
  }
}
```

### ChatGPT

Settings, Connectors, "Create". Name it `Ada Diamonds`, MCP server URL `https://www.adadiamonds.com/mcp`, authentication "No authentication". Once saved, enable it in a chat from the tools menu (Developer mode is required for custom connectors on some plans).

### Any other client

Streamable HTTP, JSON-RPC 2.0, `Accept: application/json, text/event-stream`. The server tolerates a plain `application/json` Accept. CORS is open for browser clients.

```bash
# Initialize
curl -X POST https://www.adadiamonds.com/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
# List tools
curl -X POST https://www.adadiamonds.com/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

## Tools on `ada-diamonds`

| Tool | Does | Auth |
| --- | --- | --- |
| `search_diamonds` | Live loose diamond inventory by `shape`, `min_carat`, `max_carat`, `min_price`, `max_price`, `color`, `clarity`, `cut`, `sort`, `limit` (1-50, default 10) | none |
| `search_engagement_rings` | Settings by `shape` (center stone), `style`, `type`, `min_price`, `max_price` (setting only), `q`, `limit` | none |
| `search_jewelry` | Wedding bands, earrings, necklaces, bracelets, fashion rings by `category`, `type`, `shape`, `min_price`, `max_price`, `q`, `limit` | none |
| `search_knowledge_base` | Find published guides by `query`, `limit` (1-25, default 8) | none |
| `read_article` | Full markdown of one guide by `slug` | none |
| `get_company_info` | Contact details, showroom, hours, how buying works | none |
| `request_consultation` | Book a jeweler consultation: `email` (required), `name`, `phone`, `topic`, `message`, `budget_usd`, `product_url` | `appointments:write` via OAuth consent |

All search tools are annotated `readOnlyHint: true`. `request_consultation` is non-destructive but writes; it cannot be used without the customer approving the scope on Ada's consent screen.

Prices returned by every tool are US dollars. Setting prices exclude the center diamond; pair `search_engagement_rings` with `search_diamonds` to quote a complete ring (see the `ada-diamonds-shopping` skill).

## Resources on `ada-diamonds`

Read these once at the start of a session. They give the shape of the catalog and save several tool calls.

| URI | Contents |
| --- | --- |
| `ada://catalog/diamonds` | Inventory summary by shape with carat and price ranges |
| `ada://catalog/engagement-rings` | Settings by style with price ranges |
| `ada://catalog/jewelry` | Jewelry by category |
| `ada://content/knowledge-base` | Every published guide |
| `ada://company/profile` | Who Ada Diamonds is, how buying works |
| `ada://developers/api` | The API reference, condensed |

All resources are `text/markdown`.

## The docs server (`ada-diamonds-docs`)

A second, read-only, anonymous server at `https://www.adadiamonds.com/mcp/docs` that exposes the developer documentation itself, so a coding agent can look up an endpoint or a scope while writing an integration instead of scraping pages. It shares no state with the catalog server.

| Tool | Does |
| --- | --- |
| `search_docs` | Full-text search across the developer documentation; returns matching pages and sections with URLs |
| `read_doc` | The markdown text of one documentation page |
| `list_docs` | Every documentation page with its title and URL |

The same content is reachable as markdown at `https://www.adadiamonds.com/developers` (send `Accept: text/markdown`), `https://www.adadiamonds.com/developers/llms.txt`, and `https://www.adadiamonds.com/mcp/llms.txt`.

## Tool-versus-resource guidance

- Shopper asks "what can $5,000 buy": read `ada://catalog/diamonds` for ranges, then one `search_diamonds` call with a `max_price`.
- Shopper asks about a specific stone: `search_diamonds` with tight `min_carat`/`max_carat`, or `GET /api/v1/diamonds/{report}` over REST. Do not rely on a result from earlier in the session; inventory turns over.
- Questions about CVD, HPHT, the 4Cs, or certification: `search_knowledge_base` then `read_article`. Cite the article URL.
- Questions about the business: `get_company_info` or `ada://company/profile`.

## Rate limits and errors

The MCP server sits behind the same limiter as the REST API (120 requests/minute anonymous, 600 with a credential). Tool errors come back as `isError: true` text that says what to do next (for example, that a stone has sold and how to list what is available). Send `Authorization: Bearer <key>` with a self-serve key from `POST https://www.adadiamonds.com/api/v1/keys` to raise the limit; the public sandbox key `ada_test_public_sandbox_key` also works.