Connect Breeze to Claude: Sync Giving Records and Volunteer Rosters

If your team needs to connect Breeze to Claude to automate giving reconciliations, volunteer scheduling, or member management, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Breeze's REST APIs. You can either build and maintain this infrastructure yourself, 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 Breeze to ChatGPT or explore our broader architectural overview on connecting Breeze to AI Agents.

Giving a Large Language Model (LLM) read and write access to a specialized Church Management System (ChMS) like Breeze is an engineering challenge. You have to handle API key lifecycles, map Breeze's highly specific JSON schemas to MCP tool definitions, and deal with unusual endpoint behaviors. Every time you want to expose a new custom profile field to Claude, 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 Breeze, connect it natively to Claude Desktop, and execute complex administrative workflows using natural language.

The Engineering Reality of the Breeze 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 Breeze's API is painful. Breeze was built to solve domain-specific problems for church administration, and its API design reflects structural quirks that do not map cleanly to standard CRUD operations.

If you decide to build a custom Breeze MCP server, here are the specific integration challenges you will face:

Write Operations Disguised as Query Parameters Many APIs use POST or PUT requests with a JSON body for write operations. Breeze frequently requires arguments to be passed directly in the URL query string - even for destructive or creation actions. For example, adding a contribution, creating an event, or assigning a tag all require the payload to be formatted as query parameters. An LLM cannot inherently guess this transport mechanism. Your MCP server must intercept the LLM's flat JSON arguments and correctly map them into URL query strings before executing the HTTP request.

Complex JSON Arrays for Custom Fields Updating or creating a person in Breeze is not a simple flat object mapping. Standard fields like first and last are passed normally, but any custom profile fields must be sent as a serialized JSON array of objects, specifically formatted as {field_id, field_type, response, details}. To make this accessible to Claude, you have to build a dynamic tool schema that fetches the available profile_fields, translates them into a schema the LLM understands, and then reconstructs the required fields_json array before sending it to Breeze.

Composite Keys for Deletions Breeze does not always provide a single clean UUID for relational records. If you want to remove an attendance record, delete a volunteer assignment, or unassign a tag, there is no single assignment_id to call DELETE /assignments/:id. Instead, you must pass composite named fields (like person_id and instance_id, or person_id and tag_id). Standard REST mapping patterns break down here, requiring custom routing logic for almost every destructive operation.

Rate Limits and Error Handling Breeze enforces strict rate limits to protect its infrastructure. It is important to note the factual reality of how Truto handles this: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Breeze API returns an HTTP 429, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your AI agent framework is entirely responsible for reading these headers and executing its own backoff and retry logic.

Creating the Breeze MCP Server

Truto dynamically generates MCP tools based on integration documentation and available resources. Instead of hand-coding tool definitions for every Breeze endpoint, Truto reads the API schemas and compiles them into a JSON-RPC 2.0 endpoint that any MCP client can consume.

You can generate a secure MCP server URL for Breeze using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams who prefer a visual setup, generating an MCP server takes seconds:

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Breeze account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., name the server "Breeze Production", restrict allowed methods to read and write, or set an expiration date for temporary access).
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For developers automating infrastructure, you can generate MCP servers programmatically. This is ideal for provisioning isolated agent environments per tenant.

Send a POST request to /integrated-account/:id/mcp with your configuration:

curl -X POST https://api.truto.one/admin/integrated-account/<breeze_account_id>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Breeze Volunteer AI Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["volunteers", "events", "people"]
    },
    "expires_at": null
  }'

The API returns a fully provisioned MCP server URL backed by Cloudflare KV and a D1 database record for high-speed, secure authentication.

Connecting the MCP Server to Claude

Once you have your MCP server URL, you need to connect it to your LLM interface. Because Truto's MCP servers are self-contained and authenticate via a hashed token in the URL, no additional client-side OAuth handling is required.

Method A: Via the Claude or ChatGPT UI

If you are using enterprise chat interfaces that support custom connectors, you can add the server directly through the settings.

For Claude (Desktop or Web):

1. Go to Settings -> Integrations (or Connectors) -> Add MCP Server.
2. Paste your Truto MCP URL.
3. Click Add. Claude will immediately handshake with the server and ingest the Breeze tools.

For ChatGPT:

1. Go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under Custom Connectors, click Add new server.
4. Name it "Breeze (Truto)" and paste your MCP URL.
5. Click Save.

Method B: Via Manual Config File (Claude Desktop)

If you are running Claude Desktop locally or deploying a headless agent using LangChain or Cursor, you configure the connection using a JSON file. Because Truto hosts the server remotely, you use the official @modelcontextprotocol/server-sse package to bridge the local client to the remote Server-Sent Events (SSE) endpoint.

Add this to your claude_desktop_config.json:

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

Restart Claude Desktop. The client will execute the SSE proxy, connect to Truto, and display the Breeze tools in the UI.

Hero Tools for Breeze

Truto translates Breeze's endpoints into descriptive, snake_case tools. Query and body schemas are automatically extracted and merged into a flat input namespace for the LLM.

Here are the highest-leverage tools available for automating church administration.

list_all_breeze_people

This is the core lookup tool for finding members, staff, and visitors. It supports a complex filter_json argument allowing the LLM to query by specific profile field IDs (e.g., finding all people with a specific tag or demographic). Truto handles the pagination automatically, allowing the LLM to page through large directories using limits and offsets.

"Find all members in the database who have the 'Choir Member' tag and return their contact information."

create_a_breeze_contribution

This tool allows the agent to record giving and donations. It requires parameters like person_json and uid to help Breeze map the processed payment to the correct member profile. It is incredibly useful for reconciling batch reports from third-party payment gateways.

"Record a new $100 tithe contribution for John Smith. Group it into today's general giving batch."

list_all_breeze_events

Retrieves the calendar of upcoming events, services, and meetings. The agent can use this to find the exact instance_id required for subsequent operations like tracking attendance or assigning volunteer roles.

"List all events happening this coming Sunday morning and give me their specific instance IDs."

create_a_breeze_volunteer

Schedules a member to serve at a specific event. This tool takes the instance_id of the event and the person_id of the volunteer. Truto handles mapping these arguments into the required query string format that Breeze expects.

"Schedule Sarah Jenkins to volunteer for the 9:00 AM Sunday Service this weekend."

create_a_breeze_attendance

Logs a person as having attended a specific event instance. Like the volunteer tool, it requires person_id and instance_id. This allows agents to process digital check-ins or update attendance records from physical rosters.

"Mark David Miller as present for the Wednesday night youth group meeting."

create_a_breeze_tag_assignment

Tags are the primary way Breeze groups people (e.g., "Small Group Leaders", "VBS Volunteers", "Members"). This tool takes a person_id and a tag_id to add someone to a specific cohort.

"Assign the 'New Visitor' tag to the three families that submitted connect cards today."

For a complete list of available operations and exact schema definitions, visit the Breeze integration page.

Workflows in Action

Exposing these tools to Claude transforms manual data entry into conversational workflows. Here are two real-world scenarios.

Scenario 1: Sunday Service Reconciliation

After a weekend service, church administrators typically have to log attendance and reconcile digital giving. An agent can handle this entire process autonomously.

"Look up the 10:00 AM Sunday Service from yesterday. Find the attendee records for the 'Smith Family' and mark them all as present. Then, log a $250 contribution for Michael Smith towards the General Fund."

Execution Steps:

1. Claude calls list_all_breeze_events to find the exact instance_id for yesterday's 10:00 AM service.
2. Claude calls list_all_breeze_people using a filter to find the person_ids for the Smith family members.
3. Claude loops through the IDs and calls create_a_breeze_attendance for each member, using the instance_id.
4. Claude calls create_a_breeze_contribution to record the $250 gift, mapping it to Michael Smith's profile.

flowchart TD
    A["User Prompt:<br>Reconcile Sunday"] --> B["list_all_breeze_events<br>(Find Sunday Service)"]
    B --> C["list_all_breeze_people<br>(Find Smith Family)"]
    C --> D["create_a_breeze_attendance<br>(Mark Present)"]
    C --> E["create_a_breeze_contribution<br>(Record Gift)"]
    D --> F["Return Success<br>Message to User"]
    E --> F

The user receives a plain text confirmation that the family's attendance was logged and the financial contribution was successfully tied to the correct profile.

Scenario 2: Volunteer Roster Crisis

When a scheduled volunteer calls in sick at the last minute, an agent can quickly find a replacement and update the system.

"Our usher for the 6:00 PM service tonight just canceled. Remove Tom Baker from the volunteer schedule. Then, find a list of all eligible people with the 'Usher' tag, and schedule James Wilson in his place."

Execution Steps:

1. Claude calls list_all_breeze_events to get the instance_id for the 6:00 PM service.
2. Claude calls list_all_breeze_people to resolve Tom Baker's person_id.
3. Claude calls delete_a_breeze_volunteer_by_id passing Tom's person_id and the event instance_id (handling the composite key requirement seamlessly).
4. Claude calls list_all_breeze_eligible_people (or queries tags) to find valid ushers.
5. Claude calls create_a_breeze_volunteer to assign James Wilson to the event.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Breeze as Breeze API

    User->>Claude: "Remove Tom, assign James as usher tonight"
    Claude->>Truto: Call list_all_breeze_events
    Truto->>Breeze: GET /events
    Breeze-->>Truto: Return instance_id
    Truto-->>Claude: Return instance_id
    
    Claude->>Truto: Call delete_a_breeze_volunteer_by_id (Tom)
    Truto->>Breeze: GET /events/remove_volunteer?person_id=...
    Breeze-->>Truto: 200 OK
    Truto-->>Claude: Success

    Claude->>Truto: Call create_a_breeze_volunteer (James)
    Truto->>Breeze: GET /events/add_volunteer?person_id=...
    Breeze-->>Truto: 200 OK
    Truto-->>Claude: Success
    Claude-->>User: "Roster updated successfully."

The administrator resolves a stressful scheduling conflict in seconds without ever logging into the Breeze UI or manually clicking through rosters.

Security and Access Control

Giving AI agents access to a church database containing sensitive pastoral notes and financial records requires strict security boundaries. Truto MCP servers provide multiple layers of access control out of the box:

• Method Filtering (config.methods): Restrict the MCP server to specific operations. For example, setting methods: ["read"] ensures the agent can query directories but cannot delete profiles or modify financial records.
• Tag Filtering (config.tags): Scope the server to specific functional areas. If you only want an agent managing volunteers, you can configure the MCP server to only expose tools tagged with "volunteers" and "events".
• Extra Authentication (require_api_token_auth): When set to true, possession of the MCP URL is not enough. The client must also pass a valid Truto API token in the Authorization header, adding a strict secondary identity check.
• Automatic Expiration (expires_at): Perfect for temporary staff or contractors. Set an ISO datetime, and Truto will automatically destroy the MCP token and its associated Cloudflare KV entries when the time expires, instantly revoking the AI's access.

Final Thoughts

Building a custom integration to give an AI agent access to Breeze requires navigating complex query-string architectures, composite deletion keys, and non-standard JSON payloads. Every time Breeze updates an endpoint, your custom integration layer has to be updated.

Using a managed MCP server via Truto eliminates this technical debt. Truto dynamically generates the tools based on accurate documentation, handles the routing quirks, normalizes the rate limit headers, and provides a secure SSE bridge directly to Claude. Your engineering team can focus on designing great agentic workflows instead of fighting with legacy ChMS APIs.