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/
There are two ways to connect. Either way, the assistant reaches the data of one Valigara account only.
Sign in — for Claude, ChatGPT and any other assistant that supports MCP sign-in. There is nothing to create or copy, and it is how you connect from an assistant’s connector directory.
Access key — for assistants that cannot sign in, or that you set up with a configuration file.
Sign in with OAuth
The MCP server implements the standard MCP authorization flow (OAuth 2.1 with PKCE). An assistant that supports it registers itself and discovers everything on its own — there is no client ID, secret or key to set up on either side.
1. Add Valigara to your assistant. Choose Valigara in the assistant’s connector directory, or add a custom connector with the server address above.
2. Sign in. The assistant opens Valigara in your browser. Sign in with your Valigara manager credentials.
3. Approve. The approval screen names the assistant, your user and store, and the site you will be returned to. Check them, then choose Approve.
The connection then keeps itself signed in: access tokens last one hour and are renewed automatically. If the assistant is not used for 30 days, it asks you to sign in again.
Each connection appears in My Account -> API tab as a key of type MCP, named “OAuth:” followed by the assistant’s name. Remove that key to disconnect the assistant straight away. Signing in never creates or changes your other keys.
The assistant acts as the user who approved it, but do not rely on user roles to limit it: some tools follow that user’s permissions, while most — like the Valigara API — work across the whole account. Treat a connection like an access key.
Connecting with an access key
Assistants that cannot sign in, or that you set up with a configuration file, use an MCP access key instead.
Create the key in My Account -> API tab: add a new key, choose the user it acts as, and set API key type to MCP. The type matters — the MCP server refuses API-type keys, and the Valigara API refuses MCP keys, so if you use both, keep one key of each type.
Submit the key using Authorization header in format:
Authorization: Bearer X (where X is access key)
Most of these assistants ask for two things: the server address and the authorization header. Enter them exactly as shown above. In assistants configured through a file, the entry looks like this:
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. To cut an assistant off, remove its key in the same tab.
Available tools
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.
The server offers 55 tools, all available on every account. Some follow the permissions of the user the connection acts as, and do not appear when that user’s role cannot use them. Every tool has a readable name and declares what it does: whether it only reads, whether it can change or delete data, and whether it reaches outside Valigara — posting to a sales channel, for example. A well-behaved assistant uses this to 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 (the Streamable HTTP transport, answered with plain JSON). You do not normally write these requests yourself — the assistant does — but they are useful for testing a connection. The samples below use an access key; an assistant that signed in sends its token in the same header.
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 versions 2025-06-18 and 2025-03-26.
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. Stock quantity updates, copying data between products, and starting, pausing or cancelling a batch accept dry_run: true, which returns what the call would do without changing anything — for products, the resolved products with their current and new values. 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
A request without a valid key or token is rejected with 401 before any tool runs. The response points to the server’s sign-in details, which is how an assistant knows to start signing in, renew its token, or ask you to sign in again.
A request sent from a web page on another website is refused with 403. Assistants connect from their own servers, so this does not affect them.
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
If signing in fails, send us the exact message the assistant shows, including any reference code, the time you tried, and the Valigara user you signed in as.
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.
