Koru VTEX Connector

Install and link a VTEX store to Koru for secure, read-only queries.

Koru VTEX Connector is the app installed inside VTEX. It identifies the current account and workspace and establishes a secure Koru connection without asking for an AppKey, AppToken, or password.

These are two separate apps

The Connector runs in VTEX Admin. Koru VTEX MCP runs in Koru and is the server you later add to ChatGPT or Claude. You need both pieces. If you have not obtained the free app yet, start with the Koru VTEX MCP guide.

Before you start

You need:

permission to install apps in the target VTEX account;
the VTEX IO CLI;
the exact VTEX account and workspace names for your test;
a Koru account with Koru VTEX MCP active, or complete signup from the same Connector journey.

Manual installation during testing

The Connector is not listed in the VTEX marketplace yet. Install it with the CLI. pardosit is the app publisher, not your store account.

Manual VTEX installation

Replace the sample values with your environment:

vtex login YOUR_VTEX_ACCOUNT
vtex use YOUR_WORKSPACE
vtex whoami

Before continuing, vtex whoami must show the exact account and workspace you intend to connect. The production workspace is normally master.

Install the published Connector version

vtex install pardosit.koru-vtex-connector@0.1.8

Confirm if the CLI asks, then verify:

vtex list

The list must include pardosit.koru-vtex-connector@0.1.8.

Open Koru VTEX Connector

Open VTEX Admin, select the same account, and go to Store settings → Koru VTEX Connector.

You can also open the direct route:

https://YOUR_VTEX_ACCOUNT.myvtex.com/admin/koru-vtex-connector

For a workspace other than master, use:

https://YOUR_WORKSPACE--YOUR_VTEX_ACCOUNT.myvtex.com/admin/koru-vtex-connector

The page should show a Not connected status and a Connect with Koru button.

VTEX can take up to 5 minutes

After installation, the sidebar link can appear before VTEX Admin finishes refreshing its cache. If opening it returns a 404, wait up to five minutes and reload the page. Do not reinstall the app during that interval.

Link the store to Koru

Choose “Connect with Koru”

Koru opens with a temporary request signed by VTEX. The Connector tab becomes a terminal state explaining that the flow continues in Koru and can be closed. Do not copy the URL or start another attempt while the request is open.

Use the account that obtained Koru VTEX MCP. Koru shows the store detected by VTEX and never asks for technical credentials.

If you do not have a Koru account yet, this same path lets you create one without losing the Connector request.

Let Koru validate the connection

Choosing Connect with Koru already starts the link; there is no second redundant button that starts it again. Koru shows the detected account and first tries to verify the website automatically using signed Connector evidence.

If the exact public address cannot be verified automatically, Koru offers:

Public HTTPS file: publish the file and exact value at the displayed URL.
DNS record: add the TXT record with the displayed name and value.

Then choose Check verification. Do not alter capitalization, spacing, or the generated value.

Select the store the assistant may query

Review the public address selected during onboarding. Koru does not ask for the same domain again. If that domain has several sales channels, choose the correct one; a single channel is selected automatically. Sales channel and currency are shown under Technical store details only to help distinguish them.

Choose Connect this store. Koru may ask you to sign in again to confirm this sensitive operation.

Confirm the result

The correct result is:

in Koru: Koru VTEX MCP is connected;
in VTEX Admin: Connected;
account and workspace match vtex whoami.

The final screen prioritizes Your store is ready and compacts completed steps so you do not need to scan them again.

Return to the Koru VTEX MCP guide to add the assistant and run the first query.

Access granted

The Connector can query catalog, search, prices, inventory, logistics, and orders, and simulate availability and delivery. Simulation creates no cart or order. Koru cannot change prices, stock, promotions, or orders.

Troubleshooting

VTEX says the app does not exist

Use the complete identifier and exact version:

vtex install pardosit.koru-vtex-connector@0.1.8