Building and deploying MCP AI agents for ecommerce

To build an AI agent that works on an ecommerce store with the Model Context Protocol (MCP), you give it an MCP server for each system it needs (the store platform, the ERP, the helpdesk), design a small set of clearly described tools on each server, and connect those servers to a host: an AI assistant or your own agent service. Read-only tools come first. Every tool that changes the store creates a proposal that a named person approves, and the previous state is stored so the change can be undone.

Deploying it means running remote servers over Streamable HTTP with OAuth sign-in, testing on a development or staging store first, logging every tool call, and widening the agent's reach one job and one store at a time. This guide follows that build order and is written for developers and agency technical leads who already know their platform's APIs. For the business case, start with MCP for ecommerce.

Architecture and the choices to make first

How MCP fits together

Anthropic introduced MCP as an open standard in November 2024. It defines how an AI application connects to tools and data in other software. There are three roles:

Host: the application that runs the model and decides what to do next, such as a chat assistant, an IDE or your own agent service.
Client: the connection inside the host. Each client talks to one server.
Server: a program that exposes one system's capabilities, for example your store's catalogue and orders, or your helpdesk.

Messages use JSON-RPC 2.0. A local server runs as a subprocess of the host and talks over standard input and output (stdio). A remote server listens on one HTTP endpoint using the Streamable HTTP transport, which replaced the older HTTP and server-sent events transport in 2025. Each connection opens with an initialize handshake that agrees a protocol version and capabilities.

A server can offer three kinds of thing:

Tools the model can call, listed with tools/list and run with tools/call. Each tool has a name, a description and a JSON Schema for its inputs.
Resources the host can read, such as a returns policy or a product record, through resources/list and resources/read.
Prompts: reusable templates for common jobs, through prompts/list and prompts/get.

Two corrections to older material, including the first version of this page. MCP stands for Model Context Protocol. And there is no central MCP server that collects and synchronises all your data. Each system keeps its own data behind its own server, the host calls whichever one a task needs, and your platform stays the source of truth.

Decisions to make before you write code

Use a platform server, or build your own. BigCommerce offers a Storefront MCP server for shopping agents, and Shopify provides storefront MCP for eligible stores. These cover shopper tasks such as search and cart. Back-office jobs (stock reconciliation, content fixes, order exceptions, reporting) usually need a server you build or adopt. MCP on Shopify, BigCommerce and Adobe Commerce covers what each platform offers today.
Local or remote. A stdio server suits one developer's machine. Anything shared by a team, a client or a hosted agent should be remote, with proper sign-in.
Which host. If people will use the agent inside an assistant they already have, that assistant is the host and you only build servers. If the agent runs on a schedule or on store events, you build the host too, with an agent framework or an MCP SDK client. Official SDKs exist for TypeScript, Python and several other languages, and frameworks such as LangChain and AutoGen can load MCP tools through adapters.
One agent or several. Start with one agent and one job. Split when jobs need different permissions, data or approvers.
Where approvals happen. Decide who approves each kind of change before any tool can write. This shapes your tool design more than anything else.

Designing a multi-agent system

When one agent becomes several, the habits that keep services maintainable still apply.

One job per agent. A stock agent, a content agent and an order-exceptions agent each get their own tools, credentials and approvers, with explicit inputs and outputs so each can be tested alone.
A coordinator. One orchestrating agent hands tasks to specialists, or a fixed workflow calls them in order. Agents messaging each other freely are hard to debug and harder to audit. Some teams also put a gateway in front of their MCP servers to handle sign-in, logging and an allow-list of tools in one place.
Memory in your own systems. A model's context window is not memory. Keep run history, decisions and approvals in your own database and expose what an agent needs as resources. That record doubles as your audit trail.
Events as triggers. Webhooks and platform events start agent runs, through a queue so bursts do not overwhelm the agent and failed runs can be retried.
People in the loop. Every write tool ends in a person's approval, however confident the agent is.

Setting up an MCP server for a store

A store server has a narrow job: authenticate the caller, translate tool calls into platform API requests, apply your permission rules and return compact results. Your platform remains the record of products, stock and orders.

What every store server needs

Its own API credentials with the fewest scopes that do the job, on a dedicated app or API account you can watch and revoke on its own.
A short, read-only tool list to begin with: search products, get a product with its variants and stock, list recent orders, get one order. Add write tools later, one at a time.
Rate-limit handling. Back off and retry when the platform throttles you, and return a clear error to the agent instead of a stack trace.
Webhook handling where you need freshness. Webhooks keep a cache current or trigger agent runs. Verify each webhook's signature, and expect duplicates and out-of-order delivery.
A log of every tool call: caller, tool, arguments, timing and errors.

Shopify, BigCommerce and Adobe Commerce specifics

Shopify. Create an app for the server and request access scopes per job, read_products before write_products. Use the GraphQL Admin API. Its rate limits are based on query cost, so request only the fields a tool returns. Verify webhooks with the HMAC header Shopify sends.
BigCommerce. Create a store-level API account with scopes limited to the job, such as read-only products. The REST Management API covers catalogue, orders and customers, and the GraphQL Storefront API covers what a shopper sees. Webhook payloads are deliberately light, so the handler fetches the full record before acting. On a multi-storefront store, pass the channel through every call so an agent never mixes up storefronts.
Adobe Commerce and Magento. Create an integration in the admin limited to the resources the server needs, and call the REST or GraphQL APIs from outside the application. To react to store events, an observer (on catalog_product_save_after, for example) can publish to a message queue that your agent consumes. Keep model calls out of the request path so they never slow checkout. Code changes reach the store through a pull request and your normal deployment, never straight from a tool.

Local or remote: transport and hosting

For local development, run the server over stdio, connect a desktop assistant or MCP Inspector, and read credentials from environment variables.

For anything shared, run it remotely over Streamable HTTP. The server exposes one endpoint (often /mcp) that accepts JSON-RPC messages by POST and replies with JSON or an event stream. It can keep a session, identified by the Mcp-Session-Id header, or run stateless, which is simpler on serverless platforms and behind load balancers. Serve it over HTTPS, validate the Origin header, and require authentication for anything that is not public. Remote MCP and OAuth walks through connecting a remote server to an assistant.

Designing tools and workflows

Designing tools an agent can use well

The model picks tools from their names, descriptions and input schemas, so those are the interface you are designing.

Name tools after the job, such as find_stock_mismatches or draft_product_description. A thin wrapper for every API endpoint gives the model hundreds of choices and no guidance.
Write descriptions for the model. Say what the tool does, when to use it, what it returns and what it will not do.
Constrain inputs. Use enums, formats and required fields in the schema. Validate again on the server, because the model will sometimes send something the schema allows and your rules do not.
Return less. Paginate, select fields and summarise. A whole catalogue in the context window makes every later step worse.
Report errors the model can act on. When a call fails for a business reason, such as an unknown SKU or a price below its floor, return a tool result flagged with isError and a plain message, so the model can correct itself.
Mark intent. Tool annotations such as readOnlyHint and destructiveHint tell the host what a tool does. They are hints, so enforce permissions on the server as well.
Separate proposing from applying. A tool such as propose_price_change records a proposal with its reasoning and the current value. Applying it is a separate step that only runs after approval.

Designing agentic workflows

In an agentic workflow, the agent decides its next step from what it has just learned instead of following a fixed script. That flexibility needs edges.

Start from a business goal you can measure: fewer stockouts on top sellers, fewer product pages with missing content, faster replies to "where is my order" emails.
Fix the frame and let the agent work inside it. Most dependable ecommerce workflows share one shape: gather context, analyse, prepare a change, get approval, apply, check. The agent chooses what to look at and what to propose within it.
Share context through shared sources. A stock agent and a merchandising agent that read the same stock server agree on what is in stock, with no copying between them.
Set limits. Give each run a step limit, a budget for tokens and API calls, and a timeout. A run that hits a limit, or finds data that disagrees, stops and reports instead of guessing.

A first workflow, step by step

Take a job most stores selling on several channels know: stock drifting between the store and a marketplace.

Gather context. The agent reads stock for active products from the store server and the marketplace server, plus open orders that have not yet reduced stock.
Analyse. It finds mismatches above a threshold you set and checks which system changed most recently.
Prepare. It drafts one proposed correction per product: both numbers, the value it would set, which system it treats as correct, and why.
Approve. The person who owns stock accepts, edits or rejects each proposal, from a ticket or an approval screen.
Apply. Approved changes are written through the API, with the previous values stored so each one can be reversed.
Check. The agent reads the values back, confirms they match and records the outcome.

Measure open mismatches, orders cancelled because of stock errors, and how often a proposal is approved without edits. Once the agent meets thresholds you agreed in advance, reuse the pattern for the next job: product content, price checks, order exceptions or support triage.

Connecting third-party APIs and existing platforms

Adding MCP to an existing store platform

Most stores already have integrations, apps and middleware, and MCP sits alongside them.

List what you have. APIs in use, apps with API access, middleware, and where business rules live today.
Use what the platform provides. For storefront jobs, test the platform's own MCP server before building anything.
Wrap existing logic. If your middleware already knows how to price a bundle or allocate stock, expose that logic as a tool instead of writing it again for the agent.
Run the server outside the storefront. Keep agent traffic off the path that serves shoppers, so a slow model call never slows a product page.
Connect the client. The host discovers tools with tools/list, reads context with resources/read and acts with tools/call. If your server adds or removes tools while running, it sends notifications/tools/list_changed so the host refreshes its list.

Connecting third-party APIs

Agents get more useful when they can see past the store: the ERP, shipping carriers, marketplaces such as Amazon (through its Selling Partner API) and eBay, the helpdesk, the CRM and the email platform.

Look for an official server first. Many vendors now publish their own MCP servers. Use one if its permissions fit, after reviewing its tools.
One server per system. Separate servers keep credentials, permissions and failures apart, so a carrier outage does not take your order tools down with it.
Normalise to your own model. A get_stock tool should return the same shape whether the number comes from the ERP or the platform, so the agent never needs each vendor's field names.
Handle each vendor's quirks inside its server: OAuth or API keys, pagination, rate limits, webhook signatures and whether a sandbox exists.
Keep secrets in a secrets manager, never in tool arguments, prompts or logs.

One set of rules across several platforms

Merchants with stores on more than one platform, and agencies with clients on all three, gain most from a clean split. Business rules (price floors, stock thresholds, tone of voice) live in the workflow layer. Platform detail lives inside each platform's server, behind the same tool contract. A pricing or stock workflow can then move to another platform by pointing it at a different server, with the rules unchanged.

Security, permissions and approvals

Authentication and OAuth for remote servers

For remote servers, the MCP authorisation specification builds on OAuth 2.1, and the server acts as an OAuth resource server. An unauthenticated request gets a 401 response that points to the server's protected resource metadata. The client finds the authorisation server from that metadata, the user signs in and consents, and the client calls again with an access token issued for that server. The client uses PKCE.

Two rules catch teams out: accept only tokens issued for your server, and never pass the client's token through to the store's API (the specification forbids it). The server calls the platform with its own credentials and applies its own checks on who may do what. Stdio servers do not use this flow; they take credentials from their environment.

Least privilege and the risks specific to agents

Scope by tool. Map OAuth scopes or roles to tools, so a person who can only read cannot call a write tool through the agent.
Never let the model choose the tenant. On a server that serves several stores, take the store from the authenticated identity, not from a tool argument the model fills in.
Treat tool results as data. Reviews, customer emails and supplier files can contain text written to steer a model, so nothing a tool returns is followed as an instruction.
Watch for tool poisoning. A malicious or compromised server can describe its tools in ways that mislead the model. Install servers only from sources you trust, pin their versions and review tool descriptions when they change.
Protect personal data. Encrypt it in transit and at rest, return only the customer fields a job needs, and keep logs within your retention and privacy obligations.

Approvals and undo

The MCP specification says there should always be a human in the loop with the ability to deny tool calls. On a store, build that into the server as well as relying on the host's confirmation prompt.

A write tool records a proposal: what will change, the current value, the reason and the data behind it.
A named person approves, edits or rejects it, and the decision is logged with who and when.
Only an approved proposal can be applied, and the apply step stores the previous state so it can be reversed.
Code and theme changes go to a pull request that your engineers review and deploy through the usual pipeline.

For high-volume jobs, such as content drafts for hundreds of products, a person can approve the rules and check a sample of the output before the batch goes out. Approval can change shape, but it should never disappear.

Testing, debugging and optimising

Testing before anything touches live

Test each tool by hand with MCP Inspector, the official testing tool from the MCP project, before an agent ever calls it.
Use a development or staging store with realistic data: a Shopify development store, a BigCommerce sandbox store, a Magento staging environment.
Simulate the awkward days. Replay recorded webhooks and write test cases for a sell-out during a promotion, a product with many variants, a supplier file with bad rows, and a customer email that tries to give the agent instructions.
Run evaluations on every change. Keep realistic tasks with their expected tool calls and outcomes, and rerun them whenever a tool description, prompt or model changes.

Debugging agent runs

Most agent bugs are context bugs: the agent saw the wrong data, too little data, or a tool description that misled it.

Trace every run. Give each run an ID and log the prompt, every tool call with its arguments and results, the model's decisions, timings and the approval outcome. MCP servers can send log messages to the client, but keep your own server-side logs as well.
Read the trace from the first wrong turn: stale or partial data, a misread description, or a missing tool that forced a workaround.
Check API health. Platform throttling or failed calls often explain an agent that looks confused.
Version everything together. Prompts, tool descriptions, schemas and the model version go into version control as one release, so you can roll back to the last combination that worked.

Optimising cost, speed and accuracy

Send less context. Smaller, relevant results from the server give better answers and cost less.
Cache what changes slowly, such as category trees and policies, and refresh it from webhooks.
Match the model to the step. A smaller model can classify or route, and the larger one can do analysis and drafting.
Use rejections as feedback. When a person rejects or edits a proposal, record why. Those reasons are the best input for improving prompts, rules and tool descriptions, and each improvement is reviewed like any other change.

Deploying and scaling

Rolling out in phases

Pick one job and one store. Choose a job that comes round often, uses data you already hold, and is easy to check and undo. Involve a developer, the person who owns the job, and whoever will approve the agent's work.
Audit the data and access. List the systems, credentials, rate limits and authentication methods involved, and fix the data the agent will read first.
Run read-only. Compare the agent's findings with what your team would have found.
Turn on proposals. Enable write tools that create proposals, and track approval rates and edits.
Widen with care. Add the next job, store or channel only when the current one meets thresholds agreed in advance.

Hosting and scaling

Run remote servers in containers or on serverless functions. Keep one set of credentials per store or client, so you can revoke one without touching the rest. Queue write operations, and respect each platform's rate limits per store as well as across your whole service.

Treat the tool list as a public API. Keep names and input shapes stable, add new tools instead of changing what old ones mean, and release server changes through your usual pipeline and code review.

For agencies, one server and one set of workflows can serve many client stores, each with its own credentials, approvers and logs. A finding on one client becomes a ticket for that client, and the agency's engineers still review and approve each pull request.

Operating in production

What to monitor

Tool error rates, latency and throttling, per server and per store.
Model cost per run and per job.
Proposals waiting for approval, and how long they wait.
Approval, edit and rejection rates for each job.
Changes reversed after they went live, the clearest sign an agent needs tighter rules.
The business measure you chose at the start, against its baseline.

Alert on stuck queues, repeated tool failures, unusual proposal volumes and any write that skipped approval.

Keeping agents healthy

Review access on a schedule. Scopes, credentials, installed servers and tool descriptions drift, so review them as you review staff access, rotate credentials and remove servers nobody uses.
Keep a runbook covering how to pause an agent, revoke its access, reverse a batch of changes and find a run in the logs.
Train the approvers to see what the agent read, what it proposes and how to reject or reverse it. Write down common problems and fixes as you meet them.

Where Vortex IQ fits

Vortex IQ is the AI workforce for ecommerce. Specialist crews find the problem in a store's own data and prepare the exact change, which is applied with an undo point, as a pull request or as clear steps, then checked. Store Development (CodeCraft) prepares code changes as pull requests for your engineers to review, and over 200 connectors in the Vortex IQ connector catalogue cover the systems around a store. It proposes. Your team approves. Nothing goes live without your say-so. To see what an agent would find on your store, start with a free store audit.

Frequently asked questions

Do I need to build my own MCP server for my store?

Not always. For shopper tasks such as search and cart, test your platform's own server first. Back-office jobs usually need a server you build or adopt, because they depend on your rules and approval steps.

Is MCP a replacement for my platform API?

No. An MCP server calls your platform API. MCP standardises how an AI application discovers and calls tools; the API still does the work, with its own scopes and rate limits.

Can one MCP server serve many client stores?

Yes, if it keeps them apart. Take the store from the authenticated identity, never from a tool argument, keep separate credentials and logs for each store, and apply rate limits per store.

Can an agent change a live store without asking?

Technically yes, if its write tools apply changes directly. Do not build it that way. Write tools should create proposals that a named person approves, with the previous state stored for undo.

How is MCP different from WebMCP?

MCP connects an AI application to servers you run. WebMCP lets your own web pages register tools for an agent working inside the shopper's browser, and a store can use both. WebMCP for ecommerce explains the difference.

Building and deploying MCP-powered AI agents for ecommerce: a developer guide