---
name: iblai-connect-square
description: "Read and write Square data through the Square API (Payments, Orders, Catalog, Customers and others) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Square data, or to set up a Square MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Square connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/square — not part of the iblai/vibe repository. Checked against Square's documentation on October 20, 2026; test it against your own Square setup before you rely on it.

Point-of-sale and payments platform for sellers. A Square account holds payments and refunds, orders, the item catalog, customer profiles, invoices, locations and team data.

## Auth & conventions

- **API:** Square API (Payments, Orders, Catalog, Customers and others) (REST). Versioned REST endpoints under /v2 for payments, refunds, orders, catalog, customers, invoices and locations. Requests carry a Square-Version header; list and search calls use cursor pagination.
- **Base URL:** https://connect.squareup.com/v2 (sandbox: https://connect.squareupsandbox.com/v2)
- **Access:** Public, self-serve. Any developer can create an application in the Square Developer Console and get sandbox and production credentials. A personal access token covers your own account; OAuth is used to act for other sellers.
- **Auth:** Personal access token (bearer); OAuth 2.0 authorization code; OAuth 2.0 authorization code with PKCE. Send Authorization: Bearer {token} and Square-Version. Personal access tokens give full access to your own account. OAuth tokens are scoped by permission (e.g. PAYMENTS_WRITE, ORDERS_READ) and expire after 30 days; refresh tokens renew them.
- **Limits:** Square returns HTTP 429 with RATE_LIMITED when traffic is too high and does not publish fixed numbers or rate-limit headers; endpoints may differ. Retry with exponential backoff and jitter. Paged endpoints take cursor and limit.
- Keep Square credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Orders** — POST /v2/orders/search (ORDERS_READ); up to 1,000 results per page, default 500, cursor pagination.
- **Payments** — Payments API lists and retrieves card and other payments.
- **Catalog** — GET /v2/catalog/list returns items, variations, categories, taxes and modifiers.
- **Customers** — POST /v2/customers/search (CUSTOMERS_READ) searches customer profiles by filters.
- **Locations** — Locations API lists the seller's business locations; most calls take a location ID.

## Writes

- **Take a payment** — POST /v2/payments (PAYMENTS_WRITE) with idempotency_key, source_id and amount_money charges a payment source. **Confirm with the user first.**
- **Refund a payment** — POST /v2/refunds (PAYMENTS_WRITE) refunds all or part of a payment. **Confirm with the user first.**
- **Upsert catalog object** — POST /v2/catalog/object (ITEMS_WRITE) creates or fully replaces an item; omitted fields are cleared.
- **Create customer** — Customers API creates or updates customer profiles.

## Expose it to an ibl.ai agent (MCP)

Square publishes an official MCP server, Square MCP Server (https://developer.squareup.com/docs/mcp). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Square supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "What were total Square sales at each location yesterday?"
- "Find the customer profile for jane@example.com and list her last five orders"
- "Add a new catalog item Oat Latte at $5.50 with a large size at $6.25"
- "Refund $12 of payment ID abc123 for a wrong order"

## Guardrails

- Holds PCI cardholder-related payment records (card brand, last four digits) and customer personal data. Raw card numbers are tokenized by Square and never sent to the API in plain form.
- Request the narrowest Square scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Square access tokens and credentials: https://developer.squareup.com/docs/build-basics/access-tokens
- Square MCP server: https://developer.squareup.com/docs/mcp
- Square OAuth API overview: https://developer.squareup.com/docs/oauth-api/overview
- Square MCP Server: https://developer.squareup.com/docs/mcp
- This connector on ibl.ai: https://ibl.ai/developer/connectors/square
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections