> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server vs REST API

> When to use the Closient MCP server vs the REST API for AI agent integration, custom backends, and developer tooling.

Closient exposes the same product graph through two surfaces: a
hosted [Model Context Protocol](https://modelcontextprotocol.io)
server and an [HTTPS REST API](/api-reference/overview). They cover the
same data; they're optimised for different consumers.

## Should I use the MCP server or the REST API?

| If you're...                                                            | Use                                       |
| ----------------------------------------------------------------------- | ----------------------------------------- |
| Building an AI agent (Claude, Cursor, IDE assistant, custom MCP client) | **MCP server**                            |
| Integrating product lookup into a backend service                       | **REST API**                              |
| Embedding barcode resolution in a mobile or web app                     | **REST API**                              |
| Connecting a no-code workflow tool (n8n, Make, Zapier)                  | **REST API**                              |
| Hooking a desktop AI app into product data                              | **MCP server**                            |
| Building a CLI that humans run interactively                            | Either — REST is simpler for non-AI tools |

The rough rule: **if the consumer is an LLM, use MCP. If the consumer
is code you wrote, use REST.**

## What's the difference between an AI agent calling MCP and an AI agent calling the REST API?

Both work; the AI client experience is what differs.

**MCP** gives the agent a tool list at connect time, with structured
input/output schemas and human-readable descriptions. The agent picks
tools by name and the LLM doesn't need any "how to call this API"
documentation in its prompt — the protocol handles tool discovery,
parameter validation, and result framing.

**REST** forces you to put the API surface into the agent's prompt
(or its function-calling schema), which costs tokens and means every
release of the agent needs an updated tool definition.

For agents that already speak MCP — Claude Code, Cursor, Claude Desktop,
VS Code, Windsurf — MCP is strictly less work.

## What can each surface do?

| Capability                       | MCP                                                                                     | REST                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Validate a GTIN                  | `validate_gtin`                                                                         | `GET /products/api/v1/products?gtin=...`                       |
| Resolve a GTIN                   | `resolve_gtin`                                                                          | `GET /01/<gtin>`                                               |
| Look up product data             | `lookup_product`                                                                        | `GET /products/api/v1/products/<id>`                           |
| Natural-language search          | `search_products`                                                                       | `POST /search/api/v1/sessions`                                 |
| Compare products                 | `compare_products`                                                                      | Multiple `GET /products` calls + client-side join              |
| Check local availability         | `check_availability`                                                                    | `GET /retailers/api/v1/offers`                                 |
| Generate Digital Link QR         | `generate_qr_url` (OAuth)                                                               | `POST /api/v1/qr-codes` (API key)                              |
| Create / claim a product         | `create_product` (OAuth)                                                                | `POST /products/api/v1/products`                               |
| Edit basic info, dimensions, GPC | `update_product` (OAuth)                                                                | `PATCH /products/api/v1/products/<gtin>`                       |
| Upload / delete product images   | `upload_product_image`, `delete_product_image` (OAuth)                                  | `POST` / `DELETE /dashboard/api/v1/...`                        |
| Upload / edit / delete documents | `upload_product_document`, `update_product_document`, `delete_product_document` (OAuth) | `POST` / `PATCH` / `DELETE /dashboard/api/v1/...`              |
| Add / edit / delete videos       | `add_product_video`, `update_product_video`, `delete_product_video` (OAuth)             | `POST` / `PATCH` / `DELETE /dashboard/api/v1/...`              |
| Set nutrition facts              | `set_product_nutrition` (OAuth)                                                         | `PUT /dashboard/api/v1/.../nutrition`                          |
| Set ingredients                  | `set_product_ingredients` (OAuth)                                                       | `PATCH /products/api/v1/products/<gtin>` (`ingredients` field) |
| Webhooks / event streams         | *Not exposed*                                                                           | `/integrations/webhooks`                                       |
| Bulk operations                  | *Not exposed*                                                                           | Pagination + batch endpoints                                   |

Both surfaces now cover the full brand-owner product-entry workflow — an
agent holding an MCP connection with a `products:write`/`dashboard:write`
scoped token can create a product and enter every field a human could enter
through the dashboard UI, without switching to REST. See
[MCP Tool Reference](/guides/mcp-tools) for the complete write-tool list.
Webhooks and true bulk operations (multi-hundred-row imports) remain
REST-only — those aren't a good fit for a single LLM tool call.

## How do auth and rate limits compare?

| Aspect                          | MCP                           | REST                                    |
| ------------------------------- | ----------------------------- | --------------------------------------- |
| Default auth                    | None (most tools)             | API key required                        |
| Authenticated tools / endpoints | OAuth 2.1 step-up             | `X-API-Key: <prefix>_<body>_<checksum>` |
| Rate limit                      | Shared backend limits         | 300/min, 10,000/day per key             |
| Client registration             | CIMD / DCR / pre-registration | Dashboard → Settings → API Keys         |

## Can I use both?

Yes — and many integrations do. A common pattern:

* **MCP server** for the agent's read path (lookup, search, resolve).
* **REST API** for the backend that owns mutations (catalog edits,
  webhook subscriptions, bulk imports) where you don't want LLM-induced
  side effects.

Auth is independent — the OAuth tokens minted for the MCP write tool
and the API keys minted for the REST API live in different namespaces
and have different scopes.

## Where do I go next?

<CardGroup cols={2}>
  <Card title="MCP Install" icon="download" href="/guides/mcp-install">
    One-command install for every supported MCP client.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Eighteen domain APIs with interactive playgrounds.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    First REST API call in under five minutes.
  </Card>

  <Card title="MCP Quickstart" icon="rocket" href="/guides/mcp-quickstart">
    First MCP tool call in under two minutes.
  </Card>
</CardGroup>

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify({
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
  "@type": "Question",
  "name": "Should I use the Closient MCP server or the REST API?",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "Use the MCP server when the consumer is an LLM (Claude, Cursor, IDE assistants, custom MCP clients). Use the REST API when the consumer is code you wrote — backend services, mobile apps, no-code workflow tools. The two surfaces share the same product graph; MCP is optimised for agent discovery, REST is optimised for custom code."
  }
},
{
  "@type": "Question",
  "name": "What's the difference between an AI agent calling MCP and an AI agent calling the REST API?",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "MCP gives the agent a tool list at connect time with structured schemas, so the LLM doesn't need API documentation in its prompt. REST forces you to put the API surface into the agent's prompt or function-calling schema, costing tokens and requiring updates on every release. For agents that already speak MCP — Claude Code, Cursor, Claude Desktop, VS Code, Windsurf — MCP is strictly less work."
  }
},
{
  "@type": "Question",
  "name": "Does the Closient MCP server support catalog writes?",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "Yes. Alongside generate_qr_url, the MCP server exposes a full set of OAuth-gated product write tools — create_product, update_product (basic info, dimensions/weight, GPC classification), image/document/video upload and delete, set_product_nutrition, and set_product_ingredients. An agent with a products:write or dashboard:write scoped token can complete the entire brand-owner product-entry workflow over MCP alone, without touching the dashboard UI or the REST API. Webhook subscriptions and multi-row bulk operations remain REST-only."
  }
},
{
  "@type": "Question",
  "name": "Can I use the Closient MCP server and REST API together?",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "Yes — a common pattern is MCP for the agent's read path (lookup, search, resolve) and REST for the backend that owns mutations (catalog edits, webhooks, bulk imports). Auth is independent: OAuth tokens for MCP write tools and API keys for REST live in different namespaces with different scopes."
  }
},
{
  "@type": "Question",
  "name": "How do rate limits compare between MCP and REST?",
  "acceptedAnswer": {
    "@type": "Answer",
    "text": "REST API rate limits are 300 requests per minute and 10,000 per day per API key (custom limits available). The MCP server shares the same backend limits but no upfront API key is required — most tools are public. Authenticated MCP tools share the rate-limit pool with the OAuth client they're connected to."
  }
}
]
}) }}
/>