Connect Boulevard to Claude: Handle Orders and Business Reports
Learn how to generate a managed MCP server to connect Boulevard to Claude. Automate booking operations, handle orders, and pull business reports.
If you need to connect Boulevard to Claude to automate salon and medspa scheduling, process checkout orders, or aggregate daily business reports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM function calling and Boulevard's underlying GraphQL APIs. You can either build and maintain this infrastructure yourself, dealing with OAuth lifecycles and Relay pagination, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.
If your team uses ChatGPT, check out our guide on connecting Boulevard to ChatGPT or explore our broader architectural overview on connecting Boulevard to AI Agents.
Giving a Large Language Model (LLM) read and write access to a sprawling business management ecosystem like Boulevard is a heavy engineering lift. Boulevard's API is deeply structured around complex relational graphs - an appointment isn't just a flat record, it's a node linked to clients, staff variants, specific bookable services, and location IDs. Exposing this raw graph to Claude will result in hallucinations unless you build a strict schema enforcement layer.
This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Boulevard, connect it natively to Claude Desktop, and execute complex booking and operational workflows using natural language.
The Engineering Reality of the Boulevard 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, implementing it against specialized B2B APIs is painful. Boulevard is built to manage complex, location-based service businesses. Its API reflects that operational complexity.
If you decide to build a custom Boulevard MCP server in-house, here are the specific integration challenges you will face:
Heavy GraphQL Reliance and Global IDs
Unlike traditional REST APIs with predictable endpoint structures (/v1/appointments/:id), Boulevard heavily leverages GraphQL. This means fetching an appointment or completing a checkout cart requires crafting precise query and mutation payloads. Furthermore, Boulevard uses Relay-style Global Node IDs. An LLM needs strict guidance on how to pass these opaque ID strings between tools without attempting to parse or modify them. You have to map flat MCP tool arguments into complex, nested GraphQL variables.
Multi-Step Booking and Checkout Mutations
Creating a booking in Boulevard is rarely a single API call. It is a multi-step saga. You must execute bookingCreate, followed by bookingAddService, optionally updating durations with bookingServiceSetDurations, assigning staff via bookingServiceSetStaff, and finally finalizing it with bookingComplete. If you hand Claude a generic "update booking" tool, it will fail. You have to expose these atomic mutations as distinct MCP tools with strict, validated JSON schemas so the LLM understands the exact sequence of operations.
Relay Cursor Pagination
When pulling daily reports or listing clients (list_all_boulevard_appointments, list_all_boulevard_clients), Boulevard uses cursor-based pagination (first and after). LLMs are notoriously bad at handling pagination loops natively. Your MCP server must inject virtual limit and next_cursor fields into the tool schemas, explicitly instructing the model to pass the exact cursor string back to the server for the next page of results.
Architecture: Generating a Managed MCP Server
Instead of writing and maintaining a custom GraphQL-to-JSON-RPC translation layer, you can use Truto to dynamically generate an MCP server. Truto introspects the Boulevard integration, reads the underlying resource and mutation definitions, and translates them into a compliant MCP JSON-RPC 2.0 endpoint.
Every connected Boulevard account (a "tenant" or "integrated account") gets a unique, cryptographically hashed token URL. This URL is fully self-contained. It handles the OAuth 2.0 refresh cycles, normalizes the GraphQL payloads, and handles the MCP handshake.
There are two ways to generate this server for your Boulevard integration.
Method 1: Via the Truto UI
For internal tooling or quick Claude Desktop setups, you can generate the server directly from the dashboard.
- Navigate to the Integrated Accounts page in your Truto dashboard.
- Select your connected Boulevard account.
- Click the MCP Servers tab.
- Click Create MCP Server.
- Select your desired configuration (e.g., restrict to
readoperations only, or filter by specific tags likesales). - Copy the generated MCP server URL (e.g.,
https://api.truto.one/mcp/abc123xyz...).
Method 2: Via the Truto API
For production multi-agent architectures, you should generate these servers programmatically. This allows you to spin up heavily scoped, short-lived MCP servers for specific customer sessions.
Send a POST request to the /integrated-account/:id/mcp endpoint:
curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
-H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Boulevard Orders & Reports Agent",
"config": {
"methods": ["read", "write"],
"tags": ["order", "appointment", "client"]
}
}'The API returns a secure URL containing the MCP token:
{
"id": "mcp_srv_98765",
"name": "Boulevard Orders & Reports Agent",
"config": {
"methods": ["read", "write"],
"tags": ["order", "appointment", "client"]
},
"expires_at": null,
"url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}Connecting Boulevard to Claude
Once you have the Truto MCP URL, connecting it to your LLM interface takes less than a minute. The client only needs the URL to discover the tools and route execution requests.
Option A: Via the Claude UI (or ChatGPT)
If you are using the Claude web interface (or ChatGPT with custom GPTs):
- Navigate to Settings -> Integrations (or Connectors in ChatGPT).
- Select Add MCP Server (or Add Custom Connector).
- Paste the Truto MCP URL into the Server URL field.
- Give it a name like "Boulevard Operations".
- Click Add. The LLM will immediately run the
initializeandtools/listprotocol handshake to discover the available Boulevard operations.
Option B: Via Manual Config File (Claude Desktop)
If you are running Claude Desktop locally or configuring an agent framework like Cursor, you connect via the claude_desktop_config.json file. Because Truto provides a remote SSE (Server-Sent Events) endpoint, you use the standard @modelcontextprotocol/server-sse transport.
Open your config file (typically found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the server:
{
"mcpServers": {
"boulevard-ops": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
]
}
}
}Restart Claude Desktop. The Boulevard tools will now appear in your available tool list.
Hero Tools for Boulevard Automation
Truto exposes the entirety of the Boulevard API as tools. However, dumping 150+ GraphQL mutations into Claude's context window is inefficient. Here are the highest-leverage "hero" tools for automating front-desk and back-office operations.
list_all_boulevard_appointments
This tool queries the appointments GraphQL endpoint for a specific location. It supports filtering by staff ID, date ranges, and cancellation status. It automatically handles Relay cursor pagination, instructing the LLM on how to navigate large datasets.
"Pull all the upcoming appointments for the Downtown location for tomorrow. If there are more than 100, page through the results and summarize the busiest staff members."
boulevard_appointments_reschedule
Rescheduling an appointment requires mapping the existing appointment ID to a new bookable time slot ID. This mutation (appointmentReschedule) safely moves the appointment on the calendar and triggers the appropriate client notifications.
"Client John Doe just called. He needs to reschedule his haircut appointment (ID: appt_123) to tomorrow at 2:00 PM. Check the available reschedule times, and if 2:00 PM is open, move the appointment and send him a notification."
create_a_boulevard_arrival
This tool executes the createArrival mutation. It is used to virtually "check-in" a client when they walk into the location, updating their status on the staff's dashboard. It requires the location ID and either the client's email or phone number.
"Sarah Jenkins just walked in. Her email is sarah.j@example.com. Go ahead and mark her as arrived at the Uptown location."
list_all_boulevard_orders
This tool queries the orders connection for a specific location. It is essential for end-of-day financial reconciliation. It returns detailed order payloads including the client ID, closure dates, and associated line items.
"Get all the closed orders from yesterday for location loc_890. Calculate the total revenue generated from product sales versus service sales."
update_a_boulevard_cart_selected_bookable_item_by_id
This tool executes the updateCartSelectedBookableItem mutation. It allows you to modify an active checkout cart by updating staff variants or options on a bookable item before final payment processing.
"Update cart cart_444. Change the selected bookable item to assign it to staff member ID stf_555 instead of the previous assignee, then verify the cart total hasn't changed."
list_all_boulevard_clients
This tool queries the global client directory for the business. It allows the LLM to look up clients by email, phone number, or external ID, returning their primary location and active status.
"Can you look up the client profile for Marcus Vance? Check his profile to see what his primary location is, and see if he has any notes on his file."
For the complete inventory of available Boulevard tools, query parameters, and JSON schemas, visit the Boulevard integration page.
Workflows in Action
Individual tools are useful, but MCP's real power emerges when Claude orchestrates multi-step workflows across the Boulevard graph.
Scenario 1: Front-Desk Triage and Rescheduling
Front desk staff are often overwhelmed by inbound calls. In this scenario, an AI agent handles a client's request to find their upcoming appointment, verify availability, and reschedule it.
"Find the upcoming appointments for client phone number 555-0199. They want to push their appointment back by exactly one hour on the same day. Check if that time is available, and if so, reschedule it and notify them."
Step-by-Step Execution:
list_all_boulevard_clients: The agent searches for the client using the provided phone number to retrieve theclientId.list_all_boulevard_appointments: The agent filters appointments by theclientIdandstartAt> now to find the upcoming appointment and its current time.boulevard_appointments_lookup_reschedule_times: The agent checks the available times for that specificappointmentIdon the target date.boulevard_appointments_reschedule: Seeing the requested slot is open, the agent extracts thebookableTimeIdand executes the reschedule mutation, settingsendNotification: true.
Scenario 2: End-of-Day Operations Audit
Store managers spend hours reconciling appointments against closed orders to identify missed checkouts or discrepancies. An AI agent can pull this data programmatically.
"Run an end-of-day audit for the Main Street location for today. Compare all completed appointments against closed orders. Flag any appointments that don't have a corresponding order ID attached."
Step-by-Step Execution:
list_all_boulevard_appointments: The agent pulls all appointments for the location today, filtering for those with a status indicating the service was completed.list_all_boulevard_orders: The agent fetches all orders closed today at the same location.- Data Analysis: The LLM internally compares the
appointmentIdfields referenced in the order line items against the completed appointments list. - Formatting: The agent outputs a clean, summarized list of appointment IDs and client names that require manual checkout review.
sequenceDiagram
participant Claude as Claude Desktop
participant Truto as Truto MCP Server
participant Boulevard as Boulevard API
Claude->>Truto: Call tool: list_all_boulevard_appointments
Truto->>Boulevard: POST /graphql (appointments query)
Boulevard-->>Truto: Return paginated nodes
Truto-->>Claude: JSON Array of appointments
Claude->>Truto: Call tool: list_all_boulevard_orders
Truto->>Boulevard: POST /graphql (orders query)
Boulevard-->>Truto: Return paginated nodes
Truto-->>Claude: JSON Array of orders
Note over Claude: LLM performs cross-reference logic<br>and generates discrepancy reportSecurity and Access Control
Exposing a POS and booking system to an AI model requires strict governance. Truto MCP servers provide several mechanisms to lock down access:
- Method Filtering: You can restrict a server URL to only allow specific operation types via the
config.methodsparameter. Setting this to["read"]ensures the agent can query clients and appointments but cannot mutate data or close orders. - Tag Filtering: By passing
config.tags, you can restrict the toolset to specific domains. For example,tags: ["appointment"]hides all financial and order-related tools from the LLM context. - Require API Token Auth: By setting
require_api_token_auth: true, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, adding a strict secondary authentication layer. - Time-to-Live (TTL): Passing an
expires_atISO datetime during creation automatically destroys the MCP server and invalidates the token at the specified time - ideal for temporary contractor access or ephemeral CI/CD tasks.
Rate Limits and Resiliency
Boulevard enforces strict API quotas to protect their infrastructure. It is critical to understand that Truto does not automatically retry, throttle, or apply backoff logic when an upstream rate limit is hit.
When Boulevard returns an HTTP 429 Rate Limit Exceeded error, Truto passes that 429 error directly back to the calling client. However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification:
ratelimit-limit: The total allowed requests in the current window.ratelimit-remaining: The number of requests left.ratelimit-reset: The timestamp when the quota refreshes.
Your AI application or framework (e.g., LangChain, LlamaIndex, or custom agents) is entirely responsible for reading these headers and implementing exponential backoff. Do not design your system assuming the integration layer will absorb rate limit faults.
Connect Your Tech Stack Today
Building a custom GraphQL translation layer for Boulevard is an engineering sinkhole. By leveraging Truto's dynamically generated MCP servers, you can give Claude, Cursor, and your custom AI agents immediate, secure access to Boulevard's complex booking and financial graphs. You handle the prompting and business logic; the infrastructure handles the auth, schema mapping, and token lifecycles.
FAQ
- How do I create an MCP server for Boulevard?
- You can create a Boulevard MCP server via the Truto UI by navigating to your integrated account and clicking 'Create MCP Server', or via the Truto API by sending a POST request to `/integrated-account/:id/mcp` with your desired configuration filters.
- Can I restrict Claude to read-only access for Boulevard?
- Yes. When generating the MCP server, you can pass a configuration object with `methods: ["read"]`. This ensures the AI agent can only execute queries (like listing appointments) and cannot execute mutations (like creating orders).
- Does Truto handle Boulevard API rate limits automatically?
- No. Truto passes HTTP 429 errors directly to the caller. However, Truto normalizes the upstream rate limit data into standard headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`), leaving the retry and backoff responsibilities to your LLM framework.
- How does Truto handle Boulevard's GraphQL API structure for LLMs?
- Truto translates Boulevard's GraphQL schema into a flat, REST-like JSON-RPC interface for the MCP server. Complex operations, like Relay cursor pagination, are automatically formatted with `limit` and `next_cursor` arguments so the LLM understands how to interact with the API.