Nuvemshop MCP Server for Mastra AI 24 tools — connect in under 2 minutes
Mastra AI is a TypeScript-native agent framework built for modern web stacks. Connect Nuvemshop through Vinkius and Mastra agents discover all tools automatically. type-safe, streaming-ready, and deployable anywhere Node.js runs.
ASK AI ABOUT THIS MCP SERVER
Vinkius supports streamable HTTP and SSE.
import { Agent } from "@mastra/core/agent";
import { createMCPClient } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
async function main() {
// Your Vinkius token. get it at cloud.vinkius.com
const mcpClient = await createMCPClient({
servers: {
"nuvemshop": {
url: "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp",
},
},
});
const tools = await mcpClient.getTools();
const agent = new Agent({
name: "Nuvemshop Agent",
instructions:
"You help users interact with Nuvemshop " +
"using 24 tools.",
model: openai("gpt-4o"),
tools,
});
const result = await agent.generate(
"What can I do with Nuvemshop?"
);
console.log(result.text);
}
main();
* Every MCP server runs on Vinkius-managed infrastructure inside AWS - a purpose-built runtime with per-request V8 isolates, Ed25519 signed audit chains, and sub-40ms cold starts optimized for native MCP execution. See our infrastructure
About Nuvemshop MCP Server
Connect your Nuvemshop store to any AI agent and take full control of your e-commerce operations through natural conversation.
Mastra's agent abstraction provides a clean separation between LLM logic and Nuvemshop tool infrastructure. Connect 24 tools through Vinkius and use Mastra's built-in workflow engine to chain tool calls with conditional logic, retries, and parallel execution. deployable to any Node.js host in one command.
What you can do
- Product Management — List, create, update, and delete products with full catalog details including variants, SKUs, and stock levels
- Order Processing — Monitor orders, track fulfillment status, create manual orders, and update order states through the sales pipeline
- Customer Management — Browse customer database, view order history, create and update customer records with addresses
- Discount Coupons — Create, manage, and delete promotional coupons with percentage, absolute, or shipping discounts
- Category Organization — List product categories to understand your store's organization structure
- Variant Management — Inspect product variants (size, color, material) with individual SKUs, prices, and stock
- Store Configuration — View store details including plan, currency, domain, and settings
- Webhook Integration — List, create, and delete webhooks for real-time event notifications
The Nuvemshop MCP Server exposes 24 tools through the Vinkius. Connect it to Mastra AI in under two minutes — no API keys to rotate, no infrastructure to provision, no vendor lock-in. Your configuration, your data, your control.
How to Connect Nuvemshop to Mastra AI via MCP
Follow these steps to integrate the Nuvemshop MCP Server with Mastra AI.
Install dependencies
Run npm install @mastra/core @mastra/mcp @ai-sdk/openai
Replace the token
Replace [YOUR_TOKEN_HERE] with your Vinkius token
Run the agent
Save to agent.ts and run with npx tsx agent.ts
Explore tools
Mastra discovers 24 tools from Nuvemshop via MCP
Why Use Mastra AI with the Nuvemshop MCP Server
Mastra AI provides unique advantages when paired with Nuvemshop through the Model Context Protocol.
Mastra's agent abstraction provides a clean separation between LLM logic and tool infrastructure. add Nuvemshop without touching business code
Built-in workflow engine chains MCP tool calls with conditional logic, retries, and parallel execution for complex automation
TypeScript-native: full type inference for every Nuvemshop tool response with IDE autocomplete and compile-time checks
One-command deployment to any Node.js host. Vercel, Railway, Fly.io, or your own infrastructure
Nuvemshop + Mastra AI Use Cases
Practical scenarios where Mastra AI combined with the Nuvemshop MCP Server delivers measurable value.
Automated workflows: build multi-step agents that query Nuvemshop, process results, and trigger downstream actions in a typed pipeline
SaaS integrations: embed Nuvemshop as a first-class tool in your product's AI features with Mastra's clean agent API
Background jobs: schedule Mastra agents to query Nuvemshop on a cron and store results in your database automatically
Multi-agent systems: create specialist agents that collaborate using Nuvemshop tools alongside other MCP servers
Nuvemshop MCP Tools for Mastra AI (24)
These 24 tools become available when you connect Nuvemshop to Mastra AI via MCP:
create_coupon
You must provide the coupon code and type (percentage, absolute, or shipping). Optional fields include value, validity dates, minimum purchase amount, and applicable products/categories. Example: { "code": "SUMMER20", "type": "percentage", "value": 20, "min_price": 100, "start_date": "2026-06-01", "end_date": "2026-06-30" } Create a new discount coupon in your Nuvemshop store
create_customer
You must provide at minimum the customer name and email. Optional fields include phone, addresses, and tags. Example: { "first_name": "João", "last_name": "Silva", "email": "joao@example.com", "phone": "11999999999" } Create a new customer record in your Nuvemshop store
create_order
Useful for phone orders, in-person sales, or bulk order imports. You must provide customer information and at least one order item with product ID or variant ID and quantity. Example: { "email": "customer@example.com", "items": [{ "product_id": 123, "quantity": 2 }] } Create a new order manually in your Nuvemshop store
create_product
You must provide at minimum the product name and price. Optional fields include description, SKU, stock quantity, categories, images, and variants. Example: { "name": "T-Shirt Blue", "price": 49.90, "sku": "TSH-BLU-001", "stock": 100, "description": "Comfortable cotton t-shirt" } Create a new product in your Nuvemshop store
create_webhook
You must provide the URL to receive notifications and the events to subscribe to. Available events include: orders/create, orders/update, products/create, products/update, products/delete, customers/create, customers/update. Example: { "url": "https://your-app.com/webhooks/nuvemshop", "event": "orders/create" } Create a new webhook for real-time event notifications
delete_coupon
You must provide the coupon_id. This action cannot be undone. Use this to deactivate expired or discontinued promotions. Be careful as this will prevent customers from using this coupon code. Delete a discount coupon from your Nuvemshop store
delete_product
You must provide the product_id. This action cannot be undone. Use this to remove discontinued products, test products, or items that are no longer available. Be careful as this will also remove all associated variants and images for that product. Delete a product from your Nuvemshop store
delete_webhook
You must provide the webhook_id. This action cannot be undone. Use this to remove webhook endpoints that are no longer needed or to stop receiving notifications for specific events. Delete a webhook from your Nuvemshop store
get_coupon
Use the coupon_id obtained from list_coupons to inspect full coupon details. Get detailed information about a specific coupon
get_customer
Use the customer_id obtained from list_customers to inspect full customer details. This is useful for customer support, order management, or analyzing purchase history. Get detailed information about a specific customer
get_order
Use the order_id obtained from list_orders to inspect full order details. This is useful for verifying order status, preparing shipments, or reviewing customer purchases. Get detailed information about a specific order
get_product
Use the product_id obtained from list_products to inspect full product details. This is useful for verifying product data before updating or checking stock levels. Get detailed information about a specific product
get_store
Use this to verify your store setup and understand available features. Get details about your Nuvemshop store
list_categories
Each category includes name, description, and number of assigned products. Use this to understand your store's product organization and category structure. List all product categories in your Nuvemshop store
list_coupons
Each coupon includes code, type (percentage, absolute, shipping), value, validity dates, usage count, and minimum purchase requirements. Use this to review active promotions and analyze coupon performance. List all discount coupons in your Nuvemshop store
list_customers
Each customer includes name, email, phone number, total orders, total spent, and registration date. You can optionally specify page number and records per page. Use this to browse your customer database, analyze purchase patterns, or find specific customers by name or email. List all customers in your Nuvemshop store
list_orders
Each order includes order number, customer name, total value, status (pending, paid, fulfilled, cancelled), payment status, and creation date. You can optionally filter by status, specify page number, and set records per page. Use this to monitor sales, track order fulfillment, and review revenue. List all orders in your Nuvemshop store
list_products
Each product includes name, description, price, SKU, stock quantity, status (active, draft, archived), and images. You can optionally filter by status, specify page number, and set records per page (max: 200). Use this to browse your product catalog or find a specific product by name or SKU. List all products in your Nuvemshop store
list_variants
Each variant includes SKU, price, stock quantity, and option values. Use the product_id from list_products to see all variants of that product. This is useful for managing inventory of products with multiple options. List all variants for a specific product
list_webhooks
). Each webhook includes URL, events subscribed, and creation date. Use this to verify your integration endpoints are properly configured. List all webhooks configured in your Nuvemshop store
update_coupon
Common updates include changing discount value, extending validity dates, or modifying minimum purchase requirements. You must provide the coupon_id and the fields to update as JSON. Update an existing discount coupon
update_customer
Common updates include changing contact information, updating addresses, or adding tags. You must provide the customer_id and the fields to update as JSON. Only provide the fields you want to change. Update an existing customer record
update_order
Common updates include changing order status (e.g., from pending to paid, or from paid to fulfilled), updating shipping information, or modifying order items. You must provide the order_id and the fields to update as JSON. Update an existing order in your Nuvemshop store
update_product
You must provide the product_id and the fields to update as JSON. Only the fields provided will be updated. Common updates include: changing price, updating stock quantity, modifying description, or changing product status. The product_id must exist in your store. Update an existing product in your Nuvemshop store
Example Prompts for Nuvemshop in Mastra AI
Ready-to-use prompts you can give your Mastra AI agent to start working with Nuvemshop immediately.
"Show me all pending orders and their total values."
"Create a new coupon SUMMER20 with 20% discount, minimum purchase of R$ 100, valid until June 30th."
"List all products with stock below 10 units so I can reorder."
Troubleshooting Nuvemshop MCP Server with Mastra AI
Common issues when connecting Nuvemshop to Mastra AI through the Vinkius, and how to resolve them.
createMCPClient not exported
npm install @mastra/mcpNuvemshop + Mastra AI FAQ
Common questions about integrating Nuvemshop MCP Server with Mastra AI.
How does Mastra AI connect to MCP servers?
MCPClient with the server URL and pass it to your agent. Mastra discovers all tools and makes them available with full TypeScript types.Can Mastra agents use tools from multiple servers?
Does Mastra support workflow orchestration?
Connect Nuvemshop with your favorite client
Step-by-step setup guides for every MCP-compatible client and framework:
Anthropic's native desktop app for Claude with built-in MCP support.
AI-first code editor with integrated LLM-powered coding assistance.
GitHub Copilot in VS Code with Agent mode and MCP support.
Purpose-built IDE for agentic AI coding workflows.
Autonomous AI coding agent that runs inside VS Code.
Anthropic's agentic CLI for terminal-first development.
Python SDK for building production-grade OpenAI agent workflows.
Google's framework for building production AI agents.
Type-safe agent development for Python with first-class MCP support.
TypeScript toolkit for building AI-powered web applications.
TypeScript-native agent framework for modern web stacks.
Python framework for orchestrating collaborative AI agent crews.
Leading Python framework for composable LLM applications.
Data-aware AI agent framework for structured and unstructured sources.
Microsoft's framework for multi-agent collaborative conversations.
Connect Nuvemshop to Mastra AI
Get your token, paste the configuration, and start using 24 tools in under 2 minutes. No API key management needed.