Last updated 11 November 2026

agentPickup for developers

agentPickup has three parts: discovery and ordering for agents (a public directory, each business's catalogue, and checkout), the business's own systems (orders land on its point of sale, or its staff page), and verified collection (a signed pickup pass). This page covers how an agent or platform uses them.

MCP server

The quickest way in. Hosted, streamable HTTP:

• https://agentpickup.app/mcp/cards: card and test payments only, paid by the user on the business's own checkout. This is the one in assistant directories.
• https://agentpickup.app/mcp: every tool, including pay_order for agents with a wallet, and group orders.

claude mcp add --transport http agentpickup https://agentpickup.app/mcp/cards

Or run it yourself from npm, @agentpickup/mcp (stdio):

claude mcp add agentpickup -- npx -y @agentpickup/mcp

The tools: find_shops, get_shop, ask_about_shop, create_pickup_order (with pickup_at for a later time), set_dietary_note, pay_order, order_status, get_pickup_pass, cancel_pickup_order, share_agentpickup, and the group order tools start_group_order, join_group_order, group_order_status and close_group_order. In chat apps that draw MCP Apps cards, orders show as a card that becomes the pickup pass. Agents that use skills can install the same steps with npx skills add Tokenise-au/agentpickup-sdk.

Order API

Every business has its own address: https://agentpickup.app/v/{business}, written {shop} below. The step-by-step guide for agents is AGENTS.md.

1. Find a business. GET /directory/v1/shops with q (what the user wants), place, or lat and lng with radius_km; add open_now=true. Each result's url is the business's address.
2. Read the catalogue. GET {shop}/api/catalog: items with ids, prices, options, photos, dietary labels, allergens, soldOut and inStock; the pickup location and hours; the business's local time; how long a paid order waits; and the payments it takes. Prices always come from here.
3. Ask what it doesn't say. POST {shop}/api/question with {"question": "gluten-free options?"}, without names or personal details.
4. Order. POST {shop}/api/orders once the user agrees the items and total. It returns the order, a claim to keep, and next: the checkout link for the user, or the pass for a test order.
5. Follow it. GET {shop}/api/orders/{id} for the status; with the header X-Pickup-Claim, GET {shop}/api/orders/{id}/pass for the pass.
6. Cancel. POST {shop}/api/orders/{id}/cancel with X-Pickup-Claim: unpaid orders close; paid ones are refunded the way they were paid, until the business starts them.

curl -X POST https://agentpickup.app/v/{business}/api/orders \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"usb-c","qty":1,"options":["..."]}],
       "email":"sam@example.com","rail":"square","pickupAt":"17:30"}'

rail is square or card (the business's own Square or Stripe checkout), or test where the business takes test orders. pickupAt takes a clock time in the business's local time ("17:30", "5:30pm") or an ISO time; leave it out for as soon as possible. Where the catalogue says dietaryNotes: true, dietaryNote passes the customer's dietary needs to the business. The routes are in openapi.json.

Agent checkout protocols

The pickup pass

A small signed token any point of sale, ordering platform or payment company can issue and check. It's a compact JWS (EdDSA) that fits in a QR, and it carries no names, items or amounts:

{ "v": 1, "oid": "ord_7HkQ2mXc9aRt", "pid": "Ya7qVHjkKI7bn4gU", "exp": 1793666330 }

The QR holds https://{shop}/c/<token>. Each business publishes its keys at /.well-known/collect-keys.json (JWKS), so a pass checks offline. Single use is the business's to enforce: its server marks the order collected. The format is in SPEC.md, and the library is @agentpickup/core (Apache-2.0):

import { createPublicKey } from "node:crypto";
import { extractToken, verifyPass } from "@agentpickup/core";

const { keys } = await (await fetch("https://agentpickup.app/.well-known/collect-keys.json")).json();
const shopKeys = keys.map((k) => ({ kid: k.kid, publicKey: createPublicKey({ key: k, format: "jwk" }) }));
const result = verifyPass(extractToken(scanned), shopKeys); // { ok: true, claims } or { ok: false, reason }

Directory and listings

The directory lists businesses on agentPickup and businesses on other sites that publish a listing. Already take agent orders elsewhere? Publish /.well-known/agentpickup.json on your site and send it in:

curl -X POST https://agentpickup.app/directory/v1/listings \
  -d '{"url":"https://yourshop.com/.well-known/agentpickup.json"}'

Machine-readable files

Every business serves these under its own address: /api/catalog, /openapi.json, /.well-known/agentpickup.json, /.well-known/ucp, /.well-known/acp.json, /.well-known/collect-keys.json and /.well-known/did.json. The short index for language models is llms.txt.

Open code and partners

Tokenise-au/agentpickup-sdk holds the pickup pass spec and library (Apache-2.0), the MCP server (source-available under FSL) and the agent skill. Building a point of sale, payment or ordering platform? Tell us what you'd plug it into.

Help

Questions about paying, collecting, your information or running a business are answered in the FAQ. Something not right? The support page covers it, or email hello@agentpickup.app.