Skip to content

Claude Code Setup

Jump to bottom
Kevin edited this page Jul 14, 2026 · 4 revisions

Claude Code Setup

This guide is for people connecting Vex to Claude for the first time. By the end, you'll be able to ask Claude things like "create a draft order for the Running Shoes product" and watch it happen in your Vendure store.

Three terms you'll keep seeing

  • Claude Code — Anthropic's AI agent. It runs in your terminal (or VS Code / JetBrains) and can use tools, not just chat.
  • MCP (Model Context Protocol) — the standard way Claude gets new tools. You point Claude at an "MCP server" and it gains whatever abilities that server provides.
  • Vex — an MCP server that gives Claude a pack of tools for managing a Vendure store. Once connected, Claude can list products, create customers, build orders, run GraphQL, and more.

You install Vex once, add your store once, run one command to connect Claude, and then you just talk to Claude.

Prerequisites

  1. Claude Code installed and working. (See Anthropic's Claude Code docs if you haven't set it up yet.)
  2. Node.js 20.19+ or 22.12+ — check with node --version.
  3. A Vendure 3.6+ store, running and reachable, and permission to create an API key in it.
    • Check the version in your Vendure project's package.json — the @vendure/core dependency must be 3.6.0 or newer.
    • If the store runs locally, start it before you continue. Step 2 validates the connection by fetching the schema, so it fails if the server is down.

Step 1 — Get a Vendure API key

Vex talks to Vendure using an API key, sent in the vendure-api-key header on every request. API keys arrived in Vendure 3.6 — see Vendure's API keys documentation.

1. Make sure API-key auth is switched on. In your Vendure server's config file (usually src/vendure-config.ts):

authOptions: {
  tokenMethod: ['cookie', 'bearer', 'api-key'],
}

⚠️ This is a change to your backend, not a setting in a UI. It needs a code change, a deploy, and a server restart. If you don't own that repo, ask whoever does whether api-key is already in tokenMethod — many teams have it on already, in which case skip to step 2 below.

2. Open the Vendure admin dashboard — the same host as your store with /admin on the end, e.g. http://localhost:3000/admin — and go to Settings → API Keys.

If there's no API Keys entry under Settings, you're either on Vendure < 3.6 or api-key isn't in tokenMethod yet. Go back to step 1.

3. Create a key, give it a role, and copy it now — it is shown only once.

Which permissions? Give the key the narrowest role that covers what you actually want Claude to do. A good starting point:

You want Claude to… Grant
Read and report only (safest — start here) ReadCatalog, ReadCustomer, ReadOrder, ReadSettings
Also create/edit records (needed for the Step 5 demo) The above plus CreateCatalog, UpdateCatalog, CreateCustomer, CreateOrder, UpdateOrder
Everything SuperAdmin — don't, except on a throwaway dev store

You don't have to get this right the first time. If a permission is missing, Vex tells you exactly which one — see Safety below.

Keep the key handy; you'll paste it in Step 2.

Step 2 — Add the environment to Vex

Install Vex and add your store as a named environment:

npm install -g @spaceparrots/vex
vex env add dev

It prompts for two things:

  • The URL. This is your Vendure Admin API endpoint — your store's host with /admin-api on the end, e.g. http://localhost:3000/admin-api or https://shop.example.com/admin-api. It is not your storefront URL, and not the /admin dashboard URL you just logged into. (If your team customized adminApiPath, ask them what it is.)
  • The API key from Step 1.

Vex then validates the connection by fetching the schema. The first environment you add becomes the active one.

See CLI Usage → Environments for the non-interactive form (--url / --api-key) and all the flags.

Prefer not to install globally? Run the same commands via npx -y @spaceparrots/vex env add dev.

Step 3 — Install the MCP server

First, go to the project you open in Claude Code. .mcp.json is picked up from the directory Claude Code is launched in, so this must run there — not in your home directory:

cd /path/to/your/project
vex mcp install

Run it interactively and it prompts for:

Prompt Choices
Environment Any environment you've added with vex env add (active one preselected).
Tool mode lean (recommended) or full — see Lean or full? below.
Invocation Invoke via a globally installed vex, or via npx -y @spaceparrots/vex if you'd rather not install globally.
Project link Whether to also link this directory to the chosen environment (see Project-linked environments), so the CLI auto-selects it here too.

Prefer flags over prompts, e.g. for scripting or a non-interactive shell:

vex mcp install                                       # interactive, current directory
vex mcp install ../shop --env dev --tools lean --yes  # non-interactive
Flag Meaning
[dir] Target project directory (positional, default: current directory).
--env <name> Environment to pin via VEX_ENV in the server entry.
--tools <mode> Tool mode: lean or full (default lean).
--npx Invoke via npx -y @spaceparrots/vex instead of a global vex.
--no-link Skip linking the directory to the environment.
--yes Non-interactive: accept defaults and overwrite an existing vex entry in .mcp.json without asking.

How it treats an existing .mcp.json:

  • Merges, never replaces — only the mcpServers.vex entry is touched. Other servers you've configured are left alone.
  • Asks before overwriting an existing vex entry (--yes skips the prompt).
  • Declining is not an error — the file is left untouched and the exit code is 0.
  • A malformed file is reported, not overwritten.

🔒 Your API key is not written into your project. .mcp.json contains only the environment name; the key stays in ~/.vendure-vex/config.json. .mcp.json is safe to commit.

After it finishes, restart Claude Code so it picks up the new/updated .mcp.json.

Lean or full?

Both can do everything — the difference is how much of Claude's context the tool definitions occupy before you've said a word.

Tools registered Good for
lean (recommended) 6 universal tools (vex_setup, vex_current_env, vex_refetch_schema, vex_query, vex_mutate, vex_schema) Most people. Claude discovers your schema and writes GraphQL itself. Smallest context cost.
full All 15 — the 6 above plus typed tools for products, orders, customers, zones, tax, channels, assets, fragments, and saved operations Heavy, repetitive entity work. The typed tools validate inputs and are harder for Claude to get wrong.

Start with lean. If Claude seems to fumble a task, re-run vex mcp install --tools full.

Note the two different defaults. vex mcp install writes VEX_TOOLS=lean for you. But the server itself defaults to full when VEX_TOOLS is unset — so if you hand-write .mcp.json, set VEX_TOOLS explicitly or you'll get all 15 tools.

Full detail and tradeoffs: MCP Tools Guide → Lean mode.

Step 4 — Verify the connection

Restart Claude Code if you haven't already. Run /mcp in the Claude Code CLI to list connected servers and their tools.

You should see tools prefixed vex_. In lean mode that's exactly six: vex_setup, vex_current_env, vex_refetch_schema, vex_query, vex_mutate, vex_schema. In full mode you'll also see vex_products, vex_orders, and the rest of the entity tools.

If nothing shows up, jump to Troubleshooting.

Step 5 — Try it

Now just describe what you want. A favorite first test — on a dev store, since it writes records:

Create me a dummy order for product "shoes"

Claude will chain several tools automatically: check whether the product exists (creating it if needed), find or create a customer, create a draft order, and add the item — all on its own. That tool-chaining is the whole point of connecting Vex.

Other things to try — each of these is a single prompt:

  • "List my 10 most recent orders."
  • "How many customers do I have whose email contains @example.com?"
  • "What custom fields are configured on the Product entity?"
  • "Add a note to customer 42 saying they called about a refund."

To learn what each tool does, see the MCP Tools Guide.

Safety: what Claude can actually do

Vex gives Claude the same power your API key has — no more, no less. It's worth being deliberate about that.

  • Many tools write. vex_products, vex_orders, vex_customers, vex_zones, vex_tax, vex_channels, and vex_assets all have actions that create, update, or delete. The tool reference marks which.
  • vex_query and vex_mutate are unrestricted. Vex does not inspect the GraphQL document — anything your key is permitted to run will run, including deletes. There is no dry-run and no confirmation step.
  • The API key is your only blast-radius control. Scope it (see Step 1). A read-only key makes a read-only Claude.
  • Point Claude at a dev or staging store first. Ask it "which Vendure environment are you using right now?" (that calls vex_current_env) to confirm before you let it write.
  • Your key sits in plaintext in ~/.vendure-vex/config.json. Treat that file like an SSH private key.

If a permission is missing, Vex doesn't just fail — the error names the denied operation and suggests the Permission values likely required, so you can add exactly what's needed and nothing more.

Beyond the basics

Other MCP clients

vex mcp install covers Claude Code (and any client that reads .mcp.json). If you're wiring up a different MCP client, or you just want to see the JSON without writing a file, print it instead:

vex mcp config                          # active environment, lean tools
vex mcp config --env dev --tools full   # explicit environment + tool mode
vex mcp config --npx                    # invoke via npx instead of a global vex

That prints a snippet like:

{
  "mcpServers": {
    "vex": {
      "command": "vex",
      "args": ["serve"],
      "env": { "VEX_ENV": "dev", "VEX_TOOLS": "lean" }
    }
  }
}

Paste it into your client's MCP config — per project (.mcp.json) or globally (~/.claude.json for Claude Code). If you'd rather invoke via npx (no global install), use vex mcp config --npx, which swaps in { "command": "npx", "args": ["-y", "@spaceparrots/vex", "serve"] }.

Windows: if npx isn't found by your MCP client, wrap it through cmd:

{
  "mcpServers": {
    "vex": { "command": "cmd", "args": ["/c", "npx -y @spaceparrots/vex serve"] }
  }
}

Manage environments by chatting

You don't have to touch the CLI to add or change environments — you can also just ask Claude, and it'll call the vex_setup tool:

Add my Vendure staging server at https://staging.example.com/admin-api with API key sk-1234

Which Vendure environment are you using right now?

That last one uses vex_current_env, which reports the environment plus why it was picked: an explicit env param, VEX_ENV, a project link, or the active environment.

Pin an environment per project

vex mcp install already writes VEX_ENV into .mcp.json for you (and can link the directory too). If you're hand-editing the file instead, set VEX_ENV in the server's env block:

{
  "mcpServers": {
    "vex": {
      "command": "vex",
      "args": ["serve"],
      "env": { "VEX_ENV": "myproject-staging" }
    }
  }
}

Vex picks the environment by a fixed precedence — see Environment resolution precedence for the canonical rule.

⚠️ VEX_ENV and the project link can drift apart. By default vex mcp install writes both, and VEX_ENV outranks the link. If you later re-link the directory (vex env link), the CLI follows the new link but Claude still follows the old VEX_ENV — so your terminal and Claude can end up on different stores. Pick one mechanism, or re-run vex mcp install --env <name> to resync. To see what Claude will use, ask it to call vex_current_env; don't infer it from vex env current in your shell.

Troubleshooting

Symptom Fix
No vex_* tools appear Restart Claude Code after running vex mcp install or editing .mcp.json. Check .mcp.json is in the directory you actually open Claude Code in — running vex mcp install in the wrong folder is the most common cause. Confirm vex serve runs in your terminal (Node 20.19+/22.12+). Run /mcp to see connection status.
vex env add fails: connection refused / timeout Your Vendure server isn't running or isn't reachable at that host. Start it, then retry.
vex env add fails: 404, or the response isn't GraphQL The URL is wrong. It must be the Admin API endpoint ending in /admin-api — not the storefront and not the /admin dashboard. See Step 2.
vex mcp install says "No environments configured — nothing to install" Run vex env add <name> first (Step 2), then re-run vex mcp install.
Windows: "npx not found" / server won't start Use the cmd /c form shown in Other MCP clients, or run vex mcp install without --npx to invoke a globally installed vex instead.
"No environment is configured" error Ask Claude to add one (see Manage environments by chatting), or run vex env add <name> — see CLI Usage.
"API key accepted" fails / 401 Re-check the key, and that tokenMethod includes 'api-key' in your Vendure config. Vendure must be 3.6+.
A FORBIDDEN/UNAUTHORIZED error on a specific operation The API key's role is missing a permission. The error names the operation and suggests likely Permission values — see vex schema permissions in CLI Usage or the vex_schema action list_permissions.
Claude queries a field that doesn't exist / doesn't know about a plugin The cached schema is stale. Ask Claude to call vex_refetch_schema, or run vex schema fetch. vex status shows the cache age.
Claude and the CLI disagree about which environment is in use VEX_ENV in .mcp.json outranks the project link. Compare vex env current (shell) with vex_current_env (Claude) and re-run vex mcp install --env <name> to resync.
Responses are hard to read while debugging Add "VEX_PRETTY_JSON": "1" to the server's env to pretty-print MCP responses (costs ~30% more tokens, so leave it off normally).

Next: MCP Tools Guide · CLI Usage

Vex Wiki

Guides

Vex on GitHub · npm

Clone this wiki locally