MCP Fundamentals

The Model Context Protocol (MCP) is an open standard created by Anthropic that defines how AI models connect to external data sources and tools. Think of it as a universal adapter -- instead of every AI application building custom integrations with every service, MCP provides a standardized protocol that any AI host can use to communicate with any MCP-compatible server.

For Shopify developers, MCP is particularly powerful. It allows Claude Code (and other AI tools) to directly interact with Shopify's APIs, read documentation, validate themes, and manage store data -- all through a standardized, composable interface.

Why MCP Exists

Before MCP, connecting an AI model to external services required custom code for every integration. If you wanted Claude to interact with Shopify, GitHub, and Slack, you needed three separate custom integrations with different authentication flows, data formats, and error handling patterns.

MCP solves this with a single protocol:

• For tool developers: Build one MCP server, and it works with every MCP-compatible AI host
• For AI hosts: Support MCP once, and gain access to an entire ecosystem of tools
• For end users: Mix and match tools without writing integration code

MCP is Open Source

MCP is an open specification with SDKs available in TypeScript, Python, Java, Kotlin, C#, Swift, and Go. Anyone can build MCP servers or clients. The specification and SDKs are available at modelcontextprotocol.io.

Architecture

MCP follows a client-server architecture with three distinct layers:

The Three Layers

Host: The application the user interacts with. Claude Code, Cursor, Claude Desktop, and VS Code Copilot are all examples of MCP hosts. The host manages the user interface and coordinates between the AI model and MCP clients.

Client: Created by the host, one client per server connection. The client handles protocol negotiation, capability exchange, and message routing. You rarely interact with clients directly -- the host manages them.

Server: A lightweight program that exposes specific capabilities. A Shopify MCP server might expose tools for querying products, resources for reading documentation, and prompts for common operations.

Transport Types

MCP supports multiple transport mechanisms for communication between clients and servers. Each transport has different trade-offs.

stdio (Standard Input/Output)

The most common transport for local development. The host spawns the MCP server as a child process and communicates via stdin/stdout.

stdio transport example

# Claude Code spawns this process and communicates via stdin/stdout
npx -y @anthropic-ai/shopify-dev-mcp@latest

Pros: Simple setup, no network configuration, secure (local only) Cons: Local only, one client per server instance Best for: Development tools, Claude Code, Cursor

SSE (Server-Sent Events)

Uses HTTP with Server-Sent Events for streaming responses. The server runs as a web service.

SSE transport example

# Server runs on a URL
http://localhost:3000/sse

Pros: Network-accessible, multiple clients can connect, works through firewalls Cons: More complex setup, requires HTTP server Best for: Shared team servers, remote access

Streamable HTTP

The newest transport, using standard HTTP requests with optional streaming. This is the recommended transport for production deployments.

HTTP transport

# Server endpoint
http://localhost:3000/mcp

Pros: Standard HTTP semantics, easy to deploy, supports both stateful and stateless operation Cons: Newest transport, less tooling support currently Best for: Production deployments, cloud-hosted servers

Which Transport for Shopify Development?

Use stdio for local development with Claude Code. It requires zero configuration -- just point Claude Code at the MCP server command and it handles the rest. Use SSE or HTTP when you need to share an MCP server across a team or access it remotely.

MCP Primitives

MCP defines four core primitives that servers can expose:

Tools

Tools are functions that the AI model can call to perform actions. They are the most commonly used primitive.

Example: Shopify product search tool

{
  "name": "search_products",
  "description": "Search for products in the Shopify store by title, vendor, or tag",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query string"
      },
      "limit": {
        "type": "number",
        "description": "Maximum results to return",
        "default": 10
      }
    },
    "required": ["query"]
  }
}

Key characteristics:

• Model-controlled: the AI decides when to call them
• Can have side effects (create, update, delete)
• Return structured results
• Should have clear, descriptive names and descriptions

Resources

Resources provide read-only data that can be loaded into context. Think of them as files or documents the AI can access.

Example: Shopify API documentation resource

{
  "uri": "shopify://docs/admin-api/products",
  "name": "Products API Documentation",
  "mimeType": "text/markdown",
  "description": "Complete reference for the Shopify Admin API Products endpoints"
}

Key characteristics:

• Application-controlled: the host decides when to load them
• Read-only (no side effects)
• Can be static (documentation) or dynamic (live data)
• Support URI-based addressing with custom schemes

Prompts

Prompts are pre-written templates that help users accomplish common tasks. They are user-facing -- displayed as suggestions or slash commands.

Example: Shopify app scaffolding prompt

{
  "name": "scaffold_shopify_app",
  "description": "Generate a complete Shopify app scaffold",
  "arguments": [
    {
      "name": "app_type",
      "description": "Type of app (remix, custom, hydrogen)",
      "required": true
    },
    {
      "name": "features",
      "description": "Comma-separated list of features to include",
      "required": false
    }
  ]
}

Key characteristics:

• User-controlled: the user explicitly selects them
• Return message templates (not raw data)
• Can include dynamic content from resources
• Act as conversation starters or workflow triggers

Sampling

Sampling allows an MCP server to request the AI model to generate text. This enables agentic server-side workflows where the server can leverage the AI's reasoning.

Key characteristics:

• Server-initiated: the server asks for AI completion
• Human-in-the-loop: hosts should allow users to approve/reject
• Enables multi-step reasoning within server logic
• Used for complex tool orchestration

Sampling is Advanced

Most Shopify MCP servers don't use sampling. It's primarily useful when building custom MCP servers that need to perform complex reasoning as part of their tool execution. If you're just using existing MCP servers, you can safely skip sampling for now.

MCP vs Traditional API Integrations

Understanding how MCP differs from direct API integration clarifies when to use each approach.

Aspect	Direct API Integration	MCP Integration
Setup	Custom code per API	Standardized protocol
Auth	Per-API auth flow	Handled by server
Discovery	Read docs, write code	Automatic tool discovery
Updates	Manual code changes	Server updates independently
Composability	Hard to combine	Mix and match servers
AI Awareness	Model doesn't know API exists	Model discovers tools dynamically

When to Use Direct API Calls

• Production app code: Your Shopify app should call the Admin API directly, not through MCP
• High-performance paths: MCP adds a protocol layer; skip it for latency-sensitive operations
• Simple, stable integrations: If you only need one API endpoint, MCP is overkill

When to Use MCP

• AI-assisted development: Claude Code interacting with Shopify during development
• Multi-tool workflows: Combining Shopify data with other services (analytics, CMS, shipping)
• Exploration and prototyping: Quickly testing API operations without writing code
• Documentation and schema access: Getting Shopify docs and GraphQL schema into AI context

MCP is for Development, Not Production

A common misconception: MCP is not a replacement for your app's Shopify API integration. Your production app should use the Shopify Admin API directly via the authenticated client. MCP is a tool that enhances your development workflow by giving AI assistants structured access to Shopify's ecosystem.

The MCP Ecosystem for Shopify

The Shopify MCP ecosystem includes several servers, each serving a different purpose:

Each server is covered in detail in the following sections of this module.

Setting Up Your First MCP Server

Here's a quick preview of how simple it is to add an MCP server to Claude Code:

Add the Shopify Dev MCP server

claude mcp add shopify-dev-mcp -s user -- npx -- -y @anthropic-ai/shopify-dev-mcp@latest

That single command registers the Shopify Dev MCP server globally. The next time you start Claude Code, it will automatically have access to Shopify documentation search, GraphQL schema introspection, and theme validation.

We'll cover each MCP server in depth in the following pages.

Next Steps

Now that you understand the MCP architecture and primitives, proceed to Shopify Dev MCP Server to set up Shopify's official MCP server and explore its capabilities.