Vendure Core v3.8: An MCP Server for Your Store, Improved Security, and More

Vendure Core v3.8 is out, and it's a big one: 340 pull requests from 45 contributors since our last feature release.

The headline feature is a first-party MCP server. AI agents can now work with a Vendure store by calling real store operations, and they're bound by the same permissions and access control system you are already using. We've also done a good amount of security hardening, with encrypted secret fields and API-bound sessions. On top of that we've extended custom fields and data modelling, improved price handling, refreshed the Dashboard with v2 of the Vendure design system, and moved to NestJS 12 and Apollo Server 5, with opt-in support for TypeORM v1.

3.8 is a minor release, but it does contain schema changes and a few changes in behaviour. Please read Upgrading and Breaking Changes before you update.

An MCP Server for Your Store

The Model Context Protocol (MCP) is the open standard that AI agents use to discover and call tools on a server. In v3.8 we're shipping two new packages that let Vendure act as an MCP server (#5262).

@vendure/mcp-plugin exposes your store through 42 built-in tools: 18 in the shop toolset and 24 in the admin toolset. @vendure/mcp-sdk lets any plugin register its own tools with the @McpTool decorator.

We spent a lot of time on the design to make it as "Vendure-native" as possible: tools are classes with a new @McpTool() decorator, we use the exact same roles & permissions system you already know, and your tools can inject any services and do anything that regular Vendure code can do. This allows you to expose functionality to agents without worrying about the complexities and nuances of the protocol, authentication, access control, etc.

What the Built-in Tools Cover

The shop toolset covers the catalog (search_products, get_product, list_collections), the cart (add_to_cart, apply_coupon_code), checkout (set_checkout_details, set_shipping_method, place_order), and the signed-in customer's orders and account.

The admin toolset covers products and variants, orders, customers, stock, channels and asset upload, with tools such as list_orders, refund_order, adjust_stock and upload_asset.

This means you can get started with both customer-facing functionality as well as tools to allow your store operators to manage the store via AI agents.

Permissions and Consent

Agents are bound by the same permission model as the rest of your store.

• Permissions. Each tool declares the Permission values it needs, in exactly the same way you are used to from your custom GraphQL resolver functions.
• Safety classes. Each tool is classed as readonly, mutating or destructive. These are hints to the agent as to how safe or how much caution should be taken when calling the tool. Destructive covers things like place_order, refund_order and cancel_order, and triggers a confirmation before carrying out the tool call.
• Toggles. Administrators can switch off individual tools on the Tools page of the new MCP Server section in the Dashboard (see Administration). A disabled tool disappears from the tool list and can't be called.

The plugin supports two kinds of assistant. An assistant that runs inside your Vendure server, such as a chat assistant you build as a plugin, calls tools directly. It needs no browser, consent page or token. An assistant that runs outside your server uses OAuth with consent, and acts on behalf of a signed-in customer or administrator.

Getting Started

npm install @vendure/mcp-plugin

import { McpPlugin } from '@vendure/mcp-plugin';const config: VendureConfig = {    plugins: [        // Tools are exposed directly by default. Pass `toolExposure: 'discovery'`        // to expose a small set of search/execute meta-tools instead.        McpPlugin.init({}),    ],};

The MCP Server Quick Start walks you through the setup, and our docs also feature an extensive set of guides covering all aspects of creating agentic tooling using the MCP SDK.

Security Hardening

Secret Fields Encrypted at Rest

You can now mark custom fields and configurable-operation arguments as secret: true. The value gets encrypted in the database and redacted in API responses (#5051).

import { DefaultEncryptionStrategy, VendureConfig } from '@vendure/core';export const config: VendureConfig = {    // ...    systemOptions: {        encryptionStrategy: new DefaultEncryptionStrategy({            secret: process.env.VENDURE_ENCRYPTION_KEY,        }),    },    customFields: {        Customer: [{ name: 'externalApiKey', type: 'string', secret: true }],    },};

For a configurable operation such as a payment method handler, you set secret: true on a string arg in the same way.

Reading the decrypted value requires Permission.ReadSecret, which by default only the SuperAdmin has.

Read more about how to set up and use secret fields in our new Secret Fields developer guide.

Sessions Bound to the API They Were Created For

Every session now records which API it was created for, and the Admin API only accepts sessions that were created for the Admin API. Sessions created before the upgrade don't carry an API type, so every administrator will need to log in again once after you upgrade. API keys created before the upgrade keep working.

If you write custom authentication strategies or create sessions yourself, for example in a REST controller that completes an SSO callback, pass 'admin' as the apiType argument. The Migration Guide covers the details. Many thanks to the researchers who responsibly reported this issue. See GHSA-5fpx-9m35-w745 for more details.

A Tighter RequestContext

The RequestContext is an integral API that is used throughout Vendure projects. This release makes it harder to inadvertently leak sensitive data when serializing the context inside your application.

This builds on the earlier fix for GHSA-32jm-mf7r-7qw5, which was released in 3.7.3. A serialized RequestContext is now built from an explicit allowlist of fields, so job data will never contain the session token or request headers.

The visible effect of this is that ctx.session.token is now string | undefined, and on a job queue worker it is always undefined. If a job needs a credential, pass it in the job payload or use a service-level credential. All the security fixes from the 3.7.x patch releases are also included in 3.8.0.

Custom Fields and Data Modelling

Most Vendure projects rely heavily on custom fields to model their own business, so we've filled in a few gaps here.

Relations and Indexes

• Relation custom fields now expose their entity IDs in the GraphQL APIs (#5012, #5013).
• Relation custom fields support cascade options (#4448).
• Custom fields can be indexed (#5074).

More Entities Take Custom Fields

Role now supports custom fields (#5250), and the role detail page in the Dashboard supports them too. Seller now supports localized custom fields (#5198), which adds a seller_translation table.

Orders and Checkout

Fresher Pricing for Long-Lived Carts

If a cart sits around for a few days, it can end up showing prices and promotions that no longer apply. The new OrderRecalculationStrategy lets you decide when an active order gets recalculated on read (#4928). There's a built-in TTL strategy which recalculates any order whose pricing is older than a limit you set:

orderOptions: {    orderRecalculationStrategy: new TtlOrderRecalculationStrategy({ ttlMs: 5 * 60 * 1000 }),},

This is opt-in. The default, NoOrderRecalculationStrategy, keeps the existing behaviour.

Checkout Re-checks Shipping

When an order moves to ArrangingPayment, the default order process now recalculates it: prices, promotions, taxes and shipping promotions, without changing the selected shipping method. If that shipping method is no longer eligible, the transition is refused with an OrderStateTransitionError.

Your storefront should handle that error by re-querying eligibleShippingMethods, letting the customer choose again, and then retrying. It should also re-read the order totals after the transition, since they may have changed since the customer last saw them.

Refunds and Stock

Refund destinations are now pluggable (#4594), so you can, for example, send a refund to store credit instead of back to the original payment method. When stock allocation falls short, Vendure now publishes a StockShortfallEvent (#4930), which you can hook into for alerts or backorder logic.

Dashboard

Refreshed with Design System v2

The Dashboard now runs on v2 of the Vendure design system (#4957, #5502, #5545), including updated shell navigation (#4995). This is mainly a refresh of the look and layout, so your team will still find everything where they expect it. Administrators can now set avatar images in the dashboard too.

If you have Dashboard extensions, rebuild them and give them a visual check. The move to @vendure-io/ui 2.0 can change how they render.

Extensibility

• setValuesForCreate on useDetailPage and DetailPage lets a create page start out with values from the route, such as params => ({ companyId: params.companyId }) (#5431).
• Page blocks can now have descriptions (#5050).
• Navigation and route visibility can depend on the current user (#5156).

Admin Workflows

Administrators now get a password reset flow with email support (#4974). The Admin API has a new verifyCustomerAccount mutation (#4773). When you update a Product, ProductVariant or Collection, the Dashboard now only sends the fields that changed (#4916). That makes updates smaller, but it also changes what your handlers receive, so check the breaking changes below.

Platform Foundations

NestJS 12 and Apollo Server 5

Vendure now runs on NestJS 12, @nestjs/graphql 14 and Apollo Server 5 (#5386). Make sure any direct dependencies in your project and plugins are on matching versions. Mismatches usually show up as dependency injection errors at bootstrap.

TypeORM v1, Opt-in

@vendure/core now runs on both TypeORM v1.x and v0.3 from the same code (#5106, #5122), and we have a dedicated CI job that checks both on every commit. Nothing changes unless you opt in. Core still depends on typeorm ^0.3.21, so existing and new projects stay on v0.3. To move to v1, you force the version using your package manager's overrides, resolutions or pnpm.overrides field. You don't need a database migration, because TypeORM v1 generates the same schema.

Check the TypeORM v1 section of the release notes for more detail on how to incorporate the latest TypeORM version into your application.

CLI

The CLI now has a plugin API, so plugins can add their own commands.

• Plugin commands. Plugins can register and override commands, with nested command trees, shared options, and commands that have both an action and subcommands (#5139, #5263, #5300). Help output is grouped by the package that provides each command (#5358).
• Migrations. migrate can create the initial migration from an empty database (#4959).
• Setups. The CLI supports globally installed CLI and plugin packages (#5400), and vendure dev discovers workspace projects (#5475).

The CLI also includes full support for the Vendure Console, our home for our new suite of product plans and the future home of our Vendure Cloud hosted platform - more on that at the end of this post.

You can run npx vendure console link to get started with a free account.

Performance

Server and worker bootstrap are faster (#5170). These are the median times measured in the PR:

NODE_COMPILE_CACHE is a Node.js feature that you can turn on in your deployment with an environment variable and a warm-up step in your Docker build.

We also cut down the number of database queries in a few places:

• Product.facetValues lookups are now batched per request. Previously, product lists ran several queries per product (#5546).
• Eager relations are joined when using the query relation load strategy (#5193).
• We added missing indexes on STI discriminator columns and search_index_item.productId (#5287).
• List queries no longer load the channels relation when they don't need it (#5368). If a plugin of yours reads entity.channels from list results, add channels to the relations option. For applications with many channels, you may see significant improvements in response times and memory usage for certain list queries.

Upgrading and Breaking Changes

Due to some of the new features we've added in this release, as well as certain security fixes that were made, there are some actions needed from your side during the migration.

The v3.8.0 Migration Guide covers everything you need to know.

Thank You

45 people contributed to this release, 37 of them from our community and of them, 22 were first-time contributors!

A big thank you to the community members who contributed code to v3.8: @Ryrahul, @brmk, @wakqasahmed, @GabrielRoc, @ryandiginomad, @latifniz, @supermadu7, @kwerie, @kevmtt, @ivanvasyliuk, @TheHypnoo, @sridharkalaibala, @casperiv0, @brbousnguar, @TheStreamCode, @MillisJn, @LucidityDesign, @Ismatulla, @thomslbua, @tbouliere-datasolution, @psang39, @mistuttodos, @mhouel-coexya, @lucatk, @knoid, @imanali2237, @deep231w, @cuyl, @comega-johan, @atistrcsn, @SupunGeethanjana, @StefanOrzu, @SiebelsTim, @Sanjuhub, @PavanendraBaahubali, @Lennix and @Hemang-ai.

Thanks also to the security researchers who reported the issues fixed in this release through GitHub security advisories.

Beyond the Open-Source Core

Vendure Core is and stays open source. For teams that need more, Vendure now has four paid plans: Starter, Growth, Scale and Enterprise. Depending on the plan, they add our commercial B2B layer: company accounts, quotes, organisation hierarchies, contract pricing, order approvals, single sign-on and audit logs. You can start a free trial of Starter, Growth or Scale from the pricing page, and Enterprise is arranged by contract.

Paid plans also get access to Vendure Cloud, our fully managed platform for running Vendure. It opens first as a closed beta for paid plans, and general availability is planned for Q1 2027.

See the plans