Square Model Context Protocol Server

Instructions

Implementation Reference

• server.ts:189-237 (handler)

  The core handler function for the make_api_request tool. It destructures params, capitalizes service name, validates service and method using serviceMethodsMap, checks for write permissions, retrieves the specific handler from serviceHandlersMap, calls it with access token and request, and returns the result or error.
  async (params) => { try { const { service, method, request } = params; const serviceName = service.charAt(0).toUpperCase() + service.slice(1); const methods = serviceMethodsMap[serviceName]; if (!methods) { throw new Error(`Invalid service: ${service}. Available services: ${JSON.stringify(Object.keys(serviceMethodsMap), null, 2)}`); } const handlers = serviceHandlersMap[serviceName]; if (!methods[method]) { throw new Error(`Invalid method ${method} for service ${service}. Available methods: ${JSON.stringify(Object.keys(methods), null, 2)}`); } // Support read-only mode if desired const methodInfo = methods[method]; if (process.env.DISALLOW_WRITES == "true" && methodInfo?.isWrite) { throw new Error(`Write operations are not allowed in this environment. Please set DISALLOW_WRITES to false to enable write operations. Attempted operation: ${service}.${method}`); } const handler = handlers[method]; if (!handler) { throw new Error(`No handler found for ${service}.${method}`); } const token = await getAccessToken(); const result = await handler(token, request || {}); return { content: [{ type: "text", text: result as string }] }; } catch (err: any) { return { content: [{ type: "text", text: JSON.stringify({ error: err.message, details: err.errors || err.stack }, null, 2) }], isError: true }; } });
• server.ts:184-188 (schema)

  Zod input schema defining the parameters for make_api_request: service (string), method (string), and optional request object (passthrough).
  { service: z.string().describe("The Square API service category (e.g., 'catalog', 'payments')"), method: z.string().describe("The API method to call (e.g., 'list', 'create')"), request: z.object({}).passthrough().optional().describe("The request object for the API call.") },
• server.ts:180-237 (registration)

  The MCP server.tool() registration call that registers the 'make_api_request' tool with its name, description listing available services, input schema, and handler function.
  server.tool( "make_api_request", `Unified tool for all Square API operations. Be sure to get types before calling. Available services: ${Object.keys(serviceMethodsMap).map(name => name.toLowerCase()).join(", ")}.`, { service: z.string().describe("The Square API service category (e.g., 'catalog', 'payments')"), method: z.string().describe("The API method to call (e.g., 'list', 'create')"), request: z.object({}).passthrough().optional().describe("The request object for the API call.") }, async (params) => { try { const { service, method, request } = params; const serviceName = service.charAt(0).toUpperCase() + service.slice(1); const methods = serviceMethodsMap[serviceName]; if (!methods) { throw new Error(`Invalid service: ${service}. Available services: ${JSON.stringify(Object.keys(serviceMethodsMap), null, 2)}`); } const handlers = serviceHandlersMap[serviceName]; if (!methods[method]) { throw new Error(`Invalid method ${method} for service ${service}. Available methods: ${JSON.stringify(Object.keys(methods), null, 2)}`); } // Support read-only mode if desired const methodInfo = methods[method]; if (process.env.DISALLOW_WRITES == "true" && methodInfo?.isWrite) { throw new Error(`Write operations are not allowed in this environment. Please set DISALLOW_WRITES to false to enable write operations. Attempted operation: ${service}.${method}`); } const handler = handlers[method]; if (!handler) { throw new Error(`No handler found for ${service}.${method}`); } const token = await getAccessToken(); const result = await handler(token, request || {}); return { content: [{ type: "text", text: result as string }] }; } catch (err: any) { return { content: [{ type: "text", text: JSON.stringify({ error: err.message, details: err.errors || err.stack }, null, 2) }], isError: true }; } });
• server.ts:138-177 (helper)

  serviceHandlersMap aggregates all imported service-specific handlers (e.g., CatalogHandlers, PaymentsHandlers) used by the make_api_request handler to dispatch to the correct API implementation.
  export const serviceHandlersMap: ServiceHandlers = { "ApplePay": ApplePayHandlers, "BankAccounts": BankAccountsHandlers, "BookingCustomAttributes": BookingCustomAttributesHandlers, "Bookings": BookingsHandlers, "Cards": CardsHandlers, "CashDrawers": CashDrawersHandlers, "Catalog": CatalogHandlers, "Checkout": CheckoutHandlers, "CustomerCustomAttributes": CustomerCustomAttributesHandlers, "CustomerGroups": CustomerGroupsHandlers, "CustomerSegments": CustomerSegmentsHandlers, "Customers": CustomersHandlers, "Devices": DevicesHandlers, "Disputes": DisputesHandlers, "Events": EventsHandlers, "GiftCardActivities": GiftCardActivitiesHandlers, "GiftCards": GiftCardsHandlers, "Inventory": InventoryHandlers, "Invoices": InvoicesHandlers, "Labor": LaborHandlers, "LocationCustomAttributes": LocationCustomAttributesHandlers, "Locations": LocationsHandlers, "Loyalty": LoyaltyHandlers, "MerchantCustomAttributes": MerchantCustomAttributesHandlers, "Merchants": MerchantsHandlers, "OAuth": OAuthHandlers, "OrderCustomAttributes": OrderCustomAttributesHandlers, "Orders": OrdersHandlers, "Payments": PaymentsHandlers, "Payouts": PayoutsHandlers, "Refunds": RefundsHandlers, "Sites": SitesHandlers, "Snippets": SnippetsHandlers, "Subscriptions": SubscriptionsHandlers, "Team": TeamHandlers, "Terminal": TerminalHandlers, "Vendors": VendorsHandlers, "WebhookSubscriptions": WebhookSubscriptionsHandlers };
• server.ts:97-136 (helper)

  serviceMethodsMap aggregates metadata for all Square API services and methods (descriptions, request types, isWrite flags), used for validation and info in make_api_request.
  export const serviceMethodsMap: ServiceMethods = { "ApplePay": ApplePayMethods, "BankAccounts": BankAccountsMethods, "BookingCustomAttributes": BookingCustomAttributesMethods, "Bookings": BookingsMethods, "Cards": CardsMethods, "CashDrawers": CashDrawersMethods, "Catalog": CatalogMethods, "Checkout": CheckoutMethods, "CustomerCustomAttributes": CustomerCustomAttributesMethods, "CustomerGroups": CustomerGroupsMethods, "CustomerSegments": CustomerSegmentsMethods, "Customers": CustomersMethods, "Devices": DevicesMethods, "Disputes": DisputesMethods, "Events": EventsMethods, "GiftCardActivities": GiftCardActivitiesMethods, "GiftCards": GiftCardsMethods, "Inventory": InventoryMethods, "Invoices": InvoicesMethods, "Labor": LaborMethods, "LocationCustomAttributes": LocationCustomAttributesMethods, "Locations": LocationsMethods, "Loyalty": LoyaltyMethods, "MerchantCustomAttributes": MerchantCustomAttributesMethods, "Merchants": MerchantsMethods, "OAuth": OAuthMethods, "OrderCustomAttributes": OrderCustomAttributesMethods, "Orders": OrdersMethods, "Payments": PaymentsMethods, "Payouts": PayoutsMethods, "Refunds": RefundsMethods, "Sites": SitesMethods, "Snippets": SnippetsMethods, "Subscriptions": SubscriptionsMethods, "Team": TeamMethods, "Terminal": TerminalMethods, "Vendors": VendorsMethods, "WebhookSubscriptions": WebhookSubscriptionsMethods };