Merge Unified's Square integration Merge Agent Handler's Square MCP server

Connect your AI Agents to Square in minutes

Merge lets you securely connect your agents to Square and thousands of tools instantly

Start building for free

Read docs

Square

Learn more about Merge Agent Handler

Available tools

create_booking

Create a booking/appointment. Requires startat, locationid, and appointment_segments with service and team member.

list_bookings

List bookings. Filter by location, team member, or date range. Returns paginated list with status.

get_booking

Get a booking by ID. Returns full booking details including service, team member, and customer.

update_booking

Update a booking. Can reschedule, change team member, or update notes. Use version for concurrency.

cancel_booking

Cancel a booking. Booking status changes to CANCELLED. Use booking_version for concurrency.

list_team_member_booking_profiles

List team members available for booking. Filter by location or bookable status. Returns profiles with availability.

search_availability

Search for available booking time slots. Specify date range and service. Returns available times with team members.

list_cards

List cards on file. Filter by customerid or referenceid. Returns cards with last 4 digits, brand, and expiration.

get_card

Get a card by ID. Returns card details including last 4 digits, brand, expiration, and billing address.

create_card

Save a card on file for a customer. Requires sourceid (card nonce from Web Payments SDK) and customerid. Returns saved card.

disable_card

Disable a card on file. The card can no longer be used for payments. This action is irreversible.

list_catalog

List catalog objects (items, categories, taxes, discounts). Filter by object types. Returns paginated list with cursor.

get_catalog_object

Get a catalog object by ID. Include related objects (variations, categories, images) with includerelatedobjects.

upsert_catalog_object

Create or update a catalog object. Object must include type and type-specific data (itemdata, categorydata, etc).

delete_catalog_object

Delete a catalog object by ID. Also deletes related objects (e.g., deleting item deletes its variations).

search_catalog_objects

Search catalog by text (name, description, SKU), exact match, or prefix. Filter by object types and include related objects.

batch_upsert_catalog_objects

Create or update multiple catalog objects in one request. More efficient than individual upserts.

batch_delete_catalog_objects

Delete multiple catalog objects in one request. Also deletes related objects.

create_customer_group

Create a customer group for segmentation. Groups help organize customers for marketing and reporting.

list_customer_groups

List all customer groups. Returns group names and IDs for segmentation.

get_customer_group

Get a customer group by ID. Returns group details including name and creation time.

update_customer_group

Update a customer group's name. Returns the updated group.

delete_customer_group

Delete a customer group. Removes the group but not the customers in it.

add_customer_to_group

Add a customer to a group. Customer will be included in group-based reports and marketing.

remove_customer_from_group

Remove a customer from a group. Customer will no longer be included in group-based activities.

create_customer

Create a new customer profile. Provide name, email, phone, address. Returns customer with unique ID for future payments and orders.

list_customers

List all customers with optional sorting and pagination. Returns customers with their contact info and IDs.

get_customer

Get a customer by ID. Returns full customer profile including contact info, addresses, and group memberships.

update_customer

Update a customer's profile. Provide fields to update (name, email, phone, address, etc). Returns updated customer.

delete_customer

Delete a customer by ID. Removes the customer profile. Use version for optimistic concurrency.

search_customers

Search customers by email, phone, reference_id, or fuzzy name match. Use to find existing customers before creating duplicates.

create_gift_card

Create a gift card. Specify PHYSICAL or DIGITAL type. Card starts with $0 balance until activated.

list_gift_cards

List gift cards. Filter by type, state, or linked customer. Returns cards with balances.

get_gift_card

Get a gift card by ID. Returns card details including balance, state, and linked customers.

get_gift_card_from_gan

Get a gift card by its GAN (gift card account number). Use when customer provides the card number.

link_customer_to_gift_card

Link a customer to a gift card. Customer can view and use the card in their account.

unlink_customer_from_gift_card

Unlink a customer from a gift card. Customer will no longer see the card in their account.

create_gift_card_activity

Create a gift card activity: ACTIVATE, LOAD, REDEEM, DEACTIVATE, or ADJUST balance. Each type has specific required details.

batch_retrieve_inventory_counts

Get inventory counts for catalog items at locations. Filter by item IDs, location IDs, or inventory states.

batch_change_inventory

Change inventory counts. Supports physical counts, adjustments, and transfers between locations. Requires idempotency_key.

retrieve_inventory_changes

Get history of inventory changes. Filter by item, location, change type, or time range.

create_invoice

Create an invoice for an order. Requires locationid, orderid. Invoice starts as DRAFT until published.

list_invoices

List invoices for a location. Returns paginated list with invoice status and amounts.

get_invoice

Get an invoice by ID. Returns full invoice details including payment requests and status.

update_invoice

Update a draft invoice. Can modify payment requests, recipient, title, etc. Requires current version.

delete_invoice

Delete a draft invoice. Cannot delete published invoices - cancel them instead.

publish_invoice

Publish a draft invoice to send to customer. Invoice status changes from DRAFT to UNPAID. Requires version.

cancel_invoice

Cancel a published invoice. Changes status to CANCELED. Cannot be undone. Requires version.

search_invoices

Search invoices by location and optionally by customer. Returns matching invoices with details.

list_locations

List all business locations. Returns location details including address, hours, and capabilities.

get_location

Get a location by ID. Returns full location details including address, hours, and social media links.

create_location

Create a new business location. Requires name. Can include address, hours, and contact info.

update_location

Update a location's details. Can modify name, address, hours, contact info, and social links.

create_loyalty_account

Create a loyalty account for a customer. Link by phone number. Returns account with initial balance.

search_loyalty_accounts

Search loyalty accounts by phone, customer ID, or program. Returns accounts with points balances.

get_loyalty_account

Get a loyalty account by ID. Returns points balance, lifetime points, and expiring points.

accumulate_loyalty_points

Add points to a loyalty account from a purchase. Can link to order_id or add manual points.

adjust_loyalty_points

Manually adjust loyalty points. Positive to add, negative to subtract. Provide reason for audit.

redeem_loyalty_reward

Redeem a loyalty reward on an order. Deducts points from account. Returns reward with discount details.

list_loyalty_programs

List all loyalty programs. Returns program details including reward tiers and accrual rules.

list_merchants

List merchants associated with the access token. Usually returns a single merchant for the account.

get_merchant

Get merchant info by ID. Use 'me' for the current merchant. Returns business name, country, and main location.

create_order

Create an order with line items. Requires locationid and idempotencykey. Can include catalog items or custom items with prices.

search_orders

Search orders by location, customer, state, or date range. Returns matching orders with details.

get_order

Get an order by ID. Returns full order details including line items, totals, fulfillments, and payments.

update_order

Update an order. IMPORTANT: First call get_order to get current version. Add line items, update fulfillment, or change state.

pay_order

Pay for an order using payment IDs. Links payments to the order and completes the transaction.

clone_order

Clone an existing order to create a copy. Useful for repeat orders. Returns new order with same line items.

calculate_order

Calculate order totals without creating an order. Preview taxes, discounts, and final amounts before committing.

create_payment

Create a payment to charge a customer. Requires sourceid (card nonce or card on file), idempotencykey (unique UUID), and amount_money. Returns payment with status and receipt URL.

list_payments

List payments with optional filters. Filter by time range, location, card details, or amount. Returns paginated list with cursor for next page.

get_payment

Get a payment by ID. Returns full payment details including status, amounts, card details, and receipt URL.

cancel_payment

Cancel a payment that has not been completed. Only works for payments in APPROVED or PENDING status.

complete_payment

Complete a delayed payment. Use for payments created with autocomplete=false. Captures the authorized amount.

create_refund

Refund a payment. Requires paymentid, idempotencykey, and amount_money. Can refund full or partial amounts. Returns refund with status.

list_refunds

List refunds with optional filters. Filter by time range, location, status, or source type. Returns paginated list.

get_refund

Get a refund by ID. Returns refund details including status, amount, and associated payment.

create_subscription

Create a subscription for recurring billing. Requires location, planvariationid, and customer_id. Returns subscription with status.

list_subscriptions

List subscriptions. Filter by location or customer. Returns paginated list with status and billing info.

get_subscription

Get a subscription by ID. Returns full subscription details including phases and scheduled actions.

update_subscription

Update a subscription. Can change card, tax percentage, or price override. Use version for concurrency.

cancel_subscription

Cancel a subscription. Schedules cancellation at end of current billing period.

pause_subscription

Pause a subscription. Can set pause duration or resume date. Customer won't be billed during pause.

resume_subscription

Resume a paused subscription. Can specify when to resume. Billing resumes from resume date.

create_team_member

Create a team member. Provide name, email, phone. Assign to locations. Returns team member with ID.

list_team_members

List team members. Filter by location or status. Returns paginated list with contact info.

get_team_member

Get a team member by ID. Returns full profile including locations and status.

update_team_member

Update a team member. Can modify name, contact info, status, and location assignments.

search_team_members

Search team members by location, status, or owner flag. Returns matching members.

validate_credential

Validate Square API credentials by listing merchants. Returns {success, message}.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Square MCP server

What is a Square MCP?

It's an MCP server that gives your agents access to Square's commerce platform via tools. Your agents can invoke these tools to process payments, manage orders and invoices, maintain customer records, update catalog items, and more.

Square offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Square MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Order creation from external channels: When a new order comes in via a website form or third-party booking tool, an agent creates the corresponding Square order, links it to the customer's profile, and sends a confirmation to the fulfillment team in Slack

End-of-day payment reconciliation: At the close of each business day, an agent queries Square for all completed payments, cross-references them against expected invoices in an accounting tool, and flags discrepancies for the finance team to review

Catalog sync on product updates: When a product is updated in a PIM or inventory spreadsheet, an agent calls Square to upsert the catalog object, keeping the POS and online store aligned without any manual data entry

Loyalty milestone enrollment: When a customer completes a qualifying purchase in Square, an agent checks their order history and, if they've hit a repeat-purchase threshold, adds them to a segment in a marketing tool for a loyalty reward campaign

What are popular tools for Square's MCP server?

Here are some of the most commonly used tools:

create_payment: processes a new payment against a card or other payment source, with amount, currency, and optional order reference. Use this when an agent needs to complete a transaction triggered by an external event like a booking confirmation or form submission

list_payments: returns a paginated list of payments filterable by date range, location, or status. Good for workflows that pull a daily or weekly transaction ledger for reconciliation or financial reporting

create_order: creates a new order with line items, quantities, and pricing, scoped to a specific location. Call this when an agent is building an order from data in another system before attaching a payment or routing it to a POS terminal

search_orders: finds orders matching filters like customer ID, date range, location, or fulfillment state. Useful for agents that need to look up a customer's order history or identify orders stuck in a particular status

create_customer: adds a new customer to Square with name, email, phone, and reference ID. Helpful when an agent is syncing contacts from a CRM or form tool into Square ahead of a transaction or loyalty enrollment

upsert_catalog_object: creates or updates a product, variation, or modifier in the Square catalog. Use this when an agent is keeping Square's catalog in sync with a product database or inventory management system

What makes Merge Agent Handler's Square MCP server better than alternative Square MCP servers?

Square ships its own official MCP server, but routing it through Merge Agent Handler adds controls that matter when payment and customer data are involved:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Square, this means you can prevent payment amounts, customer card metadata, order histories, and personally identifiable information from being exposed even when the agent has broad access

Managed authentication and credentials: Merge stores and refreshes Square OAuth tokens and API keys on your behalf. You never embed credentials in agent configuration or manage re-authorization when tokens expire

Real-time observability and audit trail: Every tool call against Square is recorded with timestamp, tool name, inputs, and response status. Finance and compliance teams can see exactly which payments or orders an agent touched without any custom instrumentation

Tool Packs and controlled access: Tool Packs let you bundle specific Square tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Square MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Square connector. Scope the tools to your workflow: read tools like list_payments and search_orders cover reporting and lookup needs, while write tools like create_payment, create_order, and create_customer are needed for agents that process transactions or manage records.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Square by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Square tools are now accessible through that endpoint.