MCP server

Connect Claude or ChatGPT over the Model Context Protocol: one address, no credential to mint, and tools that read your account or update price, stock, orders.

MarketplaceHub speaks the Model Context Protocol, so an AI assistant can read your account directly instead of you copying answers into it. Ask Claude or ChatGPT how many units of a SKU are left, which marketplace connection is failing, or whether last night's price push finished, and it reads the answer from your account.

It is the same data the REST API serves, through the same permissions and the same request allowance. Nothing new is exposed.

Connect an assistant

There is one address:

https://api.marketplacehub.com/mcp

Add it as a custom connector in your assistant — in Claude, Settings → Connectors → Add custom connector; in other clients, look for "MCP server" or "custom connector". Paste the address and the assistant does the rest.

You do not mint a credential for this. Unlike the REST API, the assistant registers itself and then sends you to a normal MarketplaceHub sign-in page. There is no secret to copy and nothing to paste back.

Things to ask

Plain questions work. These are the kinds an assistant answers well from your account:

• Which of my marketplace connections needs attention?
• Which orders are waiting to ship, and which are late?
• Show me everything about SKU WIDGET-1: the title and description on each marketplace, its photos, and how ready it is to sell.
• Which of my products changed since yesterday morning?
• What attributes does the Trail Running Shoes category on eBay need, and which are required?
• Set the stock of SKU WIDGET-1 to 12. Show me what would change first. (The assistant tries it as a dry run, then asks you before it does it for real.)

What you are asked to approve

After you sign in, MarketplaceHub shows you a consent screen listing exactly what the assistant has asked for — for example Read products and listings. Read it. Approving is what creates the assistant's access; nothing happens before you do.

Four things worth knowing:

• The assistant only gets the permissions it asked for, and it can never be granted more than your API offers. A request for anything else is refused.
• Access is per assistant. Connecting Claude does not connect anything else.
• If it can change things, each change waits for your approval first. You decide on the API page, under Approvals, and you can turn that off for one assistant later.
• One item on that list is not a permission over your data: Stay connected. It lets the assistant keep working without sending you back to a sign-in page every hour. It reads nothing extra, and disconnecting the assistant ends it along with everything else.

What an assistant can do

Twenty-three tools. Seventeen only read. Six can change your data, and an assistant gets those only if you approved the matching write permission — the consent screen names them, and an assistant you approved for reading is never even offered them.

Publishing a new listing is still not possible over MCP, deliberately: it writes to a marketplace against a schema that has to be got exactly right, which is a poor first thing to hand an assistant. Refunds are excluded for the same kind of reason — money moves.

The ads tools are switched off for now. MarketplaceHub does not send advertising data to AI assistants, so an assistant is not shown them and a call to one is refused. To read your ads, use the REST API (/api/advertising) with an API key.

When they are switched on, the ads tools only read. They answer from MarketplaceHub’s own copy of your ads, read from each marketplace every few hours, and none of them changes an ad. When ads are off for your account, they say why instead of answering with nothing.

A product’s listings are not the same set as your connected marketplaces. marketplaces_list answers which marketplace connections you sell through. The listings on a product record every marketplace listing we hold an id for, which includes the marketplace a product was imported from. A catalogue imported from Etsy and published to eBay shows both on the product while marketplaces_list shows only eBay, because the Etsy connection is a data source and not a sell channel. The two disagreeing is normal.

What each tool takes

An assistant fills these in for you; they are here so you can see exactly what a question turns into. Every argument is optional unless it says it is needed, and lists never return more than they are asked for: a list takes Limit (50 if you leave it out, 200 at most) and pages with Offset or a cursor.

marketplaces_list

Nothing.

products_list

Sku for an exact match, Limit, Offset, and ModifiedSince to read only what changed since a time (oldest first, so the last row is where to continue from).

products_get, products_facts

Sku (needed). Matching ignores case. products_facts answers per listing, because each marketplace holds its own title, description and attributes, and no merged value is made up. It never includes a cost price or buyer data.

products_readiness

MaxScore (0 to 100, to ask for the weak ones), Platform (a marketplace name), Limit, Offset. It reads scores that are stored and recomputed every night, so it is free, and a change you made today shows tomorrow.

product_types_search

MarketplaceId (needed, from marketplaces_list), SearchText, Limit, Offset. Only categories a listing can sit in are returned.

product_types_schema

MarketplaceId and CategoryId (both needed).

product_types_values

MarketplaceId, CategoryId and AttributeCode (needed), then SearchText, Limit, Offset.

jobs_list

Statuses (any of NotStarted and Published for waiting, InProcess for running, Completed, Failed, Cancelled, Skipped), MarketplaceId (from marketplaces_list), Since, Limit (20 by default, at most 50), Offset. Newest first. It never returns the raw error of a failed job.

jobs_get

Id (needed), the job id a write handed back or one from jobs_list.

orders_list

OrderStatuses, FromDate, ToDate, UpdatedSince, MarketplaceHubOrderIDs, Limit, Cursor (the value the last page handed back) and IncludeCustomerData.

orders_get

Id (needed) and IncludeCustomerData.

inventory_price_quantity

Items (needed), each with a Sku and a Price and/or Quantity; PropagateToListings (false stores the values and sends nothing to a marketplace); DryRun; IdempotencyKey. It answers one result per SKU with its values before and after.

orders_confirm

OrderItems (needed), each with an OrderItemId, a ShipDate and the carrier and tracking; DryRun; IdempotencyKey.

orders_ship_with_amazon

OrderId (needed), one order per call; DryRun; IdempotencyKey. Amazon charges a fee, so the assistant dry-runs first: the answer is Amazon's fee and dates, and nothing is sent. The real call answers Status requested with the AmazonOrderId, and the order's AmazonMcf then shows where it stands.

orders_cancel_amazon_shipment

OrderId (needed), one order per call; DryRun; IdempotencyKey. Amazon can stop a shipment only before it starts picking. The answer's Status is stopped, asked or queued; a refusal names why (NotSentToAmazon, AlreadyShipped, AlreadyAsked, AmazonRefused).

Try a write first

Every write tool takes DryRun. With DryRun set to true the tool changes nothing and answers with exactly what the real call would do: for each SKU or order line, the values it would write, and anything it would refuse or that a declared source of truth would overwrite. A dry run does not use up an idempotency key, so the real call can follow straight away with the same arguments. We recommend that an assistant dry-runs a batch before it sends one for real.

Retries cannot double up

An assistant that never sees the answer to a write may send it again. Every write tool is keyed against that: the same call repeated within 10 minutes returns the first answer instead of doing the work twice, so a lost reply cannot confirm one shipment twice or apply the same price change again. The assistant does not have to do anything for this; it is on by default.

After 10 minutes the same call runs again, because by then it is a new request rather than a retry. If an assistant sets a price to 10, somebody changes it to 12, and later the assistant asks for 10 again, the price goes back to 10. To repeat a write on purpose inside the 10 minutes, the assistant passes its own IdempotencyKey with a new value. A key the assistant chooses itself works like the REST Idempotency-Key header: reusing it returns the first answer for 24 hours.

A repeat that arrives while the first call is still running is refused as a conflict, and can be retried shortly. If the first call never finished — our server stopped in the middle of it — a repeat after 10 minutes runs.

The account's write limits

Writes from assistants and API keys are held to the account's write limits: how many SKUs one call may change, a stock ceiling, how many order lines one call may confirm, a price floor and ceiling when the account sets them, and how far a price may move in one call. Until the account saves its own limits on the Guardrails tab of the API page, an assistant may move a price by at most 10% per SKU in one call; an API key has no price-move limit unless the account sets one. A SKU that breaks a limit is not written, and it is never changed to a different value instead. It comes back as HeldByGuardrail with a Reason in words, and the rest of the batch still applies. Show the reason to the merchant. If the limits cannot be read, the write is held, never let through.

Changes that wait for your approval

When you connect an assistant that can write, its changes wait for you by default. The call does not fail and nothing is changed. The tool answers with Status set to pending and a ProposalId, and the request appears for you on the API page under Approvals, with the values it would write next to the values they replace. You approve or reject it there. Nobody has to approve it from the assistant's side, and the assistant cannot approve its own request.

For a price and stock call, PendingApproval says how many SKUs wait. The rest are reported as usual: a SKU that is unknown, unchanged or held by a write limit is not queued. A dry run is never held. A request that is not decided within 3 days expires, and the assistant has to ask again.

An assistant tells you that the change is waiting for you; it does not retry it. If you approve, the change is written exactly as the call asked, unless the product has changed since, in which case it is refused and the assistant can ask again. You can switch the wait off for one assistant or one API key on the same page. This applies to every assistant, including one you connected before approvals existed: only an assistant you switched it off for writes at once.

What the answers look like

Every tool answers with JSON that the assistant reads for you. Two examples, shortened, so you can see what a question turns into.

Asking which listings are weakest (products_readiness with MaxScore 60) returns the weakest first, each with what to fix and what fixing it earns back:

{
  "TotalCount": 12,
  "Listings": [
    {
      "Sku": "TRAIL-42",
      "Platform": "Etsy",
      "Score": 55,
      "Version": 1,
      "ScoredAt": "2026-10-03T01:12:00Z",
      "Fixes": [
        {
          "Rule": "Images",
          "Reason": "ImagesMissing",
          "Text": "Add a photo.",
          "PointsLost": 15,
          "Affected": 1,
          "Of": 1,
          "Names": []
        },
        {
          "Rule": "RequiredAttributes",
          "Reason": "RequiredAttributesMissing",
          "Text": "2 of 5 required attributes are empty: colour, material.",
          "PointsLost": 10,
          "Affected": 2,
          "Of": 5,
          "Names": ["colour", "material"]
        }
      ]
    }
  ]
}

A price and stock change that waits for your approval (inventory_price_quantity on an assistant that needs it) changes nothing and says so:

{
  "Status": "pending",
  "ProposalId": "6a7f0c3e5d2b4a19c8e1f0a2",
  "PendingApproval": 2,
  "Updated": 0,
  "Unchanged": 0,
  "NotFound": 1,
  "HeldByGuardrail": 0,
  "DryRun": false
}

The assistant should tell you that two SKUs are waiting under Approvals and that one SKU was not found. It should not try the change again.

What a write will not do

An order the marketplace ships for you is refused. On an Amazon FBA order a shipment confirmation is rejected rather than recorded, because Amazon is already fulfilling it. The whole call is refused and each line that caused it is named, so a bad third item cannot leave the first two already confirmed. Only Amazon reports a fulfilment channel; an eBay, Shopify or Etsy order is always treated as one you ship yourself.

Your account may expect somebody else to act. If you have named your own warehouse system as the owner of orders, a shipment confirmed through an assistant is still applied — and the answer says the warehouse was expected to do it. A change made through an assistant counts as you driving MarketplaceHub rather than as your warehouse calling the API, because that is what it is.

The same holds for price and stock. If a marketplace or your own system owns those, a change made through an assistant is applied and the answer names the owner whose next sync will put it back. See Source of truth.

Customer details are not sent by default

The two order tools leave the buyer's name, contact details, address and gift messages out unless the assistant explicitly asks for them. Most questions about an order do not need them, and an assistant's context is not somewhere personal data should arrive by accident. This matches the REST API, where the same data is behind IncludeCustomerData.

It counts against the same allowance

An assistant's calls draw on the request allowance your account already has, per endpoint — it does not get a second one for speaking MCP. One assistant may use at most half of it, so an assistant stuck in a loop cannot use up what your other integrations need. Every call also appears in API → Request Log in the app, next to your REST traffic, so you can see what an assistant read and when. Log rows are kept for 30 days. The Assistants tab also shows when each assistant was first connected and when it last made a call.

Rate limits and error codes work exactly as they do for REST. See Conventions.

How the sign-in works

For people building or testing a client. It is standard OAuth, so a client that follows the MCP authorization steps needs nothing special.

1. A call to https://api.marketplacehub.com/mcp with no token is answered 401. The answer points at the protected-resource metadata, served at https://api.marketplacehub.com/.well-known/oauth-protected-resource/mcp (the same document is also at /.well-known/oauth-protected-resource).
2. That metadata names the authorization server, https://identity.marketplacehub.com. Its discovery document is at /.well-known/openid-configuration and advertises the registration endpoint, /connect/register.
3. The client registers itself (RFC 7591). It is a public client unless it asks otherwise. Redirect addresses must be https, or http on a loopback address (RFC 8252), and may not carry a fragment. The scopes it asks for are limited to the ones an assistant can hold: OrdersRead, OrdersWrite, InventoryRead, PricingWrite, MarketplacesRead, AdsRead and the older InventoryWrite. A registration that asks for none of them is refused.
4. The client sends you to the sign-in page with the authorization code flow and PKCE. PKCE is required, and so is the consent screen: nothing is granted before you approve it.
5. The access token lasts up to an hour. A refresh token is issued only if you approve Stay connected.

A token from an assistant works on /mcp and nowhere else: the REST API refuses it, and takes an API credential instead.

Stopping an assistant

Go to API → Assistants. Every assistant you have approved is listed there, with what it was allowed to do and who approved it. Disconnect removes it. Change permissions on a row takes some of its permissions away without disconnecting it, and the assistant is held to the smaller set on its very next call. Giving it more means it has to ask again.

Disconnecting stops the assistant getting a new token, and it has to ask for your approval again before it can read anything. A token it already holds keeps working until it expires, up to an hour, so if you think a token has leaked, contact support as well.

To stop every assistant at once without disconnecting any, use Pause agent access on API → Approvals. Each assistant's very next call is refused, with a message that says the account is paused and that nothing was changed. Nothing is lost: Resume agent access turns them back on. Your API keys keep working unless you tick Pause API keys too. Resuming needs an administrator who has signed in recently.

The list belongs to the account rather than to one person — a colleague can disconnect an assistant you connected, and you can disconnect theirs. Removing the connector in the assistant itself (in Claude, Settings → Connectors) stops it from their end; disconnecting here stops it from ours.

If it will not connect

• Nothing happens when you paste the address. Check your client supports remote MCP servers with OAuth. Desktop and browser assistants generally do; older command-line tools may not.
• You sign in but the assistant reports an error. The most common cause is the sign-in window being closed before the redirect completes. Try again and let it finish.
• A tool says a permission is missing. The assistant asked for less than the question needs. Reconnect it and approve the wider set on the consent screen.