Connect an AI agent
An AI agent can answer questions about your warehouse and do work for you: “which orders are stuck, and why?”, “where is order #1042?”, “start the morning’s batches”. It connects to Floormode’s MCP server, signs in as you, and can never do more than you can.
On this page
Section titled “On this page”- What you need
- Connect
- What you approve
- Taking access back
- Read only
- What the agent can do
- Set up a store
- How the agent finds its way
- Three examples
- Read events
- When something goes wrong
- See also
What you need
Section titled “What you need”- A Floormode person whose role includes Use the API and AI agents (REST, MCP). Administrators have it.
- An AI client that can add a remote MCP server. Claude calls it a connector, other clients a custom integration or an MCP server. Floormode speaks the current MCP version, 2026-07-28, and the earlier 2025-11-25 and 2025-06-18, so newer and older clients all connect.
Connect
Section titled “Connect”-
In your AI client, add a remote MCP server with this address:
https://prod.floormode.app/mcp -
The client opens Floormode’s sign-in in your browser. Sign in with your P&H account. If you belong to more than one workspace, choose your store’s.
-
Approve the client. The next section says what the approval screen asks for.
-
Ask your question in the chat.
What you approve
Section titled “What you approve”The approval screen comes from the sign-in page of your P&H account, not from Floormode’s own pages, and its words are general. What you grant is narrower than it may sound:
- Floormode’s API for the workspace you chose: that one store’s Floormode, not your Shopify admin or any other app.
- As you, within your role. The client reads and changes what your role allows, nothing more, and every call is checked against your role as it is at that moment. A change it makes shows in the history under your name.
- For as long as you leave it connected. The screen asks to keep access: the client stays signed in without asking you each time, until you take the access back.
The screen may call the client unverified and warn about it. Most AI clients register themselves with the sign-in page when you add the server, and nobody can vouch for the publisher of a client that registered itself, so the page says so. The warning is about the client app, not about Floormode, and it changes nothing about what the client may do. Approve it only when you have just added the server yourself, in a client you trust.
Taking access back
Section titled “Taking access back”- In Floormode, one app at a time: Settings → Apps & API → Webhooks & API → Connected apps lists every app someone on your team connected, who connected it and when it was last seen. Revoke takes effect at once: the app’s next request in this workspace is refused, until an administrator chooses Allow again. An administrator (Integrations, webhooks, Flow, domains) does this for any app of the team; it stops the app in this workspace only. When you revoke an app you connected yourself, the connection in your P&H account ends too, in every workspace.
- In your AI client: remove the server (the connector). The client stops calling Floormode.
- For the whole person, at once: open the person the agent signs in as under Settings → Team & devices and choose Deactivate, or take Use the API and AI agents (REST, MCP) out of their role. The agent’s next call is refused, whatever the client still holds.
Read only
Section titled “Read only”In the same Connected apps list, set an app to Read only: it may then read everything its person may read, and every change it tries is refused with agent_read_only, at once and whatever the person’s role allows. Same as the person gives it the person’s own rights back. Read only never gives an app more than its person has. The approval screen does not offer the choice: AI clients register themselves, and such a client gets the same sign-in scopes as any other, so the limit is set in Floormode after you connect.
What the agent can do
Section titled “What the agent can do”- It works as you. Every read and every change is checked against your role, as in the app. A change it makes shows in the history under your name.
- It can change data. Holds, stock adjustments and pick batches are writes. Ask the agent to say what it will do before it does it.
- Less than your own access. For an agent that only reads, set it to Read only (see Read only). For a narrower set of writes, invite a person for it in Settings → Team & devices (for example
agent@yourshop.com), give that person a role with only what the agent needs plus Use the API and AI agents (REST, MCP), and sign in as that person when you connect; deactivating that person takes the agent’s access back without touching yours. - Limits. Your store can make 60 calls a minute through the API, agents included. Each
executecounts as one call, which its first call inside uses; each further call inside counts one more, and so does each code search (below); looking things up withsearchor in the help pages withdocscounts none. Oneexecutestops after 30 seconds or 200 calls. Apart from the store’s calls, each connected agent can send 120 requests a minute, every request counted, looking things up included, so an agent that used up the store’s calls can still find its way and plan the next step. The agent can read these limits withsearch({ context: true }).
Set up a store
Section titled “Set up a store”An agent can set a new store up with you, on any plan and before you choose one. It follows Home’s setup steps:
- Warehouses from your Shopify locations:
setup_statuslists the locations,shopify_locations_refreshreads them fresh from Shopify,warehouses_create_from_locationsmakes the warehouses. - Shelves:
locations_generate_gridorbins_create. - Stock:
inventory_opening_importbrings in Shopify’s numbers. If the store import stalled or failed,sync_import_startruns it again;sync_job_getshows how it goes. - Go live:
warehouses_go_livestarts a check of Shopify’s numbers against Floormode’s. Read the outcome withwarehouses_cutover_history. If the only differences are counts made in Floormode, the attempt names acountedDigest; the agent callswarehouses_go_liveagain with it to set Shopify to your counts. Going live cannot be undone, so ask the agent to tell you before it does it. - Packing, boxes and the team:
warehouses_update(the pack checklist),boxes_create,people_invite. - The test order: you place it in Shopify;
setup_first_ordershows where it stands while it is picked and packed.
store_facts_get gives the agent your store’s time zone and units, and floor_devices_list, printnode_scales_list and customerPages_health show what is set up already.
Some steps stay yours: installing Floormode, approving the agent, choosing your plan in Shopify, typing a carrier’s or PrintNode’s key into Floormode’s own dialog, and pairing a floor device.
Ship a parcel
Section titled “Ship a parcel”An agent can ship a parcel the way the desk does:
- Draft:
shipments_create_draftopens a shipment for the order. - Rates:
shipments_rateasks the carrier. The answer names the default your shipping rules or the customer’s checkout option chose.shipments_service_pointslists pickup points and lockers near the customer, for carriers that have them. - Buy one label:
shipments_buy_labelwith arateId. A label costs money, so the agent shows you the rate and asks you to confirm before it buys. Calling it again asks you to confirm again, and never buys a second label: it answers the label already bought. If the carrier refused, never answered, or the label could not be saved, the answer says what happened to the money and what to do next. If the carrier never answered,shipments_lookup_purchaseasks the carrier whether the label exists. - The label file:
shipping_document_linkanswers a download link for a label, customs form or manifest. The link works for 10 minutes without signing in, so the agent can download the file or give you the link. The file itself never goes through the agent’s chat. - Void:
shipments_void_labelcancels a label at the carrier, after you confirm. A label already voided is not cancelled twice.
Booking a pickup, closing out a manifest, freight quotes and printing are not open to agents yet.
How the agent finds its way
Section titled “How the agent finds its way”This part is for the curious and for developers; the agent does it by itself.
The server offers three tools: search and execute, which the agent uses in three steps (find, read the details, execute), and docs, which searches these help pages.
searchfinds what the agent can call.- Topics: without input it answers how to use it and the API’s topics, the same areas the API explorer groups by: orders, fulfillment (picking and packing), shipping, receiving, inventory, returns, layout (warehouses, bins, zones), catalog, customers (tracking pages, customer e-mails, privacy requests), people, integrations (stores and sync), reports and account.
search({ topics: ["returns"] })lists one topic’s methods; a long list comes in pages, and itscursorfetches the next one. - Find:
search({ query: "which orders are ready to pick?" })answers a short list of candidates, best first: each method’s name, its topic, what it does in one line, whether it reads or writes, the permission and plan it needs, and whether the agent may run it here (allowed: falsenames why not). Plain words and whole questions both work (“create batch”, “stocktake”, “How do I buy a label for order #1042?”), and so do typos and a merchant’s own words: “label” finds shipments, “stock” inventory, “RMA” return requests. The search ranks by each method’s name, purpose, inputs and their values, permission and the skills that use it.topics,namespaces,kind("query"for reads,"mutation"for writes) andlimitnarrow the list. - Details:
search({ names: ["picking.queue"] })answers the exact methods asked for, with their inputs and answers as TypeScript, including the fields of each list row. - Who am I here:
search({ context: true })answers the store the agent is connected to, your role, the store’s plan, your permissions and the limits. - Search with code: for questions across many methods, the agent writes JavaScript over the whole list of methods:
search({ code: 'return catalog.methods.filter((m) => m.topic === "fulfillment" && m.irreversible).map((m) => m.name);' })answers every fulfillment change that cannot be undone. The code sees only that list, with each method’s topic, inputs, permission and whether the agent may run it: no store data and no network. Each code search counts as one call. search({ index: true })lists every method by name, under its topic.- Skills: step-by-step recipes for common tasks: find stuck orders, cut a pick batch safely, receive a purchase order, adjust or move stock, count a bin, handle a return, check shipping problems, read the day’s numbers, and more, at least one for every topic.
search({ skills: true })lists them andsearch({ skill: "create-a-pick-batch" })reads one. A search names the skills that use its first methods. Clients that load skills from a server (the MCP skills extension) find the same recipes there.
- Topics: without input it answers how to use it and the API’s topics, the same areas the API explorer groups by: orders, fulfillment (picking and packing), shipping, receiving, inventory, returns, layout (warehouses, bins, zones), catalog, customers (tracking pages, customer e-mails, privacy requests), people, integrations (stores and sync), reports and account.
executeruns the JavaScript the agent writes, in a sandbox with no network. The agent callsapp.<area>.<method>(input)and returns what it found. Several calls fit in one run.docssearches these help pages live:docs({ query: "how does wave picking work" })answers the best passages, each with its page, its section and a link to it. The agent reads them to explain a screen or a setting, or to learn how a workflow goes before it looks for the methods.
Answers stay small and whole. One answer holds up to 24,000 characters by default (execute({ code, maxChars }) raises it). A bigger answer is refused with its shape (its fields, how many rows, capped and cursor), and the agent asks again for fewer fields or rows. Floormode never cuts rows off an answer quietly: a list says capped: true when more rows exist, and its cursor fetches the next page.
Answers as data. Clients on MCP 2026-07-28 also receive each answer as data (structuredContent), in the shape each tool’s output schema describes.
Refusals say how to fix the call. Beside the readable message, a refused call names the method, the field and the rule it broke, the permission or plan it needs, whether trying again can help, and the next step. A call the agent’s client cancels stops before its next step; the steps it already took stay done.
A method’s name is the operation’s name in the API explorer with its first _ turned into a dot: orders_work_queue is app.orders.work_queue, and pick_profiles_list is app.pick.profiles_list.
Three examples
Section titled “Three examples”What the agent writes for three questions, and what the answer looks like. You never write this code yourself.
Which orders are stuck, and why?
Section titled “Which orders are stuck, and why?”const { groups } = await app.dashboard.needs_attention();const short = await app.orders.work_queue({ allocationState: "short", limit: 5 });const missing = await Promise.all( short.rows.map(async (order) => { const { gaps } = await app.orders.allocation_gaps({ shopifyOrderId: order.shopifyOrderId }); return { order: order.name, missing: gaps.map((gap) => `${gap.missingQty} × ${gap.sku ?? gap.title}`), }; }),);return { attention: groups.map(({ kind, reason, count }) => ({ kind, reason, count })), missing,};{ "attention": [ { "kind": "on_hold", "reason": "address_issue", "count": 2 }, { "kind": "short_allocation", "reason": null, "count": 3 } ], "missing": [ { "order": "#1038", "missing": ["2 × MUG-BLUE"] }, { "order": "#1041", "missing": ["1 × TEE-M-BLACK", "1 × TOTE-NAT"] } ]}Where is order #1042?
Section titled “Where is order #1042?”const { hits } = await app.search.global({ query: "#1042" });const order = hits.find((hit) => hit.type === "order" && hit.label === "#1042");if (!order) return "No order #1042.";const { entries } = await app.orders.journey({ shopifyOrderId: order.id });return entries.slice(-4).map(({ atMs, kind, subject, detail }) => ({ at: new Date(atMs).toISOString(), kind, subject, detail,}));The journey lists every step oldest first: reserved, picked, packed, label bought, shipped in Shopify, the carrier’s tracking. The last steps say where the order stands.
[ { "at": "2026-10-21T09:12:40.000Z", "kind": "packed", "subject": "PACK-1", "detail": null }, { "at": "2026-10-21T09:13:05.000Z", "kind": "label_bought", "subject": null, "detail": "1Z999AA10123456784" }, { "at": "2026-10-21T09:13:09.000Z", "kind": "shipped_in_shopify", "subject": "UPS", "detail": null }, { "at": "2026-10-21T16:40:00.000Z", "kind": "tracking", "subject": "in_transit", "detail": "Louisville, KY" }]What’s short?
Section titled “What’s short?”const { rows, totalShortfallUnits } = await app.inventory.backlog_shortfall({ limit: 10 });return { totalShortfallUnits, items: rows.map(({ sku, title, demand, available, shortfall, incoming, suggestedOrderQty }) => ({ sku, title, demand, available, shortfall, incoming, suggestedOrderQty, })),};demand is what open orders owe and available what the bins hold; shortfall is the difference. incoming is already on its way, so suggestedOrderQty is what is left to order.
{ "totalShortfallUnits": 9, "items": [ { "sku": "MUG-BLUE", "title": "Mug, blue", "demand": 12, "available": 6, "shortfall": 6, "incoming": 2, "suggestedOrderQty": 4 }, { "sku": "TOTE-NAT", "title": "Tote bag, natural", "demand": 5, "available": 2, "shortfall": 3, "incoming": 0, "suggestedOrderQty": 3 } ]}Read events
Section titled “Read events”An agent can follow what happens on the floor through an event feed (Settings → Apps & API → Webhooks → Event feeds): it reads new events when it wants, with nothing of yours online. Copy the Feed URL from the feed and give it to the agent.
The loop:
- Read a page: REST
GET /api/v1/events?feed=feed_…(withafteronce it has a cursor), or MCPawait app.events.list({ feed: "feed_…", after }). - Handle the page’s
rows, oldest first. Each row is a Standard Webhooks event body; skip anidit already handled. - Keep the answer’s
cursor. The next read passes it asafter. - Wait
retryAfterMs:0while more is waiting, longer once it is caught up.
let after;for (;;) { const page = await app.events.list({ feed: "feed_…", ...(after ? { after } : {}) }); for (const event of page.rows) handle(event); after = page.cursor; await sleep(page.retryAfterMs);}What to know:
- Its own access. Each read sees only the events the agent’s own role and warehouses may see. The answer’s
readable.withheldnames the events it may not read, and why. - Gaps. A
gapin the answer names a period the feed may have missed: the events were older than Floormode keeps (5 days), or the feed had expired. A read from the past, or a feed that starts at the oldest kept event, reads only what Floormode kept. Events from before any endpoint or feed listened, or from while this feed had expired, were never kept, and a read from the past names no gap for them. To fill a gap, read the details through the API. - The cursor is opaque. Keep it as it came: it is not signed, and changing it only misleads the agent itself. A cursor that is not one, that points past the newest event, or that names a later end than the feed has is refused (
cursor_invalid). - Limits. A page holds at most 100 events and 1 MB. Feed reads have their own limits, 30 a minute per agent and feed and 120 a minute per store, and never use the store’s 60 calls a minute. Cloudflare counts them per location, so treat them as a guard and follow
retryAfterMs. - Life. A feed lives 30 days after its last read, so an agent that reads keeps it alive. A read of an expired feed is refused (
feed_expired): an administrator renews it. - Sequence numbers show how much happened in your store, not what happened.
When something goes wrong
Section titled “When something goes wrong”| The agent says | Means | Do |
|---|---|---|
| It has to sign in again and again | The sign-in did not reach your store’s workspace | Sign in with your P&H account, and choose your store’s workspace if asked |
organization_required |
The sign-in chose no workspace | Connect again and choose your store’s workspace when asked |
agent_read_only |
The app is set to Read only | An administrator sets it to Same as the person in Connected apps, if it should change data |
agent_revoked |
The app was revoked in this workspace | An administrator chooses Allow again in Connected apps, if it should have access |
| The approval screen calls it unverified | The client registered itself when you added the server | Approve it if you added the server yourself just now; see What you approve |
plan_required |
The operation needs a higher plan (the refusal names it) | Choose that plan in Settings → Billing, or leave that step out |
permission_required |
Your role does not include the API | Ask an administrator to add Use the API and AI agents (REST, MCP) to your role |
RATE_LIMITED (answered 429, "scope": "connection") |
The agent sent more than 120 requests this minute | Wait a minute and go on with fewer, larger steps. The refused request did not run |
RATE_LIMITED |
The store’s 60 calls for this minute are used up | Wait a minute, then go on in smaller steps. The refused call did not run. The refusal says how many calls of the same request had finished before it and how many were still running: those may have been done, so check before asking again |
INVALID_INPUT or CONFLICT |
Floormode refused the call and said why | The agent reads the reason and can correct the call |
... is not a function |
The agent guessed a method name | Ask it to look the name up with search({ query: "…" }) |
OUTPUT_TOO_LARGE |
The answer was bigger than the agent’s budget | The agent asks again for fewer fields or rows, or a bigger maxChars |
See also
Section titled “See also”- REST quickstart: the same API for your own code
- REST API: authentication, errors and limits in full
- API explorer: every operation with its inputs
- Standalone access & your team: inviting people and their roles