Integrates with VTEX public APIs to search and filter the Plaza Vea catalog, retrieve product variants and offers, display product images, and generate cart links for purchasing on Plaza Vea.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@plaza-vea-mcp busca leche y ordénala por precio ascendente"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP local para consultar el catalogo publico de plazaVea mediante las APIs publicas de VTEX. Permite buscar, filtrar, comparar precios, mostrar imagenes dentro de un cliente MCP y generar enlaces para continuar la compra directamente en Plaza Vea.
Incluye un crawler Scrapy opcional que mantiene un cache SQLite y un historial local de precios.
Proyecto independiente, sin afiliacion con Plaza Vea, Compania Food Retail S.A.C. ni VTEX.
Servidor basado exclusivamente en el SDK oficial mcp, usando la API de bajo nivel y stdio.
Consultas live-first al catalogo VTEX con respaldo en SQLite.
Extraccion de todos los SKUs y sellers de cada producto.
Filtros por nombre parcial y marca exacta, tolerantes a mayusculas y acentos.
Ordenamiento por precio ascendente, descendente o nombre.
Imagenes PNG como ImageContent para vision del modelo y Markdown para mostrarlas al usuario.
Enlaces individuales y combinados para agregar productos al carrito.
Crawler Scrapy respetuoso con robots.txt, AutoThrottle, cache HTTP y reintentos.
Sin Selenium, credenciales, CAPTCHA ni automatizacion del pago.
Related MCP server: mcp-carrefour
Python 3.12 o 3.13.
uv.
Codex CLI o cualquier cliente compatible con MCP por stdio.
git clone https://github.com/jeffreymonjacastro/plaza-vea-mcp.git
cd plaza-vea-mcp
uv sync --all-groupsPara registrar el servidor local en Codex desde este checkout:
codex mcp add plaza-vea -- uv --directory C:\ruta\a\plaza-vea-mcp run plaza-vea-mcp
codex mcp get plaza-veaReinicia o abre una nueva tarea de Codex para que las tools aparezcan en la sesion.
Tool | Descripcion |
| Filtra por nombre y marca y ordena por precio o nombre. |
| Devuelve todas las variantes, sellers, ofertas e imagenes. |
| Lista marcas activas, opcionalmente por prefijo. |
| Devuelve |
| Valida SKUs y genera enlaces para continuar en Plaza Vea. |
| Inicia el crawler local en segundo plano. |
| Consulta el progreso y resultado del crawler. |
Ejemplos de solicitudes naturales en Codex:
Busca productos que contengan "leche" y ordenalos del mas barato al mas caro.
Busca cafe de la marca ALTOMAYO y muestra la imagen del producto mas barato.
Genera un enlace de carrito para dos unidades del SKU 12345.
Actualiza la categoria 814 y dime cuando termine.Los precios se devuelven como enteros en centimos de sol (price_cents) y con moneda PEN.
Cada consulta indica si la fuente es live o cache. Cuando se usa el cache, stale es true.
La version inicial usa el catalogo anonimo del canal de venta 1. Precio, stock, promociones,
region y entrega se vuelven a validar al abrir Plaza Vea.
build_cart_links no abre el navegador ni modifica directamente el carrito. Devuelve:
La pagina de cada producto.
El addToCartLink oficial proporcionado por VTEX para cada SKU.
Un enlace combinado para varios SKUs.
La pagina de checkout de Plaza Vea.
El usuario abre el enlace y completa identificacion, entrega y pago en Plaza Vea. Si el enlace combinado deja de ser compatible con la tienda, se pueden abrir los enlaces individuales.
El proyecto nunca solicita ni almacena contrasenas, DNI, direcciones o datos de tarjeta.
Desde MCP, usa start_catalog_refresh. Sin category_id recorre las categorias hoja del arbol
publico; con un ID solo actualiza esa categoria. La tool devuelve un run_id que puede consultarse
con get_catalog_refresh_status.
Los datos locales se guardan en data/catalog.sqlite3; los logs del crawler quedan en
data/logs/. Ambos estan excluidos de Git.
Variables opcionales:
Variable | Uso |
| Directorio de trabajo del proyecto. |
| Directorio para base de datos, logs y cache HTTP. |
| Ruta explicita del archivo SQLite. |
uv sync --all-groups
uv run ruff check src tests scripts
uv run mypy src
uv run pytest
uv run python scripts/smoke_mcp.pyEl smoke test inicia el MCP por stdio, consulta productos reales, obtiene una imagen y construye
un enlace de carrito. No abre el enlace ni avanza al pago.
Respeta los terminos, disponibilidad y politicas publicadas por Plaza Vea.
No incrementes la concurrencia ni desactives AutoThrottle sin autorizacion.
No accedas automaticamente a /checkout; esa ruta esta bloqueada en robots.txt.
No uses este proyecto para evadir CAPTCHA, controles de acceso o limites del sitio.
Las imagenes y datos comerciales pertenecen a sus respectivos titulares.
Consulta THIRD_PARTY_NOTICES.md para referencias y atribuciones.
Codigo publicado bajo licencia MIT. Esta licencia no concede derechos sobre marcas, imagenes ni contenido comercial obtenido de Plaza Vea.
Valida SKUs y genera enlaces para que el usuario abra Plaza Vea y agregue los productos. No abre el navegador, no modifica un carrito y no realiza pagos.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
| Name | Required | Description |
|---|---|---|
| items | Yes | |
| warning | Yes | |
| checkout_url | Yes | |
| combined_cart_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive behavior. The description adds explicit context by stating it does not open the browser, modify a cart, or make payments, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, with no redundant information. It efficiently communicates the core function and key non-behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers purpose and non-behaviors, it lacks parameter semantics and any mention of validation outcomes or error handling. However, the output schema is present, so return values are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no explanation of the 'items' parameter or its sub-fields (sku_id, quantity, seller_id). The agent receives no semantic guidance for correct input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: validating SKUs and generating cart links. It is specific and distinct from sibling tools like search_products or get_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for building cart links but does not explicitly state when to use this tool versus alternatives. It lists non-behaviors but lacks direct guidance on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consulta progreso, resultado y errores de una actualizacion Scrapy.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes |
| Name | Required | Description |
|---|---|---|
| pid | Yes | |
| error | Yes | |
| run_id | Yes | |
| status | Yes | |
| started_at | Yes | |
| category_id | Yes | |
| finished_at | Yes | |
| products_processed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds specific data returned (progress, result, errors), which is useful but does not contradict the annotations. It stops short of describing error handling or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly communicates the tool's purpose without unnecessary detail or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic function but lacks details on output structure, behavior for missing/invalid run_id, and its relationship to start_catalog_refresh is implied rather than explicit. Adequate for a simple status tool but with notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides run_id with length constraints but no description of its meaning. The tool description does not explain what run_id represents or how it should be obtained, leaving the parameter semantics ambiguous despite the self-explanatory name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it queries progress, results, and errors of a Scrapy catalog refresh. This distinguishes it from sibling tools like start_catalog_refresh (which initiates a refresh) and the product search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool, such as 'after starting a refresh' or 'to check if a refresh completed'. It only states the function without usage context or comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Devuelve todas las variantes, sellers, ofertas e imagenes de un producto.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
| brand | Yes | |
| stale | Yes | |
| offers | Yes | |
| source | Yes | |
| categories | Yes | |
| fetched_at | Yes | |
| product_id | Yes | |
| product_url | Yes | |
| product_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds a little context by specifying the breadth of the returned data, but it does not disclose behavior beyond what the annotations and the stated return scope already imply, such as pagination, errors, or availability constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and the object. Every word carries meaning, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and annotations cover return values and safety profile, and the single required parameter is simple. However, the description does not clarify how to obtain or interpret product_id, nor does it situate the tool relative to its siblings, leaving minor but real gaps for autonomous selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description would need to compensate by explaining product_id semantics. It does not clarify the format, source, or scope of product_id beyond the schema's type/length constraints and the property name, leaving some ambiguity for an agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Devuelve') and identifies the resource ('un producto') while enumerating the exact data returned: variants, sellers, offers, and images. This clearly distinguishes the tool from siblings like get_product_image (single image) and search_products (search/browse).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. Sibling tools such as search_products and get_product_image are not referenced, leaving the agent to infer usage from the resource scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Descarga una imagen publica de un SKU y la devuelve como ImageContent PNG para vision del modelo. Para hacerla visible al usuario en Codex, copia tambien en la respuesta final el Markdown de imagen incluido en TextContent.
| Name | Required | Description | Default |
|---|---|---|---|
| sku_id | Yes | ||
| image_index | No |
| Name | Required | Description |
|---|---|---|
| width | Yes | |
| height | Yes | |
| sku_id | Yes | |
| mime_type | No | |
| product_id | Yes | |
| source_url | Yes | |
| image_index | Yes | |
| product_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, and non-destructive behavior. The description aligns by stating it downloads and returns an image, with no contradictions. While it does not add extra behavioral details beyond the annotations, it is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, consisting of two sentences that convey the tool's function and a key usage instruction without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool, the description covers the main purpose, output format, and a usage tip. It does not discuss edge cases or detailed return structure, but it is sufficient for an agent to understand the tool's core functionality and use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'de un SKU' which hints at the sku_id parameter, but it does not explicitly define either parameter. The image_index parameter is completely unaddressed. With 0% schema coverage, the description fails to provide necessary parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it downloads a public image from a SKU and returns it as ImageContent PNG for model vision, and further explains how to make it visible to the user in Codex. This distinguishes it from sibling tools like get_product or search_products, which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit usage instruction: copying the markdown in TextContent to make the image visible to the user in Codex. However, it does not explicitly contrast with sibling tools (e.g., when to use this over get_product), leaving some inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista marcas activas y permite filtrar por prefijo.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| prefix | No |
| Name | Required | Description |
|---|---|---|
| stale | Yes | |
| brands | Yes | |
| source | Yes | |
| fetched_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, and idempotent behavior. The description adds the detail that only active brands are listed, which is a useful behavioral nuance. However, it does not mention output format or pagination, so transparency is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly conveys the tool's purpose. It is well-structured and contains no unnecessary words or details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the presence of an output schema, the description is adequate but not comprehensive. It lacks information about pagination, sorting, or any edge cases. Since the output schema exists, the description does not need to explain return values, but it could still benefit from additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the 'prefix' parameter by mentioning filtering by prefix. The 'limit' parameter is not described, but its meaning is fairly standard. The schema covers both parameters, but the description does not fully elaborate on their semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing active brands and filtering by prefix. This distinguishes it from sibling tools like search_products or get_product, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as search_products. No contextual hints or selection criteria are offered, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Busca el catalogo publico por nombre parcial y marca exacta. Puede ordenar por precio minimo o nombre; precio y stock se revalidan al abrir Plaza Vea.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| sort | No | price_asc | |
| brand | No | ||
| limit | No | ||
| only_available | No |
| Name | Required | Description |
|---|---|---|
| stale | Yes | |
| source | Yes | |
| products | Yes | |
| fetched_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a behavioral caveat beyond the annotations: price and stock are revalidated when opening Plaza Vea, indicating data might be stale. This supplements the readOnlyHint and idempotentHint already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that covers the core functionality without unnecessary verbosity. It is well-structured and easy to parse, though it could be slightly more explicit about the return type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that some parameters are not described and the output schema is not referenced, the description leaves some gaps. However, the core search behavior and the revalidation note provide enough context for typical usage, making it moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies the semantics for 'name' (partial match) and 'brand' (exact match), and mentions sorting by price minimum. However, it does not explain limit, only_available, or the sort enum values, which remain inferred from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the public catalog by partial name and exact brand, and supports sorting. It distinguishes from siblings like get_product by focusing on catalog search, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_brands or get_product. It only explains what it does, leaving the selection criteria implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inicia un crawler Scrapy local en segundo plano. Escribe catalogo e historial de precios en SQLite, sin modificar datos remotos.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | No |
| Name | Required | Description |
|---|---|---|
| run_id | Yes | |
| status | Yes | |
| started_at | Yes | |
| category_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful context beyond annotations: it explicitly states the operation runs in the background and writes to local SQLite without modifying remote data. This complements the annotations (readOnlyHint=false, destructiveHint=false) by clarifying the side effects are local and non-destructive. However, it does not mention potential rate limits, resource usage, or how long the operation may take.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action (starts crawler in background) and follows with the data targets and the non-modification guarantee. There is no fluff or redundancy; every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool with an optional parameter and a sibling for status checking. It does not mention the category_id parameter, nor does it point to get_catalog_refresh_status for tracking progress or outcomes. While an output schema exists, the description should at least hint at the asynchronous nature and how to verify completion. This is a significant gap for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional parameter (category_id) with 0% description coverage, and the tool description does not mention this parameter at all. An agent would have no idea that it can filter the refresh by a specific category, nor what the parameter's format or effect is. The description completely fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it starts a local Scrapy crawler in the background and writes catalog and price history to SQLite. It clearly distinguishes itself from siblings like get_catalog_refresh_status by emphasizing it initiates a refresh rather than checking status. The phrase 'sin modificar datos remotos' further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention get_catalog_refresh_status as the way to check the result of a refresh, nor does it state any conditions or prerequisites (e.g., requiring an existing catalog). The description only explains what the tool does, not when it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0build_cart_linksget_catalog_refresh_statusget_productget_product_imagelist_brandssearch_productsstart_catalog_refreshScored across 7 tools
Each tool has a clear, distinct purpose: searching products, retrieving details, listing brands, fetching images, building cart links, and managing catalog refresh. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern with lowercase underscores (e.g., search_products, get_product_image, start_catalog_refresh). Perfectly uniform.
7 tools is well within the ideal range for a focused e-commerce catalog server, covering both read operations and background job management without excess.
The tool set comprehensively covers product discovery (search, get, brands, images), cart link generation, and catalog refresh management (start and status). No obvious gaps for the stated domain.
MCP server for real-time product search by barcode (EAN, UPC, GTIN) or keyword on ean-search.org
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
