📅 Book a 30-min Demo📞 Call/text (571) 293-0242
Connector · Point-of-sale and payments platform

Square MCP Server & Agent Skill

Last updated

ibl.ai publishes a free Square agent skill: a SKILL.md that teaches an AI agent to read and write Square data and expose it as an MCP tool. Download it, connect your own Square credentials, and run the agent on ibl.ai Agentic OS, where you own all the code and the data.

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.

What is the Square API, and what can an agent read from it?

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.

  • API: Square API (Payments, Orders, Catalog, Customers and others) (REST)
  • Access: Public, self-serve
  • Base URL: https://connect.squareup.com/v2 (sandbox: https://connect.squareupsandbox.com/v2)
  • Authentication: Personal access token (bearer); OAuth 2.0 authorization code; OAuth 2.0 authorization code with PKCE

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.

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.

What can an agent read from Square?

  • 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.

What can an agent write to Square?

  • 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.

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.

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.

How do I connect Square to an AI agent over MCP?

Square publishes an official MCP server: Square MCP Server.

Hosted at https://mcp.squareup.com/mcp with OAuth (production only). Local option: npx square-mcp-server start with an access token; SANDBOX and DISALLOW_WRITES flags. Beta.

You can register that server on ibl.ai as it is, or use the SKILL.md below when you want the agent to call the Square API (Payments, Orders, Catalog, Customers and others) directly.

On ibl.ai an MCP connection is three records, and a working integration always needs all three:

  1. Register the server — POST …/mcp-servers/ with its URL, a transport (sse, websocket or streamable_http) and an auth_type of none, token or oauth2.
  2. Create a connection that holds the credential, scoped to the whole organization (platform), to a single agent, or to each user (user).
  3. Enable it on the agent — mcp-tool in tool_slugs and the server id in mcp_servers. Both lists are replaced, not merged, so read the settings first.

Square supports per-user OAuth, so the server can use auth_type=oauth2 with auth_scope=user: each person connects their own Square account in the chat the first time the agent needs it.

The field reference is in MCP server connections, and the /iblai-api-agent-mcp skill runs all three steps from a coding agent.

What does the Square agent skill do?

The Square skill is one SKILL.md file named iblai-connect-square. It gives an agent the auth conventions, what to read, which writes need a person's confirmation, the ibl.ai MCP wiring, example prompts and guardrails.

Download the Square SKILL.md

Save it as .claude/skills/iblai-connect-square/SKILL.md, or in your agent's skills folder. The ibl.ai platform skills it calls come from one install:

$ npx skills add iblai/vibe --all

This connector skill is a starting point maintained on ibl.ai, not part of the iblai/vibe repository.

It was checked against Square's documentation on October 20, 2026. Test it against your own Square setup before you rely on it.

What can I ask a Square agent to do?

  • “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”

How do I run a Square agent on ibl.ai?

Agentic OS is where the agent runs on ibl.ai: it holds the Square MCP connection, the model the agent uses, its instructions and its conversation history.

On ibl.ai you own all the code and the data, run it model-agnostic across any LLM, and pay with no per-seat pricing — so you can deploy anywhere, from your own cloud to a fully air-gapped network.

Which ibl.ai agents work with Square data?

Which ibl.ai platform skills does a Square agent use?

What else should I know before connecting Square to an AI agent?

Is there an official Square MCP server?

Yes. Square publishes Square MCP Server.

You can register it on ibl.ai as an MCP server, or use the SKILL.md when you want the agent to call the Square API (Payments, Orders, Catalog, Customers and others) directly.

Who can get Square API credentials?

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.

Does Square data leave my infrastructure when an ibl.ai agent uses it?

On ibl.ai, you own all the code and the data. Self-hosted in your cloud or data center, the agent, its MCP connections and its conversation logs stay inside your perimeter.

Because the platform is model-agnostic, you can point the agent at a model you host, so Square records need not reach a third-party model provider.

Is the Square agent skill free to use?

Yes. The SKILL.md is a free download with no sign-up. It assumes you already have Square credentials, and your agreement with Square still governs how you use its API.

Which other data sources can an AI agent connect to alongside Square?

Which other Small Business systems have a connector?

Every connector, grouped by sector, is on the connectors hub.