Setting Up WebMCP for Shopify Ecommerce Sites

If you’re running a Shopify store, WebMCP gives AI agents deterministic, reliable access to your store’s functionality. Instead of agents parsing raw HTML and making unpredictable decisions, they interact with your store through structured tools that guarantee consistent behavior every time.

Why WebMCP Matters for Ecommerce

Traditional AI agents interact with websites in two ways, and both have problems:

1. Custom MCP servers – You build a Model Context Protocol server, but agents won’t load it unless they use your site daily (doesn’t scale for most ecommerce sites)
2. Browser automation – Agents extract raw HTML, clean it up, feed it to an LLM, and guess what to click. This is nondeterministic – agents make errors, miss elements, and fail unpredictably.

WebMCP solves this by letting you declare tools directly in your web pages. When an agent visits your product page, it automatically gets access to tools like add_to_cart, get_product_details, and check_inventory. The agent executes these tools with guaranteed schemas – no HTML parsing, no guesswork, zero errors.

The Contextual Loading Advantage

Here’s what makes WebMCP different: tools load contextually based on which page the agent is on. Your homepage might expose search_products and get_categories. Your product page exposes add_to_cart and get_similar_products. Your checkout page exposes apply_coupon and submit_order.

This solves the context window bloat problem. Traditional MCP loads every tool upfront. WebMCP only loads relevant tools per page.

Prerequisites

Browser Setup (Required):

• Chrome Beta browser (standard Chrome doesn’t support WebMCP yet)
• Enable WebMCP flag: Navigate to chrome://flags, search “web MCP”, enable it, restart browser
• Install Model Context Tool Inspector extension from Chrome Web Store

For Shopify Integration:

• Shopify store with admin access
• Node.js 18+ if running WebMCP server locally
• Basic understanding of REST APIs and JavaScript

Understanding the Two Implementation Modes

WebMCP supports two ways to define tools:

1. Declarative Mode (HTML Attributes)

Best for static forms and simple interactions. You add special attributes to HTML elements:

<form tool-name="add_to_cart" tool-description="Add product to shopping cart">
  <input name="product_id" tool-param-description="Shopify product ID" />
  <input name="quantity" tool-param-description="Number of items to add" />
  <button type="submit">Add to Cart</button>
</form>

The browser automatically converts these attributes into MCP tools that agents can call.

2. Imperative Mode (JavaScript API)

Best for React/Next.js apps and dynamic interfaces. You register tools programmatically:

navigator.mcpAgent.registerTool({
  name: 'add_to_cart',
  description: 'Add product to shopping cart',
  inputSchema: {
    type: 'object',
    properties: {
      product_id: { type: 'string', description: 'Shopify product ID' },
      quantity: { type: 'number', description: 'Number of items' }
    }
  },
  handler: async (params) => {
    // Your implementation
    return { success: true, cart_total: 3 };
  }
});

We’ll use the imperative mode for Shopify since most stores run on JavaScript frameworks.

Step 1: Generate Shopify Admin API Credentials

WebMCP needs authenticated access to your Shopify admin panel.

1. Log into your Shopify admin dashboard
2. Navigate to Settings → Apps and sales channels → Develop apps
3. Click “Create an app” and name it “WebMCP Integration”
4. Under “Configuration” tab, click “Configure Admin API scopes”
5. Select the following scopes:
   • read_products, write_products (product management)
   • read_inventory, write_inventory (stock levels)
   • read_orders (order monitoring)
   • read_customers (customer data)
6. Click “Save” and then “Install app”
7. Copy the Admin API access token (you’ll only see this once)

Security note: Store this token in environment variables. Never commit it to version control.

Step 2: Create WebMCP Configuration File

Create a webmcp-config.json file to centralize your Shopify connection settings:

{
  "shopify": {
    "store_url": "your-store.myshopify.com",
    "api_version": "2024-01",
    "access_token": "${SHOPIFY_ACCESS_TOKEN}"
  },
  "tools": {
    "context_specific": true,
    "auto_register": true
  }
}

Load this token from environment variables in production.

Step 3: Set Up WebMCP Tools File

For React/Next.js apps, create a dedicated webmcp.ts file to manage all your tools:

// webmcp.ts
export const registerTool = (tool: MCPTool) => {
  if (typeof navigator !== 'undefined' && navigator.mcpAgent) {
    navigator.mcpAgent.registerTool(tool);
  }
};

export const unregisterTool = (toolName: string) => {
  if (typeof navigator !== 'undefined' && navigator.mcpAgent) {
    navigator.mcpAgent.unregisterTool(toolName);
  }
};

// Helper for request tracking
export const generateRequestId = () => {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
};

Step 4: Define Shopify Tools

Create tools for common Shopify operations. Here’s a product search tool:

// tools/searchProducts.ts
import { registerTool } from '../webmcp';

export const searchProductsTool = {
  name: 'search_products',
  description: 'Search Shopify product catalog',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
      limit: { type: 'number', description: 'Max results (default 10)' }
    },
    required: ['query']
  },
  handler: async (params) => {
    const response = await fetch(
      `https://${config.shopify.store_url}/admin/api/2024-01/products.json?title=${params.query}&limit=${params.limit || 10}`,
      {
        headers: {
          'X-Shopify-Access-Token': process.env.SHOPIFY_ACCESS_TOKEN
        }
      }
    );
    const data = await response.json();
    return { products: data.products };
  }
};

// Register when component mounts
registerTool(searchProductsTool);

Step 5: Wire Tools to React Components

Bind tools to specific pages so they load contextually:

// components/ProductPage.tsx
import { useEffect } from 'react';
import { registerTool, unregisterTool } from '../webmcp';
import { addToCartTool, getProductDetailsTool } from '../tools/product';

export default function ProductPage() {
  useEffect(() => {
    // Register product-specific tools when component mounts
    registerTool(addToCartTool);
    registerTool(getProductDetailsTool);

    // Unregister when component unmounts
    return () => {
      unregisterTool('add_to_cart');
      unregisterTool('get_product_details');
    };
  }, []);

  return <div>{/* Your product UI */}</div>;
}

Now when an agent visits your product page, it automatically gets access to add_to_cart and get_product_details. When it leaves, those tools unregister.

Step 6: Handle Agent-Invoked Events

WebMCP provides special events to detect when agents execute tools:

// Add event listener for agent actions
document.addEventListener('agent.invoked', (event) => {
  console.log('Agent called tool:', event.detail.toolName);

  // Show confirmation UI
  showConfirmationDialog({
    message: 'AI agent wants to add item to cart',
    onConfirm: () => event.detail.confirm(),
    onReject: () => event.detail.reject()
  });
});

You can also add special CSS classes that activate when agents interact with forms:

.tool-form-active {
  border: 2px solid #4a90e2;
  background: #f0f8ff;
}

.tool-submit-active::after {
  content: "Please review and confirm";
  position: absolute;
  background: #333;
  color: white;
  padding: 8px 12px;
  border-radius: 4px;
}

Step 7: Test with Inspector Tool

Open your Shopify site in Chrome Beta with the Model Context Tool Inspector extension installed.

1. Click the Inspector extension icon
2. You should see registered tools for the current page
3. Click “Test Tool” to manually invoke it
4. Verify the tool executes correctly and returns expected results

As you navigate between pages, watch the tools list update contextually.

Common Use Cases

Order Fulfillment Automation

Create tools for order processing workflows:

const fulfillOrderTool = {
  name: 'fulfill_order',
  description: 'Mark order as fulfilled and generate shipping label',
  inputSchema: {
    type: 'object',
    properties: {
      order_id: { type: 'string' },
      tracking_number: { type: 'string' },
      carrier: { type: 'string', enum: ['USPS', 'UPS', 'FedEx'] }
    }
  },
  handler: async (params) => {
    // Create fulfillment via Shopify API
    return { success: true, tracking_url: '...' };
  }
};

Inventory Management

Let agents monitor and update stock levels:

const updateInventoryTool = {
  name: 'update_inventory',
  description: 'Update product inventory levels',
  inputSchema: {
    type: 'object',
    properties: {
      product_id: { type: 'string' },
      variant_id: { type: 'string' },
      quantity: { type: 'number' }
    }
  },
  handler: async (params) => {
    // Update via Shopify Inventory API
    return { success: true, new_quantity: params.quantity };
  }
};

Customer Service Automation

Provide agents with customer data access:

const getCustomerOrdersTool = {
  name: 'get_customer_orders',
  description: 'Retrieve order history for customer',
  inputSchema: {
    type: 'object',
    properties: {
      customer_id: { type: 'string' }
    }
  },
  handler: async (params) => {
    // Fetch orders via Shopify API
    return { orders: [...] };
  }
};

Troubleshooting

Tools Not Appearing in Inspector

• Verify Chrome Beta is installed and WebMCP flag is enabled
• Check browser console for navigator.mcpAgent – should be defined
• Confirm tools are registered after component mounts (use useEffect)
• Ensure no JavaScript errors preventing registration

Tool Calls Failing

• Check Shopify API access token is valid and not expired
• Verify API scopes include required permissions
• Confirm API version (2024-01) matches your Shopify plan
• Check network tab for 401/403 errors from Shopify API

Agent.Invoked Events Not Firing

• Ensure event listener is added before tools are called
• Check event.detail structure matches expected format
• Verify tools are actually being invoked by agent (not manual clicks)

Security Best Practices

• Never expose admin tokens client-side – Use server-side proxies for Shopify API calls
• Validate all tool inputs – Don’t trust agent-provided parameters without validation
• Implement rate limiting – Prevent abuse of tool endpoints
• Log all agent actions – Track which tools are called and by whom
• Require human confirmation – For sensitive actions (refunds, data deletion, etc.)

Resources

• WebMCP GitHub Repository
• Adapt Marketing WebMCP Tool – Visual configurator for rapid setup
• Shopify Admin API Documentation
• Chrome WebMCP Documentation

Next Steps

Once you have basic WebMCP tools working, consider:

1. Tool analytics – Track which tools agents use most frequently
2. A/B testing – Experiment with different tool descriptions and schemas
3. Error recovery – Build retry logic for failed tool calls
4. Multi-page workflows – Chain tools across multiple pages (search → product → checkout)
5. Custom UI feedback – Design better agent interaction indicators for your customers

WebMCP represents a fundamental shift in how AI agents interact with the web. By making your Shopify store agent-ready today, you’re positioning for a future where AI-driven commerce is the norm.

Posted in Workflows

No Comments