Amazon shipped its first official Model Context Protocol (MCP) server for the Selling Partner API, and it is one of the most consequential developer releases of the year. For the first time, any AI assistant that speaks MCP — Claude Code, Cursor, Codex, Kiro — can talk to Amazon's API natively, browse the catalog in natural language, generate working integration code, and even orchestrate multi-step workflows that compile down to AWS Step Functions.
This guide is the long-form, hands-on tour we wish existed when we first picked it up. Setup. All the tools. Real examples. The gotchas nobody warns you about. The architecture behind it. Where it stops and where you take over.
If you build on Amazon — or you're about to — bookmark this one.
@amazon-sp-api-release/sp-api-dev-mcp on npm.The Amazon SP-API MCP is Amazon's official implementation of the Model Context Protocol for the Selling Partner API. In one line: it lets a language model become a fluent SP-API engineer.
That means an AI assistant can do all of the following in natural language:
It is open source, free, and lives in Amazon's official samples repo: amzn/selling-partner-api-samples.
If you have ever stared at the SP-API specification at three in the morning trying to figure out which Finances endpoint settles which fee type — yes, this is going to feel like a cheat code.
If you've already integrated MCP servers before, skip to the next section. If not, here is the shortest useful explanation.
MCP is an open standard, originally introduced by Anthropic and now widely adopted, for giving AI assistants structured access to external tools, data, and prompts. Think of it as a USB-C port for AI: a server exposes a set of tools (functions with typed inputs and outputs), and any MCP-capable client (Claude Code, Cursor, Codex, Kiro, ChatGPT, custom agents) can plug in and call them.
The protocol covers three primitive types:
get_orders, execute_sql, etc.).Servers are small processes. They speak JSON-RPC over stdio or HTTP. They can run locally (as in the SP-API MCP via npx) or remotely. From the model's point of view, every connected server is just a list of tools it can invoke.
This is the foundation Amazon built on. Their package starts two MCP servers — one for the dev assistant, one for workflows — and each exposes its tools to whatever client you configure.
Three reasons, stacked.
One, SP-API has a famously steep learning curve. Over 300 endpoints, regional routing rules (na, eu, fe), LWA token refresh, role-based authorizations, asynchronous reports (create → poll → download), per-operation rate limits, and a half-decade of version churn. Onboarding a new SP-API developer historically takes weeks.
Two, AI coding assistants have become the default interface for new developers. If onboarding to SP-API happens in Claude Code or Cursor anyway, Amazon may as well give that assistant a guidebook, a calculator, and a credentials wallet.
Three, Amazon wants more agents on its data. Agent-native commerce is real and growing. Anything that reduces friction between "I want to read Amazon orders" and "I am reading Amazon orders" expands the ecosystem.
The result is the package we are about to dissect.
Installing the package via npx doesn't give you one server — it gives you a choice of two servers, configured by which subcommand you launch:
# The Dev Assistant
npx -y @amazon-sp-api-release/sp-api-dev-mcp sp-api-dev-assistant-mcp-server
# The Workflow MCP
npx -y @amazon-sp-api-release/sp-api-dev-mcp sp-api-workflow-mcp-serverYou can connect to one, the other, or both at the same time from your MCP client. They are designed to compose: the Dev Assistant teaches you SP-API and helps you call it; the Workflow MCP lets you string those calls into durable, observable automations.
Let's go deep on each.
The Dev Assistant is the core of the package. It is what makes the SP-API feel like a library instead of a manuscript.
This tool wraps a local vector index of the entire SP-API documentation set. You ask a question — "how do I get settlement reports", "what's the difference between Orders v0 and the newer version", "which endpoint returns Buy Box price" — and it returns the most relevant sections, ranked.
The index ships with the package, so it works offline and instantly. No web fetch latency, no rate limits, no scraping anti-bot defenses. For a docs surface as sprawling as SP-API's, this is by itself worth the install.
In practice, the model uses this tool early in almost every conversation. It is the equivalent of a senior SP-API engineer remembering exactly which page covers your question.
sp_api_reference answers questions. sp_api_explore_catalog lets you walk the structured catalog: every endpoint, its HTTP method, its path parameters, its query parameters, its request and response schemas.
The model uses it when it needs to construct a call rather than find a doc. For example, when you ask "list my orders from last week", the model uses the catalog to figure out it needs GET /orders/v0/orders, with MarketplaceIds, CreatedAfter, and pagination via NextToken. It can then hand you back the exact request, ready to fire.
This is the one with credentials. sp_api_execute actually hits SP-API on your behalf. It handles:
na → sellingpartnerapi-na.amazon.com, eu → sellingpartnerapi-eu.amazon.com, fe → sellingpartnerapi-fe.amazon.com. You set the region once; the tool routes correctly.Everything else stays your responsibility: pagination loops, rate-limit backoff, async report polling, error handling. The tool gives you one clean call; building a robust integration is still on you.
Give it a goal — "fetch orders from the last 24 hours and write them to a CSV" — and it generates a runnable code sample in Python, Java, JavaScript, C#, or PHP. The samples include authentication, the actual API call, pagination handling, and a reasonable file output.
This is enormously useful when you're scaffolding a new integration. Instead of copy-pasting from the docs and adapting, you describe the outcome and get a starting point that is idiomatic for your language.
SP-API has a long history of version churn. Orders went from v0 to v0+ to a newer revision. Reports types are renamed and reshaped. Vendor APIs split into smaller, focused pieces. Every migration is paperwork.
sp_api_migration_assistant reads code written against one version and rewrites it for another, flagging breaking changes and explaining what shifted. It is conservative — it will tell you when something needs human review — but it removes a large class of mechanical translation work.
Feed it your integration code and it returns a structured review against SP-API best practices:
x-amzn-RateLimit-Limit headers, retrying with backoff, batching where supported?NextToken, or stopping at the first page?It will not magically refactor your code, but it produces a clear punch list of things to fix before you go to production.
The second server in the package is structurally bigger and conceptually different. Instead of helping you call one endpoint, it helps you orchestrate many — durably, observably, and with human checkpoints when needed.
Under the hood, the Workflow MCP compiles your natural-language description of a process into Amazon States Language (ASL), the same language AWS Step Functions speak. Step Functions is the production-grade serverless orchestrator AWS uses for everything from ETL jobs to multi-day approval flows. You get retries, timeouts, branching, parallel execution, durable state, and visual execution traces — all for free.
That's a remarkable architectural choice. Instead of inventing a new workflow engine, Amazon piggybacked on a battle-tested one and made it accessible via natural language.
The Workflow MCP exposes around 30 tools, grouped into three logical units:
Builder — Tools for assembling a workflow. You describe the process in plain English, and the builder adds states: tasks (do a thing), choices (branch on a value), waits (sleep until a time), fetches (call SP-API), parallels (do many things at once). When you're done, the builder validates the ASL graph — checks for unreachable states, missing transitions, type mismatches — before you run it.
Interpreter — Tools for executing and monitoring. Once a workflow is built, the interpreter runs it, streams events as they happen ("started fetching orders", "got 200 rows", "branching on order count > 100"), and lets you query the status of any running execution. You can tail the live event log the way you'd tail -f a server log.
Callback — Tools for human-in-the-loop approvals. A workflow can pause at a defined checkpoint, send a notification, and wait for a human to approve or reject before continuing. This is how you build automations that need oversight — like "auto-place restock orders, but pause for human approval if the order is over $5,000."
The package ships with an optional web interface that lets you:
For developers who like graphical state-machine tooling, this is one of the more polished experiences in the agent ecosystem right now.
If you want to skip ahead to production-grade workflow patterns, our companion deep-dive walks through 7 SP-API MCP workflow examples with copy-paste prompts — daily syncs, low-stock alerts, settlement reconciliation, Buy Box tracking, returns analysis, callback-gated restock, and multi-marketplace roll-ups.
There are two prerequisites:
This is its own multi-step process and the part of the journey AI cannot speed up for you:
na (North America), eu (Europe + Middle East + India + Africa), or fe (Far East — Japan, Australia, Singapore).Hold onto your client ID, client secret, refresh token, and region — you'll paste them into the MCP config.
The Dev Assistant config block looks like this:
{
"mcpServers": {
"sp-api-dev-assistant": {
"command": "npx",
"args": [
"-y",
"@amazon-sp-api-release/sp-api-dev-mcp",
"sp-api-dev-assistant-mcp-server"
],
"env": {
"SP_API_CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
"SP_API_CLIENT_SECRET": "amzn1.oa2-cs.v1.xxxxx",
"SP_API_REFRESH_TOKEN": "Atzr|xxxxx",
"SP_API_REGION": "na"
}
}
}
}The Workflow MCP looks nearly identical, just with sp-api-workflow-mcp-server in the args. You can register both servers in the same config and call them from the same conversation.
Claude Code: Add the block above to your ~/.claude/mcp.json (global) or .claude/mcp.json in your project root (project-scoped). Restart Claude Code. Run /mcp to confirm both servers loaded.
Cursor: Cursor's MCP config lives in Settings → MCP. Click "Add new MCP server", paste the JSON, save. Cursor restarts the server automatically when you toggle it.
Codex: Codex picks up MCP servers from ~/.config/codex/mcp.json on Unix systems and the equivalent path on Windows. Same JSON shape.
Kiro: Kiro reads MCP servers from its built-in MCP panel. Paste the same block, save, refresh.
In every case, once the server is loaded, the model sees all the tools it exposes and decides when to call them based on your prompts. You don't have to "switch modes" or explicitly invoke the server — you just ask, and the model picks the right tool.
Heads up: there's an older
sp-api-mcp-serverin the same samples repository that has been deprecated. Amazon's own notice points users tosp-api-dev-mcp. If you find an old tutorial referencing the deprecated one, use the new package instead.
This is where the abstract becomes concrete. Each of the following starts as a prompt to the model with the SP-API MCP loaded, and ends with an outcome.
"Give me a JSON of every order placed in the US marketplace in the last 24 hours, including line items."
The model uses sp_api_reference to confirm the relevant endpoint (Orders v0), sp_api_explore_catalog to look up parameters, then calls sp_api_execute against GET /orders/v0/orders with MarketplaceIds=ATVPDKIKX0DER, CreatedAfter=<24h ago ISO timestamp>, and pagination. For each order it then calls GET /orders/v0/orders/{orderId}/orderItems. It returns a structured JSON document and explains throttling considerations along the way.
"Generate a Python script that pulls FBA inventory daily and saves it to a CSV."
The model uses sp_api_generate_code_sample to produce a Python program with:
GET /fba/inventory/v1/summaries.You get something runnable in under 30 seconds.
"Here's a Python file that uses Orders v0. Migrate it to the latest version."
sp_api_migration_assistant reads the file, identifies every reference to v0 endpoints and shapes, rewrites them against the current spec, and flags every spot where the rewrite is non-trivial — for example, if a field was renamed and the new name behaves slightly differently.
"Review my integration in ./sp-api-client/ for rate-limit handling and caching."
sp_api_optimize produces a punch list: missing Retry-After honoring on 429s, no caching of marketplace participation data, synchronous use of report endpoints that should be async, and a few places where it suggests batching.
"Build a workflow that pulls yesterday's order data every morning at 7 AM Eastern, writes it to S3, and pings me on Slack if order count drops more than 30% week-over-week."
The Workflow MCP builder assembles a state machine:
sp_api_execute.The interpreter starts the workflow and tails the event log. You watch the wait state pause until 7 AM, fire, execute the fetches, branch, and either silently complete or send the Slack message.
That entire workflow took a few sentences. Building the same thing as bespoke code with retries, durable timers, and observable execution would take a day.
For a deeper tour of workflow patterns — including 7 production-ready SP-API MCP workflows with copy-paste prompts covering inventory alerts, settlement reconciliation, Buy Box tracking, returns analysis, callback-gated restock, and multi-marketplace roll-ups — see the companion deep-dive.
Five things to internalize before you ship something built on this.
Every SP-API operation has its own usage plan with a steady-state rate, a burst, and a restoration interval. Detail-heavy endpoints (Orders detail, Listings item-by-item) throttle quickly. The MCP will execute calls as you ask; it is on you or your code to back off when you see x-amzn-RateLimit-Limit indicators or 429 responses.
Where Amazon supports batching — for example, getting multiple ASINs in one Catalog Items call — use it. It dramatically reduces request count.
The MCP config holds your SP_API_CLIENT_SECRET and SP_API_REFRESH_TOKEN. These are sensitive credentials with broad access to your seller account. Keep them in your MCP config file with strict file permissions; never paste them into a chat window where they could end up in transcripts.
For multi-environment setups, consider using a secret manager (1Password CLI, AWS Secrets Manager, env-file loaders) and feeding values into the MCP config at runtime.
SP_API_REGION controls which Amazon endpoint the server talks to. If you have sellers in multiple regions, you'll need separate MCP server entries — one per region — with different names. Trying to use a North America config against a European seller account will fail with confusing errors.
For anything beyond small synchronous endpoints, use the reports API: create the report, poll for status, download the result. This is the only sustainable pattern for large data pulls. The MCP can help you script the loop, but the pattern is on you.
The Workflow MCP's callback mechanism is what makes workflows safe to deploy. If your workflow can take an action with consequences — placing an order, updating prices, changing inventory — gate that action behind a callback that pauses until a human approves. The minutes you spend wiring this up will save you the hours of cleanup the first time the model gets creative.
Things that have bitten people in the first few weeks.
Picking the deprecated server. The samples repo still contains an older sp-api-mcp-server next to the new sp-api-dev-mcp. Old tutorials reference the deprecated one. If a tool name or behavior doesn't match this guide, double-check which package you actually installed.
429s on the third request. If you ask the model to "loop through every ASIN and pull catalog details", it will. Catalog Items detail calls throttle quickly. The model does not implement exponential backoff by default — you do, in the code it generates or in the workflow you build.
Region mismatches. If a seller account moved regions, or you authorized against the wrong region during application setup, every call returns auth errors. Verify by hitting GET /sellers/v1/marketplaceParticipations first to confirm which marketplaces your token can actually see.
Async reports treated as sync. Reports endpoints (/reports/2021-06-30/reports) return a reportId, not data. You then have to poll /reports/2021-06-30/reports/{reportId} for status, and only when the status is DONE can you fetch the actual document URL. New users sometimes call the create endpoint and wait, confused, for data that will never come back in that response.
Forgetting about LWA token caching. Access tokens last roughly an hour. The MCP handles refresh, but if you ever bypass the MCP and call SP-API directly from generated code, you have to implement token caching yourself or you'll exhaust the LWA rate limits in minutes.
To be honest about it: this is a toolkit for developers building on SP-API. It is a very, very good one. But it isn't a finished product, and it doesn't try to be.
The MCP gives you:
It does not give you:
For teams that want all that without building it, this is where a data layer like DataDoe comes in — it unifies SP-API, Amazon Ads, fees, and your costs into a queryable layer accessible by MCP, REST API, or BigQuery. Mentioned here because if you're reading an "ultimate guide" to SP-API MCP you've probably already discovered the gap. Back to the guide.
The Amazon SP-API MCP shines for a specific set of use cases.
Learning SP-API. If you're new to the API, having a conversational assistant that can point you to the exact docs page, walk you through endpoint structure, and generate working code is the fastest onboarding ramp Amazon has ever shipped.
Prototyping integrations. When you're scoping a build and need to know what's possible — "can we get Buy Box change events", "is there a webhook for inventory drops", "what does FBA inbound shipment data look like" — the MCP lets you explore and prototype in minutes instead of days.
Code generation and migration. Greenfield integrations or version migrations. Both happen rarely but eat huge chunks of time when they do. The generate and migrate tools cut that time meaningfully.
Operational automations. Pulling daily order data to a warehouse. Watching for stockouts. Generating settlement reports on a schedule. The workflow MCP is built exactly for this kind of recurring task with reasonable visibility — see 7 production workflow examples for concrete blueprints.
Audits. Inheriting an SP-API integration and need to know if it'll survive scaling? The optimize tool gives you a structured starting point.
Where it works less well: anything that requires unified Amazon Ads + SP-API + cost data — i.e., most analyst work and most "real profit" use cases. The MCP can call both APIs, but joining them into something usable is data engineering work you still own.
A few things to watch.
Wider client support. Right now the documented clients are Claude Code, Cursor, Codex, and Kiro. ChatGPT, Gemini CLI, and others speak MCP too, and config patterns transfer. Expect official support to broaden.
More tools per server. The Dev Assistant ships with six tools today. The Workflow MCP has around 30. Expect both numbers to grow as Amazon adds purpose-built tools for common SP-API tasks.
Tighter Step Functions integration. Because the Workflow MCP compiles to ASL, deeper integration with the AWS console is a small step away. Imagine exporting a workflow you built conversationally directly to a Step Functions state machine in your AWS account, with full IAM and observability.
More data, less plumbing. The bigger industry trend the MCP fits into is "AI agents become a primary interface to your stack." That works best when the agent talks to a connected, normalized data layer instead of raw APIs. Amazon's MCP is the raw-API side of that equation; the data-layer side is what tools like DataDoe, Looker, and BigQuery are pushing into. The two play well together.
It's Amazon's official MCP package (@amazon-sp-api-release/sp-api-dev-mcp) containing two servers — a Dev Assistant for exploring and calling SP-API, and a Workflow MCP for multi-step automation — that let AI assistants work with the Selling Partner API in natural language.
Yes. It's open source and lives in Amazon's selling-partner-api-samples repository. You still need SP-API developer credentials, which require a registered developer application.
Claude Code, Cursor, Codex, and Kiro are the officially documented clients. Any MCP-capable client should work with the same JSON config pattern.
The Dev Assistant has 6 tools focused on understanding and calling individual SP-API endpoints. The Workflow MCP has around 30 tools for orchestrating multi-step automations that compile to AWS Step Functions. For real workflow blueprints, see our 7 production workflow examples.
No, but it helps. The Workflow MCP compiles to Amazon States Language under the hood, the same language used by AWS Step Functions. You can build, run, and monitor workflows entirely through the MCP without touching AWS directly. But if you want to take the resulting state machine into your own AWS account, Step Functions familiarity helps.
No. The Amazon SP-API MCP covers the Selling Partner API only — orders, inventory, finances, listings, reports. Amazon Ads data lives in a separate Amazon Ads API. To unify both, you either build the Ads integration yourself or use a data layer that already does it for you.
No, not by itself. SP-API has no cost-of-goods (COGS) data — your product costs were never in Amazon. The MCP can show you sales and Amazon's fees (net proceeds), but real profit requires combining SP-API data with your COGS and your ad spend, and SP-API has neither.
If "easier" means "skip the developer-account registration, the data pipeline, and the COGS/Ads joining" — yes, the data-layer pattern (e.g. DataDoe) gives you the data already connected, normalized, and queryable via MCP, REST API, or BigQuery. If "easier" means "I want to build directly on the API but with less friction" — Amazon's MCP is the answer.
Yes. SP-API has sandbox endpoints. The MCP respects the region and credentials you give it; pointing it at sandbox credentials hits the sandbox.
The Dev Assistant is built for interactive use. The Workflow MCP is the right layer for unattended automation — you build a workflow once, schedule it, and let the interpreter run it, with callbacks where human approval is needed.
Issues go on the GitHub repository.
The Amazon SP-API MCP is the most significant SP-API developer release in years. It collapses the learning curve, removes most of the auth boilerplate, generates working code, and gives you a durable workflow engine for the price of an npx command.
If you build on Amazon and you haven't yet plugged it into your editor, you're working harder than you have to.
The one honest caveat: the MCP gives you the raw API. To turn that into "real profit", "unified ads + organic performance", or "queryable historical data", you'll either build a pipeline on top of it — totally doable with the workflow MCP and a warehouse (7 worked examples here) — or use a connected data layer like DataDoe that has already done that part. Either path is valid; pick based on whether your job is to build infrastructure or to ship answers.
Either way: the era of AI assistants that can fluently speak Amazon has arrived. Go build.
Every integration. Full onboarding support. If it’s not the best decision you made in 2026, you can cancel anytime.
Know what makes you money
Catch problems instantly
Connect anything with API & MCP
Replace tools with your own apps
Access Amazon-audited infrastructure