---
title: "Connect Boulevard to Claude: Handle Orders and Business Reports"
slug: connect-boulevard-to-claude-handle-orders-and-business-reports
date: 2026-11-16
author: Roopendra Talekar
categories: ["AI & Agents"]
excerpt: "Learn how to generate a managed MCP server to connect Boulevard to Claude. Automate booking operations, handle orders, and pull business reports."
tldr: "Connect Boulevard to Claude using Truto's managed MCP servers to automate complex booking workflows, reconcile end-of-day orders, and handle GraphQL schemas without custom code."
canonical: https://truto.one/blog/connect-boulevard-to-claude-handle-orders-and-business-reports/
---

# Connect Boulevard to Claude: Handle Orders and 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](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/). 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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) to dynamically generate a secure, authenticated MCP server URL. 

If your team uses ChatGPT, check out our guide on [connecting Boulevard to ChatGPT](https://truto.one/connect-boulevard-to-chatgpt-manage-bookings-and-client-data/) or explore our broader architectural overview on [connecting Boulevard to AI Agents](https://truto.one/connect-boulevard-to-ai-agents-sync-staff-and-schedule-workflows/).

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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/), connect it natively to Claude Desktop, and execute complex booking and operational workflows using natural language.

> Want to give your AI agents secure, authenticated access to Boulevard and 100+ other SaaS APIs? Let's talk about [managed MCP architecture](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/).
>
> [Talk to us](https://truto.one/book-a-demo/)

## 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](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), 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.

1. Navigate to the **Integrated Accounts** page in your Truto dashboard.
2. Select your connected Boulevard account.
3. Click the **MCP Servers** tab.
4. Click **Create MCP Server**.
5. Select your desired configuration (e.g., restrict to `read` operations only, or filter by specific tags like `sales`).
6. 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:

```bash
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:

```json
{
  "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):

1. Navigate to **Settings** -> **Integrations** (or **Connectors** in ChatGPT).
2. Select **Add MCP Server** (or Add Custom Connector).
3. Paste the Truto MCP URL into the Server URL field.
4. Give it a name like "Boulevard Operations".
5. Click **Add**. The LLM will immediately run the `initialize` and `tools/list` protocol 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:

```json
{
  "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](https://truto.one/integrations/detail/boulevard).

## 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:**
1. **`list_all_boulevard_clients`**: The agent searches for the client using the provided phone number to retrieve the `clientId`.
2. **`list_all_boulevard_appointments`**: The agent filters appointments by the `clientId` and `startAt` > now to find the upcoming appointment and its current time.
3. **`boulevard_appointments_lookup_reschedule_times`**: The agent checks the available times for that specific `appointmentId` on the target date.
4. **`boulevard_appointments_reschedule`**: Seeing the requested slot is open, the agent extracts the `bookableTimeId` and executes the reschedule mutation, setting `sendNotification: 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:**
1. **`list_all_boulevard_appointments`**: The agent pulls all appointments for the location today, filtering for those with a status indicating the service was completed.
2. **`list_all_boulevard_orders`**: The agent fetches all orders closed today at the same location.
3. **Data Analysis**: The LLM internally compares the `appointmentId` fields referenced in the order line items against the completed appointments list.
4. **Formatting**: The agent outputs a clean, summarized list of appointment IDs and client names that require manual checkout review.

```mermaid
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 report
```

## Security 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.methods` parameter. 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_at` ISO 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.

> Ready to connect Boulevard and 100+ other enterprise APIs to your AI agents? Let's discuss your architecture.
>
> [Talk to us](https://truto.one/book-a-demo/)
