Connect Square to Claude: Sync Inventory, Catalog, and Team Shifts

If you need to connect Square to Claude to automate inventory syncs, manage your product catalog, or adjust team member labor schedules, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's LLM tool calls and Square's REST API architecture. You can spend weeks building, securing, and maintaining this integration yourself, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

If your team uses ChatGPT, check out our guide on connecting Square to ChatGPT or explore our broader architectural overview on connecting Square to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling financial and operational ecosystem like Square is a serious engineering challenge. Square is not just a payment gateway; it is a full enterprise resource planning system for retail and hospitality. You have to handle strict OAuth 2.0 token lifecycles, map massive polymorphic JSON schemas into MCP tool definitions, and deal with Square's aggressive idempotency requirements. Every time Square updates a catalog endpoint or deprecates a labor field, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Square, connect it natively to Claude, and execute complex business workflows using natural language.

The Engineering Reality of the Square API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Square's API is painful. You are not just integrating a simple CRM - you are interacting with complex, ledger-based data structures.

If you decide to build a custom MCP server for Square, you own the entire API lifecycle. Here are the specific, unique challenges you will face with Square's architecture:

Polymorphic Catalog Complexity Square relies heavily on polymorphic data models, specifically within the Catalog API. A single CatalogObject can represent an item, a variation, a category, a tax, or a discount. The payload structure changes drastically depending on the type enum. For an LLM generating JSON payloads from scratch, this is a hallucination trap. The model must know precisely when to nest data inside item_data versus item_variation_data. Truto abstracts this by dynamically generating strict JSON schemas directly from Square's documentation, forcing the LLM to conform to the exact shape required for the specific catalog object type.

Ledger-Based Inventory State Unlike basic SaaS applications where you simply PATCH a quantity field, Square treats inventory as an immutable ledger. You cannot just "update" an inventory count. You must compute the state and create an InventoryAdjustment, InventoryPhysicalCount, or InventoryTransfer. Exposing these raw accounting concepts to Claude requires highly specific prompting. A managed MCP server exposes these operations as distinct, fully-typed tools, ensuring the agent creates the correct ledger entry rather than attempting an invalid direct mutation.

Strict Optimistic Concurrency Square relies on optimistic concurrency to prevent race conditions during updates. Almost all mutative endpoints (updating orders, catalog items, or team members) require passing the exact current version integer in the payload. If the version is stale, Square rejects the request. LLMs frequently attempt to guess this version or increment it arbitrarily. Your MCP server must enforce a read-before-write pattern, forcing the model to execute a get tool to fetch the current version before executing the update tool.

Transparent Rate Limit Handling Square enforces strict rate limits, particularly on search and batch endpoints. A critical architectural note: Truto does not retry, throttle, or apply backoff on rate limit errors. When Square returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (Claude or your custom AI agent) is entirely responsible for implementing the necessary retry and exponential backoff logic.

Instead of building this infrastructure from scratch, you can use Truto. Truto normalizes the authentication lifecycle and pagination, exposing Square's endpoints as ready-to-use MCP tools.

How to Generate a Square MCP Server with Truto

Truto dynamically generates MCP tools from Square's underlying resource definitions and documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring the LLM receives high-quality descriptions and accurate JSON schemas.

You can generate an MCP server for your connected Square account in two ways.

Method 1: Via the Truto UI

For ad-hoc agent testing or manual setup, you can generate the server directly from the dashboard.

1. Navigate to the integrated account page for your Square connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., name, allowed methods like read-only, or specific tags like "catalog").
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3...).

Method 2: Via the REST API

For production workflows, you will want to generate MCP servers programmatically for your end-users. The Truto API validates the integration, generates a secure, hashed token stored in Cloudflare KV, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

const response = await fetch('https://api.truto.one/admin/integrated-account/<square_account_id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Square Operations Agent",
    config: {
      methods: ["read", "write"] // You can restrict this to "read" for safety
    },
    expires_at: "2026-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); 
// Output: https://api.truto.one/mcp/<secure_token>

This URL contains a cryptographic token that encodes the specific Square account and the tool filters. It is fully self-contained.

How to Connect the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional coding. The integration operates purely over Server-Sent Events (SSE) and HTTP POST requests using the JSON-RPC 2.0 protocol.

Method 1: Via the Claude UI (Desktop or Web)

If you are using Claude's graphical interfaces, you can wire up the server in seconds.

1. Copy the MCP server URL generated by Truto.
2. Open Claude and navigate to Settings -> Integrations (or Connectors depending on your tier).
3. Click Add Custom Connector or Add MCP Server.
4. Paste the URL and click Add.

Claude will immediately perform the MCP handshake, request tools/list, and populate the model's context with the available Square operations.

Method 2: Via Manual Configuration File

If you are running Claude Desktop locally for development, or deploying a custom LangChain/LangGraph agent, you can configure the MCP connection manually. Truto provides an open-source SSE transport adapter via npm.

Edit your claude_desktop_config.json file (typically located in ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "square_truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<your_secure_token>"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The application will spawn the SSE listener and instantly expose the Square tools to your chat sessions.

Hero Tools for Square Operations

Truto generates comprehensive tools for Square. Here are six high-leverage "hero tools" that AI agents use to automate complex retail and operational workflows.

1. list_all_square_catalog_objects

This tool retrieves items, variations, categories, and modifiers from the Square seller's catalog.

Contextual usage notes: The LLM uses this tool to audit catalog integrity or search for specific item_variation_ids before executing inventory adjustments. Square uses polymorphic data, so the model must inspect the type field (e.g., ITEM, ITEM_VARIATION) to understand the returned payload.

"Retrieve all catalog objects for our account. Filter the response to only show objects of type ITEM_VARIATION so we can audit the SKUs for the summer apparel launch."

2. square_inventory_batch_create_changes

This tool batch-creates inventory ledger updates, such as physical counts, adjustments (shrinkage/damage), and inter-location transfers.

Contextual usage notes: This is an advanced mutative tool. The LLM must supply a strict array of change objects, ensuring it categorizes changes correctly. It must also generate and provide an idempotency_key (a unique UUID) to prevent accidental double-counting if a network timeout occurs.

"We just finished a stock check at the downtown location. Create a batch inventory change to set the physical count of catalog object ID 'VARIATION_123' to 45 units. Generate a unique idempotency key for this transaction."

3. list_all_square_shifts

Search and retrieve Square labor shifts, optionally filtering by employee, location, or time range.

Contextual usage notes: Labor compliance requires accurate shift tracking. The LLM uses this tool to compile timesheets, audit break durations, or verify coverage. The response includes nested objects for break start and end times, which the model can use to calculate total payable hours.

"Pull all labor shifts for the last 7 days at our primary location. Summarize the total hours worked by John Doe, and highlight any shifts where the expected paid break was skipped."

4. update_a_square_shift_by_id

Updates an existing labor shift. This is typically used by managers adjusting schedules due to sick leave or operational delays.

Contextual usage notes: Due to Square's optimistic concurrency, the agent must first fetch the specific shift to obtain its current version integer. The update payload must include this exact version, alongside the modified start_at or end_at ISO-8601 timestamps.

"John called in sick this morning. Find his scheduled shift for today, grab the current version number, and update the shift to reflect a start time delayed by 4 hours."

5. square_orders_calculate

Calculates totals, taxes, and discounts for a prospective Square order without actually saving or persisting it to the seller's account.

Contextual usage notes: Perfect for quoting and customer service bots. The agent constructs a draft order payload (line items, modifiers, discounts) and submits it. Square's pricing engine returns the exact computed total_money, total_tax_money, and total_discount_money. Square monetary values are always objects containing an amount (in the lowest denomination, like cents) and a currency string.

"Calculate the final price for an order containing two 'Latte' items and one 'Muffin' item at the Main Street location. Apply a 10% discount and tell me the total amount in dollars."

6. square_payments_complete

Completes (captures) an authorized, delayed-capture Square payment.

Contextual usage notes: In workflows where payments are authorized at the time of booking but captured after service completion, the agent uses this tool to finalize the transaction. It requires the original payment_id.

"The delivery for order #8899 was just marked successful. Find the associated authorized payment ID and execute the completion call to capture the funds."

To see the complete inventory of available operations, required parameters, and JSON schemas, view the Square integration page.

Workflows in Action

Connecting Square to Claude transforms the model from a passive query interface into an active operational assistant. Here is how an AI agent strings these tools together to execute multi-step workflows.

Scenario 1: Retail Inventory Reconciliation

Store managers frequently need to adjust inventory based on physical cycle counts. Instead of navigating through multiple Square Dashboard menus, they can instruct Claude.

"Audit our current inventory for 'Espresso Beans'. Find the variation ID, check the current count at the Downtown location, and apply a physical count adjustment to set the new total to 120 units."

Step-by-step execution:

1. square_catalog_objects_search: The agent searches the catalog for items matching "Espresso Beans" and extracts the specific item_variation_id.
2. square_inventory_batch_get_counts: The agent queries the current ledger state for that variation ID at the Downtown location to confirm the baseline.
3. square_inventory_batch_create_changes: The agent constructs a physical_count change object, generates a UUID for the idempotency_key, and executes the ledger update to set the quantity to 120.

The manager receives a natural language confirmation that the physical count has been recorded, along with the previous baseline metric.

Scenario 2: Emergency Labor Schedule Adjustment

When unexpected events happen, managers need to adjust staffing rapidly without violating concurrency rules.

"A water main broke and we are opening 3 hours late today. Find all scheduled shifts for the Main Street location for this morning, and push everyone's start time back by 3 hours."

Step-by-step execution:

1. list_all_square_shifts: The agent retrieves all active shifts for the specified location and date, filtering for morning hours.
2. Read-before-write iteration: For every shift found, the agent reads the exact version integer from the payload.
3. update_a_square_shift_by_id: The agent iterates through the list, recalculating the start_at timestamp (+3 hours) and issuing the update call, ensuring the correct version is passed to satisfy Square's optimistic concurrency checks.

Claude processes the batch update and summarizes the new schedule for the manager.

Security and Access Control

When exposing an enterprise system like Square to an AI agent, security is the top priority. Truto's MCP architecture provides granular access control enforced at the proxy layer, meaning the LLM cannot bypass these restrictions.

• Method Filtering (config.methods): You can restrict an MCP server to specific operation types. For example, setting methods: ["read"] ensures the agent can only execute get and list operations, effectively creating a read-only safety boundary.
• Tag Filtering (config.tags): You can scope the server to specific functional domains. By setting tags: ["catalog", "inventory"], you prevent the agent from accessing sensitive domains like team member wages or payments.
• Secondary Authentication (require_api_token_auth): By default, the cryptographically hashed MCP URL acts as a bearer token. For high-security environments, enabling this flag requires the client to also pass a valid Truto API token in the Authorization header.
• Automated Expiration (expires_at): You can generate short-lived MCP servers for temporary workloads. Once the ISO datetime is reached, Truto's durable objects automatically purge the token from Cloudflare KV, instantly revoking access.

Moving from Prototypes to Production

Building a custom MCP server for Square is a great weekend project, but maintaining it in production is a full-time job. You have to handle OAuth refreshes, monitor catalog schema drift, enforce optimistic concurrency, and build robust error handling for rate limits.

Truto eliminates this architectural debt. By dynamically generating documentation-driven tools and acting as a standardized pass-through proxy, Truto lets your engineering team focus on building intelligent AI agents rather than maintaining API boilerplate.