MCP Setup

Connect your Vantemo store to AI assistants like Claude, ChatGPT, and Cursor using the Model Context Protocol (MCP). This guide covers setup for each supported client.

Prerequisites

1. A Vantemo store with an active subscription
2. A secret API key (Settings → API Keys → Create Key → Type: Secret)

Important: Use a SECRET key (vt_sk_...) for the MCP server. Publishable keys cannot use the MCP. Restricted keys work if they hold admin:read (read actions) and admin:write (changes), the same rule as the REST admin API: a key with only admin:read can read everything, but every change is refused.

Quick Start

npx @vantemo/mcp --api-key vt_sk_live_YOUR_KEY

The server will introspect your API key, discover your shop, and start listening for MCP tool calls via stdio.

Client Configuration

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vantemo": {
      "command": "npx",
      "args": ["@vantemo/mcp", "--api-key", "vt_sk_live_YOUR_KEY"]
    }
  }
}

Restart Claude Desktop after saving. You should see "Vantemo" in the tools list.

Claude Code (CLI)

Add to your project's .mcp.json or global ~/.claude/mcp.json:

{
  "mcpServers": {
    "vantemo": {
      "command": "npx",
      "args": ["@vantemo/mcp", "--api-key", "vt_sk_live_YOUR_KEY"]
    }
  }
}

Cursor

Open Cursor Settings → MCP Servers → Add Server:

{
  "vantemo": {
    "command": "npx",
    "args": ["@vantemo/mcp", "--api-key", "vt_sk_live_YOUR_KEY"]
  }
}

ChatGPT Desktop

ChatGPT supports MCP servers via its plugin system. Add a new MCP server with:

• Command: npx
• Arguments: @vantemo/mcp --api-key vt_sk_live_YOUR_KEY

Environment Variables

Instead of passing the key as an argument, you can use environment variables:

{
  "mcpServers": {
    "vantemo": {
      "command": "npx",
      "args": ["@vantemo/mcp"],
      "env": {
        "VANTEMO_API_KEY": "vt_sk_live_YOUR_KEY"
      }
    }
  }
}

Local Development

To connect to a local API server:

npx @vantemo/mcp --api-key vt_sk_test_YOUR_KEY --api-url http://localhost:4001

Or in your MCP config:

{
  "mcpServers": {
    "vantemo-dev": {
      "command": "npx",
      "args": [
        "@vantemo/mcp",
        "--api-key", "vt_sk_test_YOUR_KEY",
        "--api-url", "http://localhost:4001"
      ]
    }
  }
}

Verify It Works

Once connected, try these prompts with your AI assistant:

• "List all my products"
• "Show me this week's revenue"
• "Create a product called Test Widget at €25"
• "What are my top-selling products this month?"

Troubleshooting

"Invalid API key format"

Make sure your key starts with vt_. If you're using a key from another service (Stripe, OpenAI), that won't work.

"Failed to introspect API key"

• Check that your API key is valid and not revoked (Settings → API Keys)
• Verify the API URL is correct (default: https://api.vantemo.com)
• If using --api-url, make sure the API server is running

"Publishable API keys cannot use the MCP"

You're using a publishable key (vt_pk_...). Switch to a secret key (vt_sk_...) for full admin access.

"This restricted API key lacks the "admin:write" scope"

Your restricted key (vt_rk_...) can read but not make changes. Add admin:write to the key (Settings → API Keys), or use a secret key. The same message naming admin:read means the key cannot read either.

Tools not showing up in client

• Restart your AI client after updating the MCP config
• Check that npx is in your PATH
• Run the server manually to check for errors: npx @vantemo/mcp --api-key YOUR_KEY --verbose

Next Steps

• Tools Reference — See all available tools and actions
• MCP Overview — Architecture and security model
• Managing with AI — Practical use cases