What the agent does
This is for a software company that sells back-office tools to independent coffee shops and small café groups: supplier orders, staff rotas and a weekly numbers email. Owners ask the same question most weeks: are refunds normal, and is anything odd happening at one till? Square holds the answer, but finding it means opening each refund, finding the sale it reversed and checking who rang it up. The company adds a Refund review to the weekly email, written by an agent that reads each café's own Square account.
The company saves the agent once as a template with POST /o/{org}/agents, with "connections": ["square"] (it connects a Square account of its own first, because a template names connections its creator has) and instructions that keep it to reading. When an owner turns Refund review on, the backend calls POST /o/{org}/agents {"template": "<template id>", "name": "refunds-<cafe id>"}, then POST /o/{org}/agents/{agent}/connections {"type": "mcp", "name": "square"}, and opens the authorize_url in a popup for that owner while they are signed in to the app. The owner signs in on Square's own page, so the company registers no Square application. Square's docs say its hosted server reaches production accounts only and is in beta.
The hosted server has three tools: get_service_info to discover a service's methods, get_type_info for a method's parameters, and make_api_request to call it. A run reads the locations service for each location's name and time zone, then the refunds service's list of payment refunds for the week, with begin_time and end_time in RFC 3339, limit at 100 and the cursor from each page. Each refund carries amount_money in the smallest currency unit, status, reason, destination_type (card, cash and others), payment_id, order_id, location_id, created_at and an optional team_member_id. For each refund it reads the original payment through the payments service for the sale's amount and time, and turns team_member_id into a name through the team service.
It writes the week by location: the count and total of refunds against the week before, then the refunds worth a look by the owner's rules, which arrive in input: a cash refund over a set amount, a refund with no reason, a full refund of a sale more than two days old, a refund within minutes of its own sale, and one team member's share of a location's refunds well above the rest. Square documents a refund's team_member_id as the team member associated with taking the payment, so the review labels every name that way. It refunds, cancels and changes nothing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "<agent id>",
"input": "Review my Square refunds for the week 2026-11-09 to 2026-11-15. Use get_service_info and get_type_info as needed, then make_api_request. 1) List locations: id, name, timezone. 2) List payment refunds with begin_time 2026-11-09T00:00:00-05:00 and end_time 2026-11-16T00:00:00-05:00, limit 100, following cursor; also 2026-11-02 to 2026-11-09 for last week's count and total only. 3) For each refund this week, get its payment (amount_money, created_at) and resolve team_member_id to a name with the team service. Flag: destination_type CASH over 2500 cents; no reason; a full refund of a payment more than 48 hours old; a refund within 10 minutes of its payment; a team member with over 40% of a location's refunds and at least 5 of them. Show money in dollars. Label every name as: took the payment. Write refunds-review.md (per location: count and total vs last week, then flagged refunds with time, amount, reason, sale time, name, flag) and refunds.json. Read only: never refund, cancel, create or update anything in Square."
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The session returns refunds-review.md and refunds.json as artifacts. The app's webhook handler reads the JSON into that café's weekly email: a totals line for every location, then each flagged refund with its time, amount, reason, the sale it reversed and the flag it tripped.
What the owner checks: each flagged refund against what they know of that day, such as a spilled order or a regular charged twice, and the name beside it, which is who took the payment rather than who pressed refund. A flag is a reason to ask, not a finding, and the review never says anyone did wrong. Cash handed back without a refund rung up in Square is not in Square, so it is not in the review either.
Run it on every Monday morning, per café
The app's scheduler sends one POST /o/{org}/sessions per café with Refund review on, at 06:00 on Monday in that café's time zone, with the café's agent id as agent, the week and the owner's thresholds in input, and a request_id that is a UUID v5 of the café id and the week, so a retried job starts no second run. Runs past the key's max_concurrent wait as queued and start as slots free, and the key's webhook brings each run.completed to the app.
An owner who sees a strange refund midweek can press Check refunds now in the app, which sends the same request for the week so far to that café's agent.
The use case this job follows, with its automation and trigger: Run an agent per customer task.
Why run it on Rush?
Each café's Square sign-in is that café's own, stored in Rush's connection under that café's agent. The company holds no Square tokens and runs no Square OAuth app, and a run of one café's agent cannot reach another café's account. The session's accounts lists the Square connection it used, so the company can show an owner every run that read their account.
Each run has its own computer, a transcript of every Square call and its model cost, which the company adds up per café with GET /o/{org}/sessions?agent=<agent id> to see what the feature costs it. Because the server describes its own services through get_service_info and get_type_info, a field Square adds is readable on the next run without a code release in the app.
Frequently asked questions
Does the owner need a Square developer account?
No. The owner signs in to Square on Square's own page and the company registers no Square application. Square's docs say it keeps an allowlist of MCP clients for the hosted server and that the server is in beta, so the company tries the feature on its own café account before offering it to customers.
Is the name beside a refund the person who issued it?
Not necessarily. Square documents a refund's team_member_id as the team member associated with taking the payment. The review labels every name that way, and an owner who needs to know who pressed refund checks the till's own record.
Could the agent refund or cancel something?
The Square server writes as well as reads; Square documents a read-only switch for the local server and none for the hosted one. The template's instructions and each prompt forbid every call that is not a read, and the transcript lists every make_api_request the run made with its arguments.
What about an owner with several cafés?
One Square account covers all of an owner's locations, so one agent reads them all and the review is split by location_id. A group that wants one review per location manager can put a single location's id in input, since the refunds list takes location_id.