vex: the Vendure CLI and MCP server for the Admin API
vex talks to the Vendure Admin GraphQL API - from your terminal, or as an MCP server so Claude can do it for you. It reads your instance's schema including the fields your own plugins add, manages multiple environments, and turns a query you built once into something you can replay. Requires Vendure 3.6 or newer.
Three bad ways to drive the Admin API
When you need to change something in a Vendure instance that the Admin UI does not expose, you have had three unsatisfying options. Clicking through the Admin UI: fine once, not repeatable, and frequently not offered at all for the fields your own plugins add. Hand-writing GraphQL in curl or Postman: it works, but you rewrite every selection set, juggle auth headers, and guess what that field in your custom plugin is actually called. Or you write a script that does exactly one thing and then sits in a folder collecting dust.
All three share the same gap: none of them knows your schema. Vendure projects diverge from the default exactly where the real work is - custom types, custom mutations, custom permissions. vex fetches your instance's SDL, caches it, and works from it: in the field picker, in introspection, and in the error message when the API key is missing a permission.
Requires Vendure 3.6 or newer
vex authenticates with API keys, which Vendure introduced in 3.6. On 3.5 or older it will not run - check this before you install. You also need Node.js 20 or newer.
- Enable API key auth in your Vendure config:
authOptions: { tokenMethod: ['cookie', 'bearer', 'api-key'] } - Go to Settings > API Keys in the Vendure dashboard.
- Create a key, assign the roles and permissions it needs, and copy it - it is shown only once.
The key is sent in the vendure-api-key header on every request.
How it works
Set it up once, then every environment is one command away. vex keeps everything under ~/.vendure-vex/: environments, cached schemas, fragments, and saved operations.
Add an environment
vex env add dev prompts for URL and API key and validates them right away by fetching the schema. Multiple instances live side by side, and vex env status tells you per environment whether the endpoint is reachable and the key accepted.
Build or save a query
In the interactive builder you pick the operation and the fields, vex prompts for variables with proper type coercion, and shows you the GraphQL document it produced. Add --save and it becomes a named operation you can replay later with vex run and different variables.
Wire up Claude (optional)
vex mcp install writes a .mcp.json into your project and links the directory to the environment you picked. From then on Claude works through the same operations you use in the terminal.
Quickstart
Install globally, add one environment, go - everything after that is optional.
npm install -g @spaceparrots/vexvex env add dev
vex env status dev
vex build -q customers
vex build -q contents --save ContentsPublished
vex run ContentsPublished --var "options={\"take\":5}"
vex schema fetchvex mcp installPrefer reviewing first? vex mcp config prints the snippet without writing.
What vex does
Not a framework, not a dashboard - a command line tool for people who already work against the Admin API.
Multiple environments with a health check
Dev, staging, and production sit side by side as named environments, switchable with vex use <env>. vex env status checks endpoint reachability, whether the API key is accepted, and the state of the cached schema.
Schema aware, custom plugin fields included
vex fetches your instance's SDL and stores it per environment, including the types, queries, and mutations your own plugins add. Introspection then runs locally: describe a type, list custom fields, look up an operation.
Interactive query builder
Pick the operation, tick the fields in the picker, enter variables with proper type coercion - vex shows the document it built and runs it. Add --dry-run to see the result before anything reaches the server.
Fragments and saved operations
Fragments are named field selections you reuse across operations. Saved operations store the full document plus its default variables and replay through vex run, with individual variables overridable.
Typed resource commands and asset uploads
Customers, products, orders, channels, zones, and tax ship with list/get/create/update/delete plus resource-specific actions such as order transition or zone add-members. vex asset upload pushes local files up and handles the GraphQL multipart request for you.
Escape hatch and permission diagnostics
vex query and vex mutate run any GraphQL document when no ready-made command fits. When something fails with FORBIDDEN or UNAUTHORIZED, vex names the denied operation and suggests the likely missing Permission values; vex schema permissions lists them all, plugin permissions included.
Manage Vendure with Claude: the MCP server
Started with no arguments, vex runs as an MCP server over stdio - exactly what MCP clients expect. Server instructions ship with the handshake, so Claude already knows the tool tiers of typed entity tools, schema discovery, and raw GraphQL before the first call. The cached schema is also exposed as the MCP resource vendure://schema/<envName>.
Full mode
The default, 15 tools. Each entity domain is one action-dispatch tool: vex_customers, vex_products, vex_orders, vex_channels, vex_zones, vex_tax, vex_assets, plus setup, schema discovery, raw GraphQL, fragments, and saved operations. A call looks like vex_products with { "action": "get", "id": "5" }.
Lean mode
Set VEX_TOOLS=lean in your MCP client config and vex registers only the universal interface: vex_setup, vex_current_env, vex_refetch_schema, vex_query, vex_mutate, vex_schema. Claude then drives Vendure through schema discovery plus raw GraphQL.
Why this is a token question
Tool definitions are always on: the name, description, and JSON schema of every registered tool sit in the context of every request, whether the tool gets used or not. That is why vex groups whole domains into one action-dispatch tool instead of one tool per operation, and why lean mode exists: less convenience, smallest possible per-session footprint. MCP responses are compact JSON, and VEX_PRETTY_JSON=1 pretty-prints them for debugging at roughly 30 percent more tokens.
Create me a dummy order for product "shoes".
Claude checks whether the product exists, creates it if needed, finds or creates a customer, creates a draft order, and adds items - chaining the MCP tools on its own.
When vex fits, and when it does not
A good fit if
- You regularly do things to a Vendure instance that the Admin UI does not expose, or that come up too often to click through.
- Your instance runs custom plugins with their own types, mutations, or permissions and you would rather not look their fields up every time.
- You run several environments and need certainty about which one you are working against.
- You want Claude or another MCP client near your shop, but through defined tools rather than freehand HTTP.
Not a fit if
- You need the Storefront API: vex works against the Admin API only.
- Your instance runs Vendure 3.5 or older - without API key auth there is no way in.
- You want to drive some other GraphQL API: vex is built around Vendure, not around GraphQL in general.
- You are looking for a graphical interface for non-technical colleagues - that is what the Admin UI is for, and it does that better.
vex, the Admin UI, or hand-written GraphQL
There is no direct counterpart to vex. The real alternatives are the Admin UI and GraphQL you write yourself, and both have situations where they are the better call.
| Criterion | vex | Admin UI | Raw GraphQL |
|---|---|---|---|
| Schema awareness incl. custom fields | Fetches and caches your instance's SDL, custom plugin types included | Shows only what the UI was built to show | You know the schema, or you introspect it yourself |
| Repeatability | Saved operations and fragments, replayable with vex run | Every run is manual | Repeatable if you manage documents and variables yourself |
| Multi-environment | Named environments, project links, health check on command | One URL and one login per instance | You juggle URLs and headers by hand |
| AI controllable | MCP server with 15 tools, 6 in lean mode | Not designed for it | Only through an integration you build |
| Barrier to entry | Node.js, a terminal, one setup step | Lowest: log in and click, no GraphQL knowledge needed | Low on setup, high on knowledge |
| Overview and eyeballing | Text output, JSON or a table | Clearly better: lists, detail views, previews | Raw JSON |
Missing a command? Build it in.
I built vex to automate the recurring moves against a Vendure instance, and to make checks on it repeatable instead of clicking them together again every time.
vex covers the domains I reach for most. Your instance looks different: its own plugins, its own mutations, its own routines. If a resource command is missing, a custom field does not come through cleanly, or you need a tool that MCP mode does not expose, open an issue or send a pull request straight away. MIT licensed, no CLA.
Frequently asked questions about vex
vex is an open-source CLI and an MCP server for the Vendure Admin GraphQL API. From the terminal it manages products, customers, orders, channels, zones, tax, and assets; connected as an MCP server, Claude performs the same operations. The package is @spaceparrots/vex, MIT licensed, published on npm.
Vendure 3.6 or newer. vex authenticates with API keys, which were introduced in 3.6. There is no supported way to run it against older versions.
Extend authOptions.tokenMethod in your Vendure config with 'api-key' so it reads ['cookie', 'bearer', 'api-key']. Then go to Settings > API Keys in the dashboard, create a key, and assign it the roles carrying the permissions it needs. The key is shown only once, so copy it immediately. vex sends it in the vendure-api-key header.
Yes. vex mcp install writes a .mcp.json into your project and vex is available as an MCP server from then on. You describe the task in plain language and Claude chains the right tools: find the product, create a customer, create a draft order, add items.
Yes, that is one of the reasons it exists. It fetches the SDL of your running instance and caches it per environment, so the types, queries, mutations, and permissions your plugins add are available to the field picker, to introspection, and to the MCP tools. For custom mutations without a dedicated command there are vex query and vex mutate.
Full mode is the default and registers 15 MCP tools, including typed tools for customers, products, orders, and the other domains. Lean mode via VEX_TOOLS=lean registers only 6: setup, current environment, schema refetch, schema discovery, and raw query and mutate. Fewer tool definitions mean less context per session, at the cost of Claude doing more discovery and writing more GraphQL itself.
Yes. Environments are stored by name in ~/.vendure-vex/config.json and switched with vex use <env>. vex resolves which one applies in this order: an explicit --env, then the VEX_ENV variable, then a project link for the current directory, then the globally active environment. vex status tells you which one is in use and why.
Nothing. vex is open source under the MIT license and installs from npm with npm install -g @spaceparrots/vex. You need Node.js 20 or newer and a Vendure instance on 3.6 or above.
Try vex
One npm install, one vex env add, and you are talking to your Admin API - assuming your instance runs Vendure 3.6 or newer.
vex comes out of the day-to-day Vendure work at SpaceParrots. If you need more than a tool and want help on the project itself: Vendure consulting and development.