About Valigara MCP

About Valigara MCP

The Valigara MCP server lets an AI assistant work directly with your data on Valigara.com — your products, listings, orders, gemstones and batches — without copying anything between systems.

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external systems. Any MCP-capable assistant can connect to Valigara, so you are not tied to a single vendor.

The MCP server exposes the same actions as the Valigara API, described so that an assistant can use them on its own. If you are building an integration, use the API. If you want an assistant to do the work for you, use MCP.

Please contact us for the test account credentials.

Access & Authentication

The Valigara MCP server is accessed using the link below.

https://api.valigara.com/client/mcp/v1/

Submit an access key using Authorization header in format:
Authorization: Bearer X (where X is access key)

The access key can be found in My Account -> API tab — the same key used for the Valigara API. If you already have an API key, it works for MCP with no extra setup.

The key identifies your Valigara account, and an assistant can only reach the data of that account. Treat it like a password: anyone holding it can read and change your data.

Connecting an assistant

Most assistants ask for two things: the server address and an authorization header. Enter them exactly as shown above. In assistants configured through a file, the entry looks like this:

Once connected, the assistant asks the server what it can do and the tools appear automatically. There is nothing to install and nothing to keep updated — when Valigara adds a tool, connected assistants pick it up on their own.

Sign in with OAuth

The MCP server also implements the standard MCP authorization flow (OAuth 2.1 with PKCE). An assistant that supports it discovers everything on its own: you choose to connect, sign in with your Valigara manager credentials on the approval screen, and confirm — no key to create or copy. Sessions use short-lived tokens that refresh automatically, and access can be revoked at any time without touching your API key.

OAuth connections are enabled per assistant by Valigara — there is no self-service app registration. If you would like to connect your assistant this way, please contact us. Until OAuth is enabled for your assistant, the access key above works today and keeps working afterwards.

Available tools

The server offers 55 tools. 35 of them are available on every account today; the other 20 are rolling out in beta and may not be available on your account yet — the tool pages mark each of those with a short beta note. Every tool declares whether it reads or writes data, so a well-behaved assistant can ask you before doing anything that changes something.

Each tool is documented on its category page, with parameters and real request and response samples:

Products (16 tools) — import, update, export and search products; register sales; post to sales channels and revise listings; copy data between products.

Orders (11 tools) — export orders and buyers, import orders, set tracking numbers, update order fields, attach files.

Gemstones (7 tools) — the full gemstone lifecycle – import, update, export, search, delete – plus the field definitions.

Batches & Procedures (11 tools) — follow background jobs, read per-item results, pause, resume or cancel them, run saved procedures, inspect schedules.

Listings & Channels (3 tools) — search listings across every sales platform, inspect a single listing, see per-channel product status.

Stock, Models & Config (7 tools) — stock levels and adjustments, models, configuration lookup lists, the inventory valuation report.

Requests

MCP uses JSON-RPC 2.0 over HTTP POST. You do not normally write these requests yourself — the assistant does — but they are useful for testing a connection.

The connection opens with an initialize handshake, which the assistant performs for you:

Ask the server which tools are available:

Call a tool:

The server supports the standard MCP methods: initialize, ping, tools/list, tools/call, resources/list and resources/read. Protocol version 2025-06-18.

Working with batches

Many actions do not finish while you wait. Importing products, posting listings, revising inventory and running a procedure all start a batch — a background job — and return its id straight away.

This matters when you are talking to an assistant: when it says “started”, the work is queued, not done. Ask it to check batch_info with the batch id, and to read the errors before reporting success. A batch that finished is not the same as a batch that did what you wanted — check the counts.

Before you let an assistant change data

Read tools are safe to explore with. Write tools are not reversible, so a few habits are worth having.

There is no undo. Valigara does not keep a copy of what a value was before a tool changed it. If a product’s gemstones are overwritten, the previous grading is gone — and grading usually comes off a certificate that nobody can retype from memory.

Changes reach your sales channels. Wrong quantities cause overselling on eBay, Amazon and the rest, which costs money and damages your standing with the marketplace.

Ask for the scope before saying yes. “Update the rings” is not a scope. Ask the assistant how many products it is about to touch, and on which account.

Prefer a dry run where a tool offers one. Several write tools accept dry_run: true and return exactly what the call would do — the resolved products, current and new values — without changing anything. The tool pages show a dry-run sample wherever it is supported.

Watch for partial updates. When updating a product, sending a shorter list of gemstones, metals or images replaces the existing ones by default rather than adding to them.

Output Format

Tool results are returned as JSON inside the MCP response. Exports are paginated — tools such as products_export and orders_export take limit and offset and report the total number of matching records, so an assistant can page through a large catalogue rather than requesting all of it at once.

Errors

An unauthenticated or expired key is rejected before any tool runs. A tool called with invalid arguments is rejected with a message naming the offending parameter, and nothing is executed. Business errors from an action are returned in the result, with the same message codes as the Valigara API.

MCP Troubleshooting

When asking us about your work with Valigara MCP, please provide the raw http request & raw http response, including the name of the tool that was called and the arguments the assistant sent. The assistant can usually show you both.