MCP Server

The Vantemo MCP (Model Context Protocol) server allows AI assistants like Claude, ChatGPT, and Cursor to directly interact with your store's API. Instead of manually writing API calls or navigating the admin dashboard, you describe what you want in natural language and the AI executes it.

What is MCP?

The Model Context Protocol is an open standard created by Anthropic that enables AI assistants to use external tools. Think of it as a universal plugin system for AI — the MCP server exposes your store's capabilities as "tools" that the AI can call.

Architecture

┌─────────────┐     stdio      ┌──────────────┐     HTTPS     ┌──────────────┐
│  AI Client  │ ◄────────────► │  MCP Server  │ ◄───────────► │ Vantemo API  │
│  (Claude)   │                │  (local)     │               │  (cloud)     │
└─────────────┘                └──────────────┘               └──────────────┘

The MCP server runs locally on your machine and communicates with the AI client via stdio. It authenticates to the Vantemo API using your secret API key.

How it Works

1. Startup: The MCP server calls GET /v1/api-key/me to introspect the API key and discover which shop it belongs to.
2. Tool Registration: 11 tool groups are registered with the AI client, each covering a domain (catalog, orders, analytics, etc.).
3. Tool Calls: When the AI selects a tool, the MCP server resolves the action, checks scopes, calls the API, and returns results.
4. Safety: Destructive actions require explicit confirmation. Scope checks prevent unauthorized access.

Installation

npx @vantemo/mcp --api-key vt_sk_live_YOUR_KEY

Or configure it in your AI client's MCP settings:

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

Dynamic Tool Groups (11 tools, not 393)

LLMs perform poorly when presented with 40+ tools. Instead of exposing all 393 API endpoints individually, the MCP server organizes them into 11 tool groups. Each group is a meta-tool with an action parameter that selects the specific operation.

See the Tools Reference for the complete action list.

Security

• Local execution: The MCP server runs on your machine — your API key never leaves your device
• Scope enforcement: API key scopes are checked before every action. PUBLISHABLE keys only get storefront read access
• Destructive action gating: DELETE operations require explicit confirm: true parameter
• MCP tool annotations: Standard readOnlyHint, destructiveHint, and idempotentHint annotations help clients show appropriate UI
• Rate limiting: The API server enforces per-key rate limits. 429 errors are relayed to the AI
• Audit logging: Every action is logged to stderr as structured JSON for compliance
• PII awareness: The customers:read scope grants access to customer PII (email, name, IP address, user agent). Use restricted keys with only the scopes you need, especially when connecting to AI assistants that may log or transmit data to third parties

CLI Options

npx @vantemo/mcp --api-key <key> [options]

Options:
  --api-key <key>   Vantemo API key (or VANTEMO_API_KEY env var)
  --api-url <url>   API base URL (default: https://api.vantemo.com)
  --verbose         Enable debug logging
  --help            Show help

Next Steps

• Tools Reference — Complete list of MCP tool groups and actions
• MCP Setup — Client-specific configuration
• Managing with AI — Practical use cases