AI agents (MCP)

Point Claude — or any MCP client, or your own sales agent — at your workspace and ask it who to call today. Stitchwork speaks the Model Context Protocol, so the tools below appear automatically, with no integration to build.

What your agent can do

Access is read-only with three exceptions, and all of them only add. An agent can find prospects, look up customers and orders, read the diary, and read your sales figures and nudge results. The three things it can write are a customer note, a follow-up — a customer put on somebody's list, with the reason, the day it is owed by, and optionally a draft of the message worth sending — and a nudge proposal: a draft for your storefront that cannot appear anywhere until a person turns it on. All three are appended, signed with the seat that wrote them, and none can be edited or removed by the agent afterwards. Nothing it does changes, deletes, sends or activates anything: not a price, a quote, an order, or a person's details. And it sees only what the person or agent holding the token could already see in Stitchwork — an associate who staffs one store gets one store's data.

The headline use is finding leads. In Stitchwork a lead is not a stranger from a web form: it is your own warm prospect — somebody who abandoned a basket, showed buying intent and never bought, or bought before and has gone quiet.

What the AI can and cannot see

The point of connecting through Stitchwork rather than exporting a CSV is that the data protection is enforced server-side, not promised. Concretely:

• Minimum answers, never the export. Every row an agent is shown passes an explicit allowlist. Hashed IPs, user agents and raw attribute blobs never leave — a column added next year is invisible to agents until somebody deliberately exposes it. Customer notes are deliberately exposed: they are what your team knows about a person, and a brief written without them is a brief written blind.
• Named access only. There is no workspace-wide AI key. Every connection is a seat: a specific person, or a named agent.
• Scoped like the app. A seat sees what its holder already sees — an associate's AI gets their store's data, not the estate's.
• Add-only where it writes at all. Three tools write — add_customer_note, create_follow_up and propose_nudge — and all of them can only add. Everything else in the registry reads. No tool can change or delete anything, so the worst a wrong call leaves behind is an extra note on a timeline, one more item on a work list, or a draft in your review queue — each signed with whoever's seat wrote it. Your team can correct and remove all of them from the app; an AI connection cannot, and that is deliberate. An agent cannot close a follow-up either — what happened on a call is a fact only the person who made it holds — and it cannot activate, edit, pause or delete a nudge, its own proposals included.
• Nothing an agent writes reaches a customer. A note and a follow-up land in front of a colleague, who decides what to do about them; a follow-up's draft message reaches a customer only if that colleague sends it — from the customer's record in Stitchwork, or from their own tools. A nudge an agent proposes is a draft the serving path can never render — it appears on your site only after a person reviews it and turns it on. No tool sends an email or a text, and no tool can put text on your storefront: the agent drafts, a person decides what a shopper ever reads.
• Grant-first. Connecting cannot create access or add a seat to your bill. An admin grants; consent without a grant ends at "ask your admin".
• Off means off. Tokens are checked on every request, so revoking a seat or disconnecting an app takes effect immediately — nothing waits for an expiry.

Your data stays in Stitchwork. The AI comes to it and takes away only the shaped answer to the question it asked. What an AI vendor does with a conversation is governed by your agreement with them — choose your client accordingly.

Connecting Claude

This is the normal way in, and there is no credential to copy.

1. An owner or admin grants the person MCP access in Settings → MCP. This is what uses a seat, and it has to happen first — Claude cannot grant itself access, and nobody can add to your bill by connecting.
2. In Claude, add a custom connector and paste the endpoint: https://app.stitchwork.io/mcp
3. Claude sends them to Stitchwork to sign in and confirm. Approve, and the connection is live.

Behind that, Claude discovers our authorization server, registers itself and runs an OAuth 2.1 flow with PKCE. There is nothing to configure: no client ID, no secret, no token to paste. If someone without a seat tries, they are told to ask an admin.

Access tokens last an hour and refresh silently. Disconnecting the app in Settings → MCP cuts it off immediately — it does not wait for anything to expire.

Connecting an agent or script

For something headless — a nightly sweep, your own sales bot — OAuth is the wrong shape, because there is no person to sign in. Create an agent in Settings → MCP instead and copy its token. It is shown once and never again.

Endpoint:  https://app.stitchwork.io/mcp
Header:    Authorization: Bearer mcp_live_••••
Protocol:  2024-10-07 … 2026-07-28 (negotiated)

Negotiation follows the spec: on initialize the requested revision is read from params.protocolVersion in the body — the MCP-Protocol-Version header only exists on later requests, where it carries the already-negotiated version and wins if sent. Stitchwork answers in your revision when it speaks it, and in its newest when it does not. Both the classic initialize handshake and 2026-07-28's server/discover work.

The transport is stateless: one HTTP POST carrying JSON-RPC 2.0, no session to establish and no stream to hold open. A quick check that your token works:

curl -X POST https://app.stitchwork.io/mcp \
  -H "Authorization: Bearer mcp_live_••••" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Mcp-Method header (and Mcp-Name on a tools/call) arrived in 2026-07-28 and lets gateways route without reading the body. Send them or leave them out, but if you send one it must match the body — a header that disagrees is rejected rather than guessed at.

The playbooks

The tools below say what each piece of data means. The playbooks say what to do with them, in order — because an agent asked to "check follow-ups" will read the outstanding list back and stop, which is a fair reading of a request that named one thing. A playbook names the whole round instead.

In Claude Code they appear as slash commands: type / and they are listed alongside everything else. Arguments follow the command.

/mcp__stitchwork__morning_run
/mcp__stitchwork__lapsed_sweep 365
/mcp__stitchwork__appointment_prep tomorrow

Playbooks are user-invoked, so they do not fire when somebody types a request in plain English. For that path, the tools carry the same sequence themselves: a result from list_follow_ups or any find_* tool includes a next_steps field naming what to do next and what the result is not. Both read from one source, so they cannot describe two different processes.

Other clients surface prompts differently, or not at all — the next_steps path works everywhere regardless. Discover them over the wire with prompts/list, and fetch one with prompts/get.

The tools

Finding leads

• list_pending_callbacks — shoppers who typed their number into a nudge and asked to be rung, while still anonymous. The warmest list in the catalogue — they asked, in as many words — and the only one that is not already a follow-up, because there is no customer record to attach one to until somebody rings and takes their email. Worth reading first: these go cold faster than anything else here. Read-only, and phone numbers are not returned — claiming one needs an address that only exists once a person has made the call, and a stranger's mobile is not something to copy into a transcript. What comes back is enough to brief and prioritise: how long they have waited, what they were last looking at, and which message they answered. Whoever is making calls works them on the Leads page.
• find_abandoned_orders — baskets, unpaid invoices and drafts that never completed. The warmest list there is: the customer already chose the items. Returns one entry per opportunity, not per order: somebody whose card declined five times against one basket is a single entry worth a single basket, with attempts: 5 and the other order ids listed. Baskets the customer went back and bought are excluded — that money has already been taken. See Repeat checkout attempts. Two exclusions: baskets the customer went back and bought (see Repeat checkout attempts), and ones where they have since spent at least what the basket was worth. An entry that survives but carries bought_since means they HAVE bought since — just not enough to account for this basket — which is the difference between opening a call with "you didn't finish your order" and opening it with what they actually bought.
• find_high_intent_customers — customers who viewed, searched, carted or were quoted, and did not buy in the same window — so a repeat customer who bought last year and is circling something new is on this list, where they belong. Each comes back with an intent score, a stage and a plain-English reason they are on the list.
• find_lapsed_customers — past buyers who have gone quiet for longer than customers here normally do. This is the far end of find_repeat_candidates rather than a separate list: the same axis, time since their last order, cut further out — so everybody here is already on that list with a lapsed flag on the row. Reach for it when you want only the far end, or for active_since_days, which narrows it to lapsed buyers who have started browsing again and is the sharpest cut in the product. max_orders: 1 isolates one-time buyers who never came back — a different and usually larger problem than a regular going quiet.
• find_outstanding_balances — customers who paid a deposit and still owe the balance, with what each owes and how long since their deposit landed. The one entry here that is not a prediction: these people have already bought, and this is money owed on sales you have made. It does not say a balance is late — Stitchwork holds no payment terms or delivery dates, so days_waiting is time since the deposit and nothing more. Never let an agent present it to a customer as overdue.
• find_repeat_candidates — customers at the point their next order normally comes, measured against this workspace's own rhythm rather than a fixed number of days. max_orders: 1 gives the second-sale list: people who have bought exactly once, which no window over the order table can express and which is the segment retention is won or lost in. Every row carries how far past due they are, whether they have crossed into lapsed, and when they were last on the site. Order it by due, value or recent — each is a column on the row, never a blended score.
• find_open_quotes — quotes sent and not converted, oldest first. A quote is left out when the customer has since spent at least what it was for: plenty of sales land through a till or an import without the quote ever being marked converted, and the quote is not really open in that case.
• find_customers_for_product — who should hear about one product: a new arrival, something back in stock, the last one on the floor. The other direction from the brief's suggestions. Customers who quoted it, put it in a basket or looked at it come first — weighted as the brief weighs them, a quote above a basket above a look — then customers who keep browsing its category; never anyone who has already bought it. Each row says why in words ("Put it in a basket twice; looked at it 3 times", "Keeps looking at Sideboards (6 views)"), who looks after the customer, and whether they engaged with this product or only its category. Takes a product_id or a sku. Read-only: telling them is a person's job, which an agent can propose with create_follow_up. The same list is the Who to tell tab on a product.

Retention

• get_retention_rhythm — how repeat business actually works in this workspace: what share of customers ever order again, how long they take between orders, and the three windows every retention list is built on. Read it before calling anybody "due" or "lapsed", because those words mean this workspace's measured numbers rather than a general rule, and quote source — it says whether they were measured from real orders or are still the shipped defaults. Read-only: the windows shape every retention list in the product, so changing them is a person's decision in Settings → Retention, not an agent's.

Briefing a salesperson

• get_customer_brief — the pre-meeting brief, from one call: identity, lifetime value, buying intent with the reason, the products they are circling, recent searches, open quotes, abandoned baskets, what they already own (with the actual items), appointments, and suggested products to show them. Takes a customer_id, an exact email, or a name — an ambiguous name comes back as candidates rather than a guess. It carries the team's most recent notes on the person too, with a count of any older ones it left behind, and the client profile: who looks after them, their tags, what the team knows about them (a ring size, a preferred finish) and the dates that matter, each with how many days away it is — so a draft can mention the anniversary next week, and never get the ring size wrong.
• list_appointments — the diary: who is booked in, when, at which store and to see whom, with the customer's own words about why they are coming. Defaults to what is still to happen, soonest first; when: "past" reads what already happened, no-shows included. The natural opening move before get_customer_brief — an agent that reads the diary at eight can have every visit of the day briefed before anyone takes their coat off. Read-only: booking, moving and cancelling appointments are commitments to a customer, and they stay with people.

Putting somebody on the list

The list itself, how work is routed and how a sale is credited are covered in Follow-ups & sales credit.

• create_follow_up — the tool that turns a lead into work. The find_* tools say who is worth contacting; this is what makes one of them appear on a colleague's list tomorrow morning, with the reason attached. Takes a customer, a reason in plain prose, and a day — either due_in_days or an exact due_on.
  Only one follow-up can be open per customer at a time, enforced in the database. A second attempt returns the one already standing with created: false rather than raising a duplicate — so a nightly sweep can run every night without burying your team in copies of its own suggestions.
  Where it lands depends on the seat. A person's seat puts it on their list, because somebody working through their own AI client saying "chase this on Friday" is making a commitment of their own. A bot's seat routes it from the customer's own records — to the associate who raised their open quote, or who saw them at their last appointment, at the store it happened at — and leaves it unassigned when there is no such record.
  The model is never asked who should call. It cannot name anybody, and there is no argument for doing so: choosing would mean handing it your staff list. What it gets is the name already on the record, which is a fact your workspace holds rather than a rota an AI invented — and every routed follow-up carries the sentence explaining it (routed_because: "Priya Shah raised quote Q-1042, still open"), so nobody has to take the decision on trust. Whoever it lands on can hand it back in one click.
  People move, so the name is checked against today rather than the record: somebody who has left, or moved to another store, does not inherit their old customers. Then the work keeps the store and loses the owner, which is the safe direction — somebody there can claim it.
  An agent cannot close, reassign or re-date a follow-up. It proposes work; a person does it and records what came of it.
  Pass worth and worth_currency when the figure came from find_abandoned_orders or find_open_quotes. That is what lets Stitchwork retire the follow-up by itself if the customer buys that much before anybody calls — measured against what they walked away from, rather than against any purchase at all.
  Optionally pass proposed_message — a draft of the words worth sending, written while the evidence is in front of the agent. It renders on the follow-up card and goes no further on its own: the colleague edits it and sends it from the customer's record (by email, text or WhatsApp) or from their own email or phone — or drops it. Nothing is sent unless a person presses Send; the agent sends nothing.
• list_follow_ups — what the team already owes people, overdue first. Worth asking before proposing anything: a customer somebody has already committed to calling on Tuesday is not a lead. mine narrows it to this connection's own list, unassigned to work nobody has picked up — which is where an agent's own suggestions sit. Ask for status: "done" to read back the outcomes people recorded, which is the most useful thing there is before contacting somebody again.
  status: "settled" is the work that retired itself — the customer bought before anybody contacted them, so Stitchwork closed it. An agent running each morning does not have to re-check whether yesterday's suggestions are still worth calling: that already happened as the orders landed, and the open list is current when it reads it. Reading the settled ones is how it reports what was overtaken by events.
• get_follow_up_review — the manager's week, from the same query the app serves: raised, done, dismissed, settled, still open, still overdue, and a by_source split saying how much of the raising was the agent's own. The number a sweep should read before proposing more — "of the nine I suggested last week, four were called and two bought before anyone rang" is the sentence that earns it the next week.

The storefront's messages

Nudges are covered in their own page; these two tools are the agent's seat at that table — one reads the verdicts, one drafts for the review queue, and neither can touch what a shopper sees.

• get_nudge_report — every nudge with its status, who it targets (as the same described sentence the settings card shows) and its verdict against the holdout: better, worse, inconclusive, no_difference, counting or unmeasured. Pass nudge_id for one nudge's full report — responses, callbacks awaiting a name, and revenue that followed a match, per currency. The verdicts come from the same arithmetic the app shows and must be quoted as given: a conversion rate on the treated arm alone measures the targeting, not the message, which is precisely the number the holdout exists to refuse.
• propose_nudge — the third of the three tools that write, and the most fenced. It drafts a nudge — message, targeting rule, call to action — that lands in your review queue as a draft, named as the agent's. A draft cannot render: the serving path reads live nudges and nothing else, so these words appear on your site only after a person opens Settings → Nudges, reads the proposal, and turns it on — an act that is audited and offered by no tool. The agent cannot activate, edit, pause or delete anything, its own proposals included; rejecting one is a person's act too. The queue holds at most five unreviewed proposals — past that the tool refuses and names what is waiting, so the pressure lands on reviewing rather than on drafting more. Why allow it at all: the holdout. A nudge is the one surface where an AI's copy gets measured against a control group instead of believed — agent proposes, person approves, holdout referees.

Recording what was said

• add_customer_note — the second of the three tools that write. After a call or a visit, your agent can record what the customer asked for or what was promised, so the next person to speak to them knows it. The note is signed and stamped: a seat held by a person is recorded as that person, exactly as if they had typed it on the customer page; a seat held by a bot is recorded under the bot's own name and marked as AI-written wherever it appears. Nothing is ever attributed to somebody who did not write it. An agent cannot edit or delete a note, its own included — correcting or removing one is a colleague's job, done from the customer page, and the audit log records who did it.

Looking things up

• search_customers, get_customer
• get_customer_timeline — everything one person has done, so your agent can refer to what actually happened instead of guessing.
• get_customer_notes — the full history of what your team has written about someone, each note with its author and date. The one source here that is a colleague's own sentence rather than a figure derived from behaviour.
• get_customer_emails — what your team has already sent that customer from Stitchwork, newest first, with the subject, what it actually said, who sent it and when. Notes are what your team wrote about somebody; this is what they were told. Have your agent read it before drafting any outreach: the commonest way clienteling goes wrong is three people saying the same thing to the same customer in a week, and a subject line will not tell you whether you are about to repeat a price or contradict a promise. Reading only — nothing in this catalogue can send an email.
• get_customer_texts — the SMS and WhatsApp conversation with that customer, both ways, newest first. It is the one place the customer's own replies are recorded, and when the most recent message is from the customer it says so (awaiting_reply), because an unanswered question comes before anything else. Reading only. See Messaging.
• search_orders, get_order — get_order includes the line items, each resolved back to the product and variant its SKU means.
• search_products — every result carries its type, price, variant count and lifetime sales; sort by bestselling to rank the catalogue.
• get_product — one product by id or by SKU, with its variants, options, per-variant sales and what a unit actually sells for. The tool that turns an order line's GTR-DR-MAH-LH into "the mahogany left-handed Dreadnought", with the parent product and its siblings attached.
• list_channels

What's selling

• get_sales_summary — revenue, orders and average order value for a period, with the previous period alongside.
• get_top_products — the bestsellers over a recent window, by revenue, units or number of sales, filterable to one store, category or brand.
• get_frequently_bought_together — co-purchase from real orders. Anchor it on a product for companions with an attach rate ("42% of Dreadnought orders include a hard case"), or run it open for the workspace's strongest pairs.

Money and currencies

Every money figure comes back per currency, in a list, never as one combined total. Stitchwork holds no exchange rates, so a customer who spent £3,400 and $4,000 is worth two figures and not "£7,400" — any single number would be invented. The tool descriptions say so, and so does the server's own instructions block, because a model asked "how much is this customer worth" will otherwise add them.

Result sizes

Every list tool takes limit (default 20, maximum 100) and offset, and returns a next_offset when there is more. Results are deliberately lean — list rows carry who to contact and what it is worth, and the matching get_* tool fills in the detail. That is a token budget, not a restriction: a page of twenty leads with everything attached would spend your agent's working memory on the eighteen people it never mentions.

Calls are rate limited per seat. A normal conversation will never reach it; an agent stuck in a loop will, and gets a 429 with a Retry-After.

Errors

Two kinds, and the difference matters to your agent. A problem with the request — a bad token, a locked workspace, a malformed body — is an HTTP error your client handles. A problem with the answer — no such customer, an empty date range — comes back as a normal 200 with isError set, so the model can read it and try something else.

Seats and billing

Each person or agent you grant access to is one MCP seat, charged on top of your normal terms. Seats are counted from the grant list and never from usage — running a lot of queries does not change your bill, and neither does running none. Revoke a seat and the charge stops; revoking also kills every token under it immediately.

A token can be rotated with no downtime: create a second one, deploy it, then revoke the first. Extra tokens on the same seat are not extra seats. Removing somebody from your team revokes their MCP seat automatically.

MCP access is not yet available on AWS Marketplace subscriptions — the listing has no MCP seat dimension. Get in touch and we will arrange it.

Keeping access safe

• Only approve a connection you started yourself. The consent screen names the application asking — if you do not recognise it, cancel.
• Disconnecting an app in Settings → MCP revokes its access on the spot.
• A token is a workspace credential. Anyone holding it can read your customers.
• It is shown once, at creation. Stitchwork stores only a hash and cannot recover it.
• Settings → MCP shows when each token was last used, so an unused one is easy to spot.
• Revoke anything you are unsure about and mint a replacement — it takes seconds.