MCP server

Connect your Vendu e-commerce store to any AI assistant that supports the Model Context Protocol.

Quick Start

Option A: OAuth (Claude Desktop, Cursor)

Your MCP client will handle authentication automatically:

{
  "mcpServers": {
    "vendu": {
      "url": "https://vendu.space/api/mcp"
    }
  }
}

When you first connect, you'll be redirected to Vendu to authorize access. By default this grants read only — a client has to request scope=read write explicitly to also get the write tools; there's no way to end up with write access by omission.

Option B: API Key

Go to Settings → Integrations → API Keys in your Vendu dashboard
Create a key with the scopes you need (read, write)
Add to your MCP client config:

{
  "mcpServers": {
    "vendu": {
      "url": "https://vendu.space/api/mcp",
      "headers": {
        "Authorization": "Bearer vndu_your_key_here"
      }
    }
  }
}

Available Tools

23 tools total (13 read, 10 write). Every tool is scoped to your workspace automatically — there's no tenant_id to pass, it comes from the key or token.

Read Tools (scope: `read`)

Tool	Description
`get_orders`	Get recent orders. Filter by status, date, customer.
`get_conversations`	Get customer conversations. Filter by platform, AI status.
`get_products`	Search your product catalog by name, category, stock.
`get_contacts`	Get customer contacts with conversation summary.
`get_analytics`	Store analytics: orders, revenue, AI performance (today/7d/30d).
`get_ai_config`	View your AI assistant config: tone, language, knowledge base.
`get_messages`	Read messages from a specific conversation.
`get_escalations`	Escalations waiting for review — the AI's draft, why it escalated, confidence.
`get_order`	One order in full, including its status history (who changed it, from what, to what, why).
`get_conversation_trace`	The AI trace for a conversation: model, confidence, tokens/cost, tools called — for debugging "why did the bot say that".
`get_knowledge_items`	List knowledge-base articles, with whether each is actually indexed for retrieval.
`get_knowledge_item`	One knowledge-base article, in full.
`search_products_semantic`	Run the real production RAG pipeline for a query and see exactly what the AI would find. Costs a classification call and an embedding call.

Write Tools (scope: `write`)

Tool	Description
`reply_to_conversation`	Sends a message to the customer on their channel, records it, and pauses AI auto-replies for that conversation — a human has taken over.
`update_order_status`	Moves an order through its lifecycle. An invalid transition is rejected with the list of valid targets.
`tag_contact`	Adds a tag to a contact, for segmentation and automation triggers.
`update_ai_persona`	Update AI tone, language, custom instructions, auto-reply on/off.
`pause_ai_for_contact`	Pause/resume AI auto-replies for a conversation.
`resolve_escalation`	Resolve a pending escalation: approve the AI's draft, send an edited reply, take over (pause with no message), or dismiss.
`add_knowledge_item`	Add an article to the knowledge base; it's queued for embedding immediately.
`update_knowledge_item`	Update a knowledge-base article's title, content, enabled or pinned state.
`create_order`	Create an order for a customer. Every line item must reference an existing catalog product — price, name and stock come from the catalog, never from the caller. Supports an `idempotency_key` so a retried call is safe.
`simulate_customer_message`	Run a message through your workspace's real AI pipeline (triage, catalog search, sales agent, safety critic) and get back the reply it would send — without touching any real conversation. Requires `write` scope because it costs a real model call, not because it changes data.

Order statuses (get_orders's status filter and update_order_status's status) are upper-case: DRAFT, PENDING, CONFIRMED, PAID, PROCESSING, SHIPPED, DELIVERED, COMPLETED, RETURNED, CANCELED.

Prompts

Three ready-made prompts (prompts/list / prompts/get) your MCP client can offer as one-click workflows. A prompt just seeds an instruction; your client's own model decides how to follow it and calls the tools itself.

Prompt	Scope needed	Arguments	What it does
`morning_report`	`read`	`language` (optional)	A 5-line briefing: today's revenue/orders, AI performance, pending escalations, orders needing attention, one suggested action.
`review_escalations`	`write`	none	Works through every pending escalation and resolves each one via `resolve_escalation`.
`test_agent`	`write`	`scenario` (required), `turns` (optional, default 3)	Plays a customer scenario against your real agent via `simulate_customer_message` and scores each reply against a safety/quality checklist.

Rate limits

MCP calls share the same rate limiter as the REST API (see Rate limits), with one difference: scope is decided per tool call, not per HTTP verb, since every MCP request is a POST. Any tool named get_* counts as read; everything else counts as write. A batch of JSON-RPC calls takes the strictest scope present — one write call in a batch makes the whole batch count against the write bucket.

Plan	Read / min	Write / min
free	30	5
starter	60	15
professional	120	30
business	300	60
enterprise	600	120

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds). At the limit, the server answers with a JSON-RPC error (code: -32000, message: "Rate limit exceeded") and a Retry-After header — this is a JSON-RPC error object, not the application/problem+json body the REST API returns at 429.

Audit

Every write tool call — including resolve_escalation, create_order, the knowledge-base writes, and even simulate_customer_message's run — is written to your workspace's audit log:

API-key calls are attributed to the key itself.
OAuth calls are attributed to the user who authorized the connection.

A failed audit write never blocks or undoes the action it documents — it's a side channel, not a gate.

Authentication

The server supports two authentication methods:

API Key: Authorization: Bearer vndu_xxxxx — create in Settings → Integrations, scoped per key. This is a different key from the REST API key (vk_live_…, Settings → Developers) used for /api/v1/*; neither works on the other surface.
OAuth 2.1: Full PKCE flow with dynamic client registration — used by Claude Desktop, Cursor, etc. Request scope=read write explicitly to get write access; an omitted or empty scope grants read only.

OAuth Endpoints

Endpoint	URL
Authorization Server Metadata	`GET /.well-known/oauth-authorization-server`
Dynamic Client Registration	`POST /api/oauth/register`
Authorization	`GET /oauth/authorize`
Token Exchange	`POST /api/oauth/token`
MCP Endpoint	`POST /api/mcp`

Protocol

Transport: Streamable HTTP (stateless)
Protocol: JSON-RPC 2.0 (single & batch)
MCP Version: 2025-03-26

Examples

Ask about orders

"Show me all pending orders from the last 7 days"

The AI calls get_orders with { "status": "PENDING", "since": "2026-08-30T00:00:00Z" }. Note the upper-case status.

Check analytics

"How is my store performing this week?"

The AI calls get_analytics with { "period": "7d" } and summarizes revenue, order count, and AI performance.

Adjust AI behavior

"Make the AI more formal and respond in English"

The AI calls update_ai_persona with { "tone": "formal", "language": "en" }.

Test how your agent would answer (write scope)

"See how the bot would respond if a customer asked whether the red dress comes in size M"

The AI calls simulate_customer_message with { "message": "Do you have the red dress in size M?" } and returns the reply your real pipeline would generate — no real conversation is touched, but the call is billed like any other AI response.

Morning briefing

Run the morning_report prompt. Your client fetches today's analytics, pending escalations, and orders awaiting confirmation, and summarizes all of it in 5 lines.

Testing your agent through MCP

You (or your CI) can exercise your workspace's live AI configuration without opening the dashboard or touching a real customer conversation, combining three tools:

simulate_customer_message — play a scenario against your real pipeline (triage, RAG, sales agent, critic) with your real catalog and knowledge base, and every side-effecting integration mocked (nothing is charged, shipped, or sent to a customer).
get_conversation_trace — see why a real conversation's agent behaved the way it did. (This reads an existing conversation's history — a simulated run isn't a real conversation, so use the debug field simulate_customer_message already returns instead.)
search_products_semantic — run the exact retrieval path production uses, to check what the agent would actually find for a given question.

Before wiring this into an automated test suite, know what it costs:

simulate_customer_message makes real model calls (triage, sales agent, and the safety critic each call a model) and is billed like production traffic. It requires write scope for that reason, not because it writes any data.
search_products_semantic always runs the full pipeline — a classification call plus an embedding call on every invocation, with no cheaper fallback path.
AI_MODE=mock only applies to local development and test environments — it has no effect on the production /api/mcp endpoint. A real MCP call against https://vendu.space/api/mcp always uses real models and incurs real cost. Point automated regression checks at a mock-mode local or staging instance rather than looping these tools against production.
All three tools are still subject to the rate limits above.

What the assistant can change

Read tools are available with the read scope. The following require write, and each one is deliberately narrow:

Tool	What it does
`reply_to_conversation`	Sends a message to the customer on their channel, records it in the conversation, and pauses AI auto-replies — a human has taken over. An identical message within a minute is refused, because a retried tool call would otherwise reach the customer twice.
`update_order_status`	Moves an order through its lifecycle. A transition the lifecycle forbids is rejected with the list of valid targets; the change carries the same lock, audit row and event as a change made in the dashboard.
`tag_contact`	Adds a tag to a contact, for segmentation and automation triggers.
`update_ai_persona`	Tone, language, custom instructions, auto-reply on/off.
`pause_ai_for_contact`	Pauses or resumes AI replies for one conversation.
`resolve_escalation`	Approves, edits, dismisses, or hands off a pending escalation — reuses the same outbound-delivery path as `reply_to_conversation`.
`add_knowledge_item` / `update_knowledge_item`	Adds or edits a knowledge-base article the AI is grounded on; re-embeds automatically.
`create_order`	Creates one order, through the same validated path the dashboard's "create order" form uses.
`simulate_customer_message`	Runs your agent against a test message. Writes nothing to a real conversation — gated on `write` because it costs a real model call.

What the server will never do

Installing apps, changing scopes, setting credentials, touching billing or managing the team are not available over MCP, and will not be.

The line is not read-versus-write — replying to a customer is a write and it is fine. It is whether the effect outlives the conversation and then acts on its own. A reply is one message a person can see and correct; an installed app is a standing grant that keeps calling an external endpoint long after the conversation ended.

This matters because the same assistant reads customer messages, and a customer's message is text an attacker controls. Every tool above has a bounded worst case. "Install an app" would not.

Configuration belongs in the dashboard, in front of someone who can see what they are approving.

Support

Dashboard: vendu.space
Documentation: vendu.space/docs/developers/mcp
Email: support@vendu.space

Connect your Vendu e-commerce store to any AI assistant that supports the Model Context Protocol.

Quick Start

Option A: OAuth (Claude Desktop, Cursor)

Your MCP client will handle authentication automatically:

{
  "mcpServers": {
    "vendu": {
      "url": "https://vendu.space/api/mcp"
    }
  }
}

Option B: API Key

Go to Settings → Integrations → API Keys in your Vendu dashboard
Create a key with the scopes you need (read, write)
Add to your MCP client config:

{
  "mcpServers": {
    "vendu": {
      "url": "https://vendu.space/api/mcp",
      "headers": {
        "Authorization": "Bearer vndu_your_key_here"
      }
    }
  }
}

Available Tools

23 tools total (13 read, 10 write). Every tool is scoped to your workspace automatically — there's no tenant_id to pass, it comes from the key or token.

Read Tools (scope: `read`)

Tool	Description
`get_orders`	Get recent orders. Filter by status, date, customer.
`get_conversations`	Get customer conversations. Filter by platform, AI status.
`get_products`	Search your product catalog by name, category, stock.
`get_contacts`	Get customer contacts with conversation summary.
`get_analytics`	Store analytics: orders, revenue, AI performance (today/7d/30d).
`get_ai_config`	View your AI assistant config: tone, language, knowledge base.
`get_messages`	Read messages from a specific conversation.
`get_escalations`	Escalations waiting for review — the AI's draft, why it escalated, confidence.
`get_order`	One order in full, including its status history (who changed it, from what, to what, why).
`get_conversation_trace`	The AI trace for a conversation: model, confidence, tokens/cost, tools called — for debugging "why did the bot say that".
`get_knowledge_items`	List knowledge-base articles, with whether each is actually indexed for retrieval.
`get_knowledge_item`	One knowledge-base article, in full.
`search_products_semantic`	Run the real production RAG pipeline for a query and see exactly what the AI would find. Costs a classification call and an embedding call.

Write Tools (scope: `write`)

Tool	Description
`reply_to_conversation`	Sends a message to the customer on their channel, records it, and pauses AI auto-replies for that conversation — a human has taken over.
`update_order_status`	Moves an order through its lifecycle. An invalid transition is rejected with the list of valid targets.
`tag_contact`	Adds a tag to a contact, for segmentation and automation triggers.
`update_ai_persona`	Update AI tone, language, custom instructions, auto-reply on/off.
`pause_ai_for_contact`	Pause/resume AI auto-replies for a conversation.
`resolve_escalation`	Resolve a pending escalation: approve the AI's draft, send an edited reply, take over (pause with no message), or dismiss.
`add_knowledge_item`	Add an article to the knowledge base; it's queued for embedding immediately.
`update_knowledge_item`	Update a knowledge-base article's title, content, enabled or pinned state.
`create_order`	Create an order for a customer. Every line item must reference an existing catalog product — price, name and stock come from the catalog, never from the caller. Supports an `idempotency_key` so a retried call is safe.
`simulate_customer_message`	Run a message through your workspace's real AI pipeline (triage, catalog search, sales agent, safety critic) and get back the reply it would send — without touching any real conversation. Requires `write` scope because it costs a real model call, not because it changes data.

Prompts

Prompt	Scope needed	Arguments	What it does
`morning_report`	`read`	`language` (optional)	A 5-line briefing: today's revenue/orders, AI performance, pending escalations, orders needing attention, one suggested action.
`review_escalations`	`write`	none	Works through every pending escalation and resolves each one via `resolve_escalation`.
`test_agent`	`write`	`scenario` (required), `turns` (optional, default 3)	Plays a customer scenario against your real agent via `simulate_customer_message` and scores each reply against a safety/quality checklist.

Rate limits

Plan	Read / min	Write / min
free	30	5
starter	60	15
professional	120	30
business	300	60
enterprise	600	120

Audit

Every write tool call — including resolve_escalation, create_order, the knowledge-base writes, and even simulate_customer_message's run — is written to your workspace's audit log:

API-key calls are attributed to the key itself.
OAuth calls are attributed to the user who authorized the connection.

A failed audit write never blocks or undoes the action it documents — it's a side channel, not a gate.

Authentication

The server supports two authentication methods:

API Key: Authorization: Bearer vndu_xxxxx — create in Settings → Integrations, scoped per key. This is a different key from the REST API key (vk_live_…, Settings → Developers) used for /api/v1/*; neither works on the other surface.
OAuth 2.1: Full PKCE flow with dynamic client registration — used by Claude Desktop, Cursor, etc. Request scope=read write explicitly to get write access; an omitted or empty scope grants read only.

OAuth Endpoints

Endpoint	URL
Authorization Server Metadata	`GET /.well-known/oauth-authorization-server`
Dynamic Client Registration	`POST /api/oauth/register`
Authorization	`GET /oauth/authorize`
Token Exchange	`POST /api/oauth/token`
MCP Endpoint	`POST /api/mcp`

Protocol

Transport: Streamable HTTP (stateless)
Protocol: JSON-RPC 2.0 (single & batch)
MCP Version: 2025-03-26

Examples

Ask about orders

"Show me all pending orders from the last 7 days"

The AI calls get_orders with { "status": "PENDING", "since": "2026-08-30T00:00:00Z" }. Note the upper-case status.

Check analytics

"How is my store performing this week?"

The AI calls get_analytics with { "period": "7d" } and summarizes revenue, order count, and AI performance.

Adjust AI behavior

"Make the AI more formal and respond in English"

The AI calls update_ai_persona with { "tone": "formal", "language": "en" }.

Test how your agent would answer (write scope)

"See how the bot would respond if a customer asked whether the red dress comes in size M"

Morning briefing

Run the morning_report prompt. Your client fetches today's analytics, pending escalations, and orders awaiting confirmation, and summarizes all of it in 5 lines.

Testing your agent through MCP

You (or your CI) can exercise your workspace's live AI configuration without opening the dashboard or touching a real customer conversation, combining three tools:

simulate_customer_message — play a scenario against your real pipeline (triage, RAG, sales agent, critic) with your real catalog and knowledge base, and every side-effecting integration mocked (nothing is charged, shipped, or sent to a customer).
get_conversation_trace — see why a real conversation's agent behaved the way it did. (This reads an existing conversation's history — a simulated run isn't a real conversation, so use the debug field simulate_customer_message already returns instead.)
search_products_semantic — run the exact retrieval path production uses, to check what the agent would actually find for a given question.

Before wiring this into an automated test suite, know what it costs:

simulate_customer_message makes real model calls (triage, sales agent, and the safety critic each call a model) and is billed like production traffic. It requires write scope for that reason, not because it writes any data.
search_products_semantic always runs the full pipeline — a classification call plus an embedding call on every invocation, with no cheaper fallback path.
AI_MODE=mock only applies to local development and test environments — it has no effect on the production /api/mcp endpoint. A real MCP call against https://vendu.space/api/mcp always uses real models and incurs real cost. Point automated regression checks at a mock-mode local or staging instance rather than looping these tools against production.
All three tools are still subject to the rate limits above.

What the assistant can change

Read tools are available with the read scope. The following require write, and each one is deliberately narrow:

Tool	What it does
`reply_to_conversation`	Sends a message to the customer on their channel, records it in the conversation, and pauses AI auto-replies — a human has taken over. An identical message within a minute is refused, because a retried tool call would otherwise reach the customer twice.
`update_order_status`	Moves an order through its lifecycle. A transition the lifecycle forbids is rejected with the list of valid targets; the change carries the same lock, audit row and event as a change made in the dashboard.
`tag_contact`	Adds a tag to a contact, for segmentation and automation triggers.
`update_ai_persona`	Tone, language, custom instructions, auto-reply on/off.
`pause_ai_for_contact`	Pauses or resumes AI replies for one conversation.
`resolve_escalation`	Approves, edits, dismisses, or hands off a pending escalation — reuses the same outbound-delivery path as `reply_to_conversation`.
`add_knowledge_item` / `update_knowledge_item`	Adds or edits a knowledge-base article the AI is grounded on; re-embeds automatically.
`create_order`	Creates one order, through the same validated path the dashboard's "create order" form uses.
`simulate_customer_message`	Runs your agent against a test message. Writes nothing to a real conversation — gated on `write` because it costs a real model call.

What the server will never do

Installing apps, changing scopes, setting credentials, touching billing or managing the team are not available over MCP, and will not be.

This matters because the same assistant reads customer messages, and a customer's message is text an attacker controls. Every tool above has a bounded worst case. "Install an app" would not.

Configuration belongs in the dashboard, in front of someone who can see what they are approving.

Support

Dashboard: vendu.space
Documentation: vendu.space/docs/developers/mcp
Email: support@vendu.space

Quick Start

Option A: OAuth (Claude Desktop, Cursor)

Option B: API Key

Available Tools

Read Tools (scope: read)

Write Tools (scope: write)

Prompts

Rate limits

Audit

Authentication

OAuth Endpoints

Protocol

Examples

Ask about orders

Check analytics

Adjust AI behavior

Test how your agent would answer (write scope)

Morning briefing

Testing your agent through MCP

What the assistant can change

What the server will never do

Support

Quick Start

Option A: OAuth (Claude Desktop, Cursor)

Option B: API Key

Available Tools

Read Tools (scope: read)

Write Tools (scope: write)

Prompts

Rate limits

Audit

Authentication

OAuth Endpoints

Protocol

Examples

Ask about orders

Check analytics

Adjust AI behavior

Test how your agent would answer (write scope)

Morning briefing

Testing your agent through MCP

What the assistant can change

What the server will never do

Support

Read Tools (scope: `read`)

Write Tools (scope: `write`)

Read Tools (scope: `read`)

Write Tools (scope: `write`)