--- title: "Buscar produto via MCP (Model Context Protocol)" url: "https://devcenter.stone.com.br/apis/stone-catalog/versions/502db258-cb08-4b38-8af1-b96a688b9a9e/operations/findProductsMcp" --- > Full API specification: https://devcenter.stone.com.br/apis/stone-catalog/versions/502db258-cb08-4b38-8af1-b96a688b9a9e.md # Buscar produto via MCP (Model Context Protocol) `POST` `/products/mcp` Operation ID: `findProductsMcp` Endpoint MCP (Model Context Protocol) para integração com agentes de IA (Claude Desktop, Cursor, Zed, etc.). Requer autenticação OAuth2 via Scalekit. ## Request body (required) Content types: `application/json` ## Responses - `200` - Produto encontrado com sucesso - `400` - Parâmetros inválidos - `401` - OAuth token inválido ou ausente - `404` - Produto não encontrado - `500` - Erro interno do servidor ## OpenAPI definition ```yaml openapi: 3.0.3 info: title: Stone Catalog API version: 1.0.0 servers: - url: https://sdx.api.stone.com.br/v1/catalog description: Ambiente de Desenvolvimento (SDX) - url: https://api.stone.com.br/v1/catalog description: Ambiente de Produção (PRD) paths: /products/mcp: post: tags: - MCP summary: Buscar produto via MCP (Model Context Protocol) description: Endpoint MCP (Model Context Protocol) para integração com agentes de IA (Claude Desktop, Cursor, Zed, etc.). Requer autenticação OAuth2 via Scalekit. operationId: findProductsMcp security: - OAuth2BearerMcp: [] requestBody: required: true content: application/json: schema: type: object properties: barcode: type: string description: Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos) pattern: ^[0-9]{12,13}$ example: "7891234567890" name: type: string description: Nome do produto para busca textual minLength: 3 example: Smartphone Samsung Galaxy description: Forneça 'barcode' ou 'name' para buscar o produto. Se ambos forem fornecidos, 'barcode' terá prioridade. examples: byBarcode: summary: Busca por código de barras value: barcode: "7891234567890" byName: summary: Busca por nome value: name: Smartphone Samsung Galaxy responses: "200": description: Produto encontrado com sucesso content: application/json: schema: type: array items: $ref: "#/components/schemas/ProductResponse" example: - id: 550e8400-e29b-41d4-a716-446655440000 barcode: "7891234567890" name: Smartphone Samsung Galaxy S24 Ultra 256GB shortDescription: Smartphone premium com câmera de 200MP longDescription: O Galaxy S24 Ultra redefine a experiência móvel premium... brand: Samsung manufacturer: Samsung Electronics categoryPath: Eletrônicos > Smartphones > Samsung images: - https://api.catalog.stone.com.br/products/images/550e8400-e29b-41d4-a716-446655440000/image1.jpg price: R$ 7.299,99 attributes: cor: Preto Titânio memoria: 256GB ram: 12GB weightKg: 0.233 heightCm: 16.2 widthCm: 7.9 depthCm: 0.86 metadata: version: 1 confidenceScore: 0.95 discoveredAt: 2024-01-15T10:30:00Z updatedAt: 2024-01-15T10:30:00Z lastScrapedAt: 2024-01-15T10:30:00Z "400": description: Parâmetros inválidos content: application/json: schema: $ref: "#/components/schemas/ValidationError" examples: invalidBarcode: summary: Código de barras inválido value: error: Invalid parameters details: - field: barcode message: Barcode must contain exactly 12 or 13 numeric digits invalidName: summary: Nome muito curto value: error: Invalid parameters details: - field: name message: Name must be at least 3 characters long missingParameters: summary: Nenhum parâmetro fornecido value: error: Invalid parameters details: - field: barcode or name message: Either barcode or name must be provided "401": description: OAuth token inválido ou ausente content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Invalid or missing OAuth token headers: WWW-Authenticate: description: Indica o método de autenticação necessário schema: type: string example: Bearer realm="MCP" "404": description: Produto não encontrado content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Product not found "500": description: Erro interno do servidor content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Internal server error security: - OAuth2BearerMcp: [] components: schemas: ProductResponse: type: object required: - id - name - categoryPath - images - metadata properties: id: type: string format: uuid description: Identificador único do produto example: 550e8400-e29b-41d4-a716-446655440000 barcode: type: string nullable: true description: Código de barras EAN-13 pattern: ^\d{12,13}$ example: "7891000100103" name: type: string description: Nome do produto example: Coca-Cola 2L shortDescription: type: string nullable: true description: Descrição curta do produto example: Refrigerante Coca-Cola 2 Litros longDescription: type: string nullable: true description: Descrição detalhada do produto example: Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família. brand: type: string nullable: true description: Marca do produto example: Coca-Cola manufacturer: type: string nullable: true description: Fabricante do produto example: Coca-Cola Brasil categoryPath: type: string description: Caminho completo da categoria example: Alimentos e Bebidas > Bebidas > Refrigerantes images: type: array description: Lista de URLs das imagens do produto items: type: string format: uri example: https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg attributes: type: object nullable: true description: Atributos específicos do produto (pares chave-valor) additionalProperties: type: string example: volume: 2L sabor: Original tipo: Refrigerante weightKg: type: number nullable: true format: float description: Peso do produto em quilogramas example: 2.1 heightCm: type: number nullable: true format: float description: Altura do produto em centímetros example: 32.5 widthCm: type: number nullable: true format: float description: Largura do produto em centímetros example: 10.5 depthCm: type: number nullable: true format: float description: Profundidade do produto em centímetros example: 10.5 price: type: string nullable: true format: string description: Faixa de preço do produto em reais. Retorna null quando não disponível. example: R$ 7.50 metadata: type: object required: - version - confidenceScore - discoveredAt - updatedAt - lastScrapedAt properties: version: type: integer description: Versão do registro do produto example: 1 confidenceScore: type: number format: float minimum: 0 maximum: 1 description: Score de confiança dos dados (0.00 - 1.00) example: 0.95 discoveredAt: type: string format: date-time description: Data/hora em que o produto foi descoberto example: 2024-01-15T10:30:00Z updatedAt: type: string format: date-time description: Data/hora da última atualização example: 2024-01-15T10:30:00Z lastScrapedAt: type: string format: date-time description: Data/hora do último scraping example: 2024-01-15T10:30:00Z ValidationError: type: object required: - error - details properties: error: type: string description: Mensagem de erro example: Invalid parameters details: type: array description: Lista de erros de validação items: type: object properties: field: type: string description: Campo com erro example: barcode message: type: string description: Mensagem de erro específica example: Barcode must contain exactly 12 or 13 numeric digits Error: type: object required: - error properties: error: type: string description: Mensagem de erro example: Internal server error securitySchemes: OAuth2BearerMcp: type: http scheme: bearer bearerFormat: JWT description: Bearer token OAuth2 via Scalekit, exclusivo para o endpoint MCP. O token deve ter como audience o resource_id `/products/mcp`. ```