> ## 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.
# Install the Closient MCP Server
> Connect Claude, Cursor, VS Code, and other MCP-compatible AI tools to Closient in one click or with a single command.
The Closient MCP server lets any AI agent that speaks the
[Model Context Protocol](https://modelcontextprotocol.io) call Closient
directly — validate GTINs, resolve them to product pages, look up
catalog data, search by natural language, compare products, find
nearby availability, and (with auth) generate Digital Link URLs for
QR codes.
The server is hosted by Closient — you do not install or run anything
locally. Pointing your MCP client at the server URL is enough.
| | Value |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Server URL (Streamable HTTP) | `https://www.closient.com/mcp/http` |
| Server URL (legacy SSE) | `https://www.closient.com/mcp/sse` |
| Health probe | `https://www.closient.com/mcp/health` |
| Authorization Server metadata | [`/.well-known/oauth-authorization-server`](https://www.closient.com/.well-known/oauth-authorization-server) |
| Protected Resource metadata | [`/.well-known/oauth-protected-resource`](https://www.closient.com/.well-known/oauth-protected-resource) |
Use `https://www.closient.com/mcp/http` for new integrations. The
`/mcp/sse` endpoint is kept for backwards compatibility with older
MCP clients that haven't adopted the Streamable HTTP transport yet.
## Tier 1 — first-class clients
These clients ship MCP support out of the box. Pick the matching tab
and follow the snippet — no extra packages, no local server, no JSON
hand-editing.
Run once from a terminal:
```bash theme={null}
claude mcp add closient --transport http https://www.closient.com/mcp/http
```
That's it. `claude mcp list` should now show `closient` and the tools
become available to any Claude Code session in this workspace.
To remove later: `claude mcp remove closient`.
1. Open **Claude Desktop > Settings > Connectors** (formerly
"Custom Connectors").
2. Click **Add custom connector**.
3. Paste the server URL:
```
https://www.closient.com/mcp/http
```
4. Save. Claude Desktop will discover the tools and prompt for OAuth
the first time you call `generate_qr_url` (see
[Authentication](/guides/mcp-authentication)).
For a deeper walkthrough see Anthropic's
[custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
1. Open [claude.ai](https://claude.ai) and go to
**Settings > Connectors > Custom Connectors**.
2. Click **Add custom connector**.
3. Paste:
```
https://www.closient.com/mcp/http
```
4. Save. The connector is available to all chats on this account.
**One-click install:**
Click to open Cursor with the Closient server pre-filled. You'll
see a confirmation prompt before it's added.
**Manual install:** open `~/.cursor/mcp.json` (or use
**Settings > MCP > Add new server**) and add:
```json theme={null}
{
"mcpServers": {
"closient": {
"url": "https://www.closient.com/mcp/http"
}
}
}
```
Run from a terminal:
```bash theme={null}
code --add-mcp '{"type":"http","name":"closient","url":"https://www.closient.com/mcp/http"}'
```
VS Code 1.95+ ships built-in MCP support. The Closient server is
added to your user `settings.json` under
`"mcp.servers"` and available to GitHub Copilot Chat and any
MCP-aware extension.
To add manually, open **Settings > MCP > Edit settings.json** and add:
```json theme={null}
{
"mcp": {
"servers": {
"closient": {
"type": "http",
"url": "https://www.closient.com/mcp/http"
}
}
}
}
```
## Tier 2 — Windsurf
Windsurf reads a `mcp_config.json` file in the project root (or the
global `~/.codeium/windsurf/mcp_config.json`). Add:
```json theme={null}
{
"mcpServers": {
"closient": {
"url": "https://www.closient.com/mcp/http"
}
}
}
```
Restart Windsurf and the Closient tools appear in the Cascade panel.
## Tier 3 — generic JSON config
Any MCP-compatible client (Cline, Zed, Trae, Continue, custom
agents built on the MCP Python or TypeScript SDKs, etc.) can connect
with the generic Streamable HTTP entry below. Paste it into whatever
configuration format the client uses for MCP servers.
```json theme={null}
{
"name": "closient",
"transport": "http",
"url": "https://www.closient.com/mcp/http"
}
```
If the client only supports the older HTTP+SSE transport, use:
```json theme={null}
{
"name": "closient",
"transport": "sse",
"url": "https://www.closient.com/mcp/sse"
}
```
## What you get
Once installed, the client discovers the following tools (no auth
required for discovery):
| Tool | Auth | Use case |
| -------------------- | ----- | ------------------------------------------------------------------------- |
| `ping` | none | Health probe — returns `pong`. |
| `validate_gtin` | none | Check a GTIN's structure and check digit. |
| `resolve_gtin` | none | Apply the resolver-rule hierarchy and return the destination URL. |
| `lookup_product` | none | Look up structured product data by GTIN. |
| `search_products` | none | Natural-language search across the catalog, optionally with geo boosting. |
| `get_product_detail` | none | Rich product record — attributes, images, ingredients, nutrition. |
| `compare_products` | none | Side-by-side comparison of 2-5 products. |
| `check_availability` | none | Find nearby physical stores carrying a GTIN. |
| `generate_qr_url` | OAuth | Build the canonical Digital Link URL to encode in a 2D barcode. |
Full input/output schemas and examples are in the
[Tool Reference](/guides/mcp-tools).
## Authentication
The first eight tools above work immediately — no token, no setup.
`generate_qr_url` requires an OAuth 2.1 bearer token with the
`qr:generate` scope. When you (or your agent) call it without a
token, Closient returns `403 Forbidden` with a `WWW-Authenticate`
header that tells the MCP client where to start the OAuth flow. Most
first-class MCP hosts (Claude Desktop, Cursor, VS Code) handle the
prompt-and-retry transparently — see
[Authentication](/guides/mcp-authentication) for the full flow.
## Verifying the connection
After installing, ask your AI tool something like:
> Use the Closient MCP server to validate GTIN 00614141123452.
The agent should call `validate_gtin` and report the GTIN is valid
(it's a real GS1 test code). If you get a "no MCP server named
closient" error, restart the client — most hosts only pick up new
server configs on launch.
A direct sanity check from a terminal:
```bash theme={null}
curl -sS https://www.closient.com/mcp/health
```
A `200 OK` response means the hosted server is reachable from your
network.
## Troubleshooting
| Symptom | Likely cause |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client can't connect | Corporate proxy or firewall blocking `closient.com`. Try `curl https://www.closient.com/mcp/health` from the same host. |
| `tools/list` returns empty | Client is configured for `transport: stdio` instead of `http`. Closient is a remote server only. |
| `generate_qr_url` always returns 403 | Token missing the `qr:generate` scope. Re-run the OAuth flow and accept the consent screen — older tokens issued without the scope must be refreshed. |
| OAuth pop-up never appears | Client doesn't honour the `WWW-Authenticate` header (some self-built MCP clients). Mint a token manually via [OAuth Authentication](/guides/mcp-authentication) and pass it in `Authorization: Bearer `. |
| 401 instead of 403 | Token is expired. Access tokens last 24 h, refresh tokens 90 d. |
## Reference
* [Tool Reference](/guides/mcp-tools) — input/output schemas for every tool.
* [Authentication](/guides/mcp-authentication) — OAuth 2.1 step-up flow.
* [MCP Error Contract](/guides/mcp-errors) — how failures surface over JSON-RPC.
* [MCP Identity Propagation](/guides/mcp-identity) — agent vs. end-user actor in audit logs.
* [MCP Tool Annotations](/guides/mcp-tool-annotations) — `readOnlyHint` / `destructiveHint` semantics.
* [Model Context Protocol spec](https://modelcontextprotocol.io) — the underlying open standard.