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: 9 tool groups are registered with the AI client, each covering a domain (catalog, orders, analytics, etc.) as a read tool plus, for groups that can change data, a _write tool for changes that are easy to undo and a _confirm tool for the rest.
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: Deletes, money, stock and live-shop changes are flagged so the client asks your approval on every call. Scope checks prevent unauthorized access. Responses are marked as untrusted data.

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 (9 groups, not one tool per endpoint)

LLMs perform poorly when presented with 40+ tools. Instead of exposing one tool per API endpoint, the MCP server organizes its 130 actions into 9 tool groups. Each group is exposed as a read tool (catalog) and, for its write actions, up to two more: catalog_write (changes that are easy to undo) and catalog_confirm (changes that ask your approval first). All are meta-tools 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, by the same rule as the REST admin API: read actions need admin:read, every change needs admin:write. PUBLISHABLE keys are refused
• Human approval for risky changes: Deletes, prices, coupons, stock, shipping, order status, store-wide settings and live-shop changes run only through a _confirm tool. _confirm tools carry _meta["anthropic/requiresUserInteraction"], so Claude Code prompts you on every call; the AI cannot approve on your behalf. Changes that are easy to undo (new items, text edits, photos) run through a _write tool, which is not flagged and runs without a prompt when you allow the server's tools. Other clients should be set to ask before every *_confirm call. See Approval tiers
• MCP tool annotations: Read tools are annotated readOnlyHint; _write and _confirm tools destructiveHint
• Untrusted-content marking: Every API response and API error body is wrapped in a randomly tagged <untrusted_content_…> block so text written by customers or visitors is treated as data, not instructions
• Rate limiting: Each API key allows 60 requests per minute by default. On a rate-limit 429 the AI is told how many seconds to wait
• Audit logging: Every action is logged to stderr as structured JSON for compliance
• PII awareness: admin:read reads every resource, customer PII (email, name, IP address, user agent) included; there is no narrower read scope. Keep that in mind when connecting 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