Square Model Context Protocol Interface (V0.9 Beta)

This implementation adheres strictly to the Model Context Protocol (MCP) specification, enabling sophisticated interactions between autonomous agents and the Square Connect API.

Rapid Deployment Guide

Initialize the Square MCP Interface quickly using Node Package Execute:

bash

Standard initialization

npx square-mcp-connector start

Startup with environment configuration variables set

ACCESS_TOKEN=YOUR_SECRET_TOKEN SANDBOX=true npx square-mcp-connector start

Local invocation

npx /opt/path/to/project/square-mcp-connector

Substitute YOUR_SECRET_TOKEN with a valid credential obtained from the Square API Access Token documentation. Environment variables can alternatively be established prior to command execution.

Hosted MCP Endpoint

Square furnishes a managed remote MCP endpoint, which is the preferred method due to its OAuth integration:

https://mcp.squareup.com/sse

Utilizing the remote service bypasses the need for manual access token management by facilitating direct OAuth login with your Square credentials.

Operational Parameters (Environment Variables)

Variable Name	Function	Example Value
ACCESS_TOKEN	Key for authenticating API requests	sq0atp-...
SANDBOX	Activates the non-production testing environment	true
PRODUCTION	Ensures live environment interaction	true
DISALLOW_WRITES	Enforces read-only operation mode	true
SQUARE_VERSION	Specifies the target Square API schema version	2025-04-16

Agent Integration Protocols

Goose Integration Helper

To integrate the Square MCP Interface with the Goose framework:

Remote Integration Method

Execute the following URL within a system running Goose to install the production remote endpoint:

goose://extension?cmd=npx&arg=mcp-remote&arg=https%3A%2F%2Fmcp.squareup.com%2Fsse&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote

Alternatively, use the command line:

bash

Automated configuration update

npx square-mcp-connector install

Retrieve installation URL only

npx square-mcp-connector get-goose-url

The install command automatically modifies Goose's configuration manifest.

Claude Desktop Configuration

For use with Claude Desktop, consult the main Model Context Protocol Setup Guide. Append the relevant section to your claude_desktop_config.json:

Remote MCP Entry

{ "mcpServers": { "mcp_square_api": { "command": "npx", "args": ["mcp-remote", "https://mcp.squareup.com/sse"] } } }

Local MCP Entry

{ "mcpServers": { "mcp_square_api": { "command": "npx", "args": ["square-mcp-connector", "start"], "env": { "ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN", "SANDBOX": "true" } } } }

Tool Reference Set

The Square MCP Connector exposes a focused toolkit for API interaction:

Utility Name	Function Description	Core Application
get_service_info	Queries for extant service methodologies	System Probing
get_type_info	Retrieves schema definitions for required parameters	Argument Structuring
make_api_request	Dispatches the actual Square API invocation	Operation Execution

Available Service Domain Catalog

This connector grants entry to the entirety of Square's operational API landscape. Refer to the main Square Developer Documentation for granular service specifications:

Domain	Responsibility
applepay	Apple Pay transaction channeling
bankaccounts	Management of financial institution linkages
bookingcustomattributes	User-defined metadata for reservations
bookings	Scheduling and appointment lifecycle control
cards	Storage and retrieval of payment instruments
cashdrawers	Tracking of physical till contents
catalog	Product listings, categories, and pricing definitions
checkout	Payment initiation and finalization procedures
customercustomattributes	Extensible data fields for client profiles
customergroups	Logical aggregation of clientele
customersegments	Automated categorization of the customer base
customers	Comprehensive client record maintenance
devices	Management of connected Square hardware
disputes	Handling transactional chargeback evidence
events	Log of system activity streams
giftcardactivities	Ledger of gift card usage
giftcards	Gift certificate issuance and tracking
inventory	Real-time stock levels and movement records
invoices	Creation and remittance management for billing statements
labor	Staff time and scheduling data interfaces
locationcustomattributes	Metadata tagged to specific business sites
locations	Management of operational physical/virtual sites
loyalty	Loyalty program configuration and point tracking
merchantcustomattributes	Custom data applied at the merchant level
merchants	Merchant account configuration details
oauth	Credential exchange procedures
ordercustomattributes	Extensible data fields for sales orders
orders	Transactional record maintenance
payments	Authorization and capture of funds
payouts	Fund disbursement reporting
refunds	Reversing prior payments
sites	Square Online presence configuration
snippets	Embedded code management for Square Online
subscriptions	Recurring billing lifecycle management
team	Personnel roster and role definition
terminal	Configuration of Square payment hardware
vendors	Supplier relationship data
webhooksubscriptions	Setup for asynchronous event notification channels

Interaction Paradigm

To leverage the Square API via MCP most effectively:

1. Enumerate: Employ get_service_info to map out accessible functions within a domain

get_service_info(service: "catalog")

1. Schema Check: Utilize get_type_info to define input structures

get_type_info(service: "catalog", method: "list")

1. Invoke: Execute the desired endpoint using make_api_request

make_api_request(service: "catalog", method: "list", request: {{}})

Development and Troubleshooting Aids

Utilizing the MCP Inspector

The MCP Inspector tool provides a graphical testing interface:

bash

Compile source assets

npm run build

Launch the inspector environment with the Square connector loaded

npx @modelcontextprotocol/inspector node dist/index.js start

Iterative Development Cycle

1. Obtain source code: git clone [repository_url]
2. Install dependencies: npm install
3. Initiate file watching and recompilation: npm run watch
4. Run the compiled server instance: node dist/index.js start
5. Validate changes via the MCP Inspector interface.

Community Contribution

This software package is automatically generated based on Square's official OpenAPI Specification artifact. While community feedback is valued, substantive modifications must typically be implemented within the code generation pipeline that constructs this interface. Please initiate an issue thread to discuss any proposed pull requests.