Overview

The agentic integration path for Channels Plus.

What is Channels Plus MCP Server?

The SiteMinder Channels Plus MCP Server provides channel partners with AI-assisted access to the SiteMinder platform via the Model Context Protocol (MCP). It enables programmatic property discovery, reservation management, and property content export through a single HTTP endpoint.

Protocol: MCP (Model Context Protocol) over stateless HTTP Endpoint: POST /mcp Format: JSON-RPC 2.0 MCP Version: 2025-06-18

---

Setup

Authentication

Every request to the MCP server must include two HTTP headers:

Header	Description
x-sm-api-id	Your assigned channel identifier
x-sm-api-key	Your channel secret key

Missing or invalid credentials return HTTP 401 Unauthorized:

{
  "errors": [
    {
      "code": "credentials_required",
      "message": "missing x-sm-api-id or x-sm-api-key"
    }
  ]
}

Credentials are issued during partner onboarding. Contact your SiteMinder integration manager if you need to rotate keys.

---

Transport & Protocol

Endpoint

All MCP interactions are sent as HTTP POST requests to a single endpoint:

POST https://<mcp-server-host>/mcp

Required Headers

Header	Value
Content-Type	application/json
Accept	application/json, text/event-stream
x-sm-api-id	Your channel identifier
x-sm-api-key	Your channel secret key

Request Format

Requests use the JSON-RPC 2.0 envelope:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": {
      "<param1>": "<value1>",
      "<param2>": "<value2>"
    }
  }
}

Note: Tool parameters go inside params.arguments, not directly in params.

Response Format

Success:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<JSON-serialized result>"
      }
    ]
  }
}

Tool Error (see Error Handling for full details):

Session Model

The server is stateless. Each request is independent — there are no sessions to establish or maintain. No session initialization, handshake, or keep-alive is required.

Request Tracing

You may include an x-sm-trace-token header for correlating requests with your internal systems. If omitted, a trace token is generated automatically. Include this token when contacting SiteMinder support to help diagnose issues.

---

Using the API

Available Tools

Property Discovery

Tool	Description
list_properties	Search for properties by location, dates, and filters
show_property	Get detailed property info including room types, rates, and pricing

Reservation Management

Tool	Description
create_pending_reservation	Create a temporary hold on rooms and rates
confirm_reservation	Finalize a pending reservation with guest details and payment
show_reservation	View details of a confirmed or cancelled reservation
list_reservations	Query reservations by date range
modify_reservation	Update guest information on an existing reservation
cancel_reservation	Cancel a confirmed reservation (subject to cancellation policy)

Property Content Export

Tool	Description
export_properties	List all shoppable properties for indexing
export_property	Get full property content (photos, amenities, room types, rates, taxes, fees)

---

Booking Workflow

The standard booking flow follows four steps:

list_properties  →  show_property  →  create_pending_reservation  →  confirm_reservation
    (search)         (details)           (hold rooms)                  (finalize)

Step 1: Search Properties — list_properties

Search for available properties near a location.

Required parameters:

Parameter	Type	Description
latitude	decimal	Center latitude (-90 to 90)
longitude	decimal	Center longitude (-180 to 180)
checkInDate	string	Arrival date in yyyy-MM-dd format
checkOutDate	string	Departure date in yyyy-MM-dd format

Optional parameters:

Parameter	Type	Default	Description
radiusKm	decimal	15	Search radius in km (15-100)
totalAdults	int	—	Total adults across all rooms
totalChildren	int	—	Total children across all rooms
totalRooms	int	—	Number of rooms needed (1-10)
page	int	1	Page number
perPage	int	20	Results per page (max 100, multiple of 10)
sortBy	string	distance	Sort by distance or name
sortDirection	string	asc	asc or desc
minStarRating	decimal	—	Minimum star rating (1, 1.5, 2, ... 6)
maxStarRating	decimal	—	Maximum star rating
propertyType	string	—	e.g., Hotel, Resort, Apartment (case-sensitive)
swimmingPoolAvailable	boolean	—	Filter for swimming pool
breakfastIncluded	boolean	—	Filter for breakfast rates
freeCancellation	boolean	—	Filter for free cancellation rates
language	string	—	Preferred content language
excludeSelfRated	boolean	—	Exclude self-rated properties

Occupancy modes: Use either totalAdults/totalChildren/totalRooms (aggregate) or per-room occupancy via the rooms parameter in create_pending_reservation. These modes are mutually exclusive.

Response: Returns an array of properties. Each property includes:

• Property details (name, address, location, star rating, amenities, photos)

• Commission breakdown (totalCommissionPercentage, siteminderCommissionPercentage, channelCommissionPercentage)

• One or more room options with roomRateUuid, pricing, and cancellation policy

• acceptedCardTypes for payment (needed at confirmation step)

Step 2: View Property Details — show_property

Get full details for a specific property, including all room types and rate plans.

Required parameters:

Parameter	Type	Description
uuid	string	Property identifier (from search results)
checkInDate	string	Arrival date in yyyy-MM-dd format
checkOutDate	string	Departure date in yyyy-MM-dd format

Optional parameters:

Parameter	Type	Description
totalAdults	int	Total adults across all rooms
totalChildren	int	Total children across all rooms
totalRooms	int	Number of rooms (1-10)
language	string	Preferred content language

Response: Returns:

• Complete property information (photos, amenities, check-in/check-out times)

• Room types, each containing room rates with:

  • roomRateUuid (required for booking)

  • ratePlanName, breakfastIncluded

  • Price breakdown: totalPrice, taxes, fees

  • cancellationPolicy with policyType and freeCancellationUntilDays

  • Commission breakdown

Step 3: Create Pending Reservation — create_pending_reservation

Temporarily hold rooms at a property. The hold expires after approximately 10 minutes.

Required parameters:

Parameter	Type	Description
uuid	string	Property identifier (from search or export results)
checkInDate	string	Arrival date in yyyy-MM-dd format
checkOutDate	string	Departure date in yyyy-MM-dd format
rooms	array	Array of room objects (1-10 rooms)

Each room object:

{
  "roomRateUuid": "<from show_property results>",
  "adults": 2,
  "children": 0
}

Optional parameters:

Parameter	Type	Description
netInvoicing	boolean	Deduct commission from booking amount (default false)

Response: Returns:

• bookingReferenceId — Use this for confirmation

• expiresInMinutes — Time remaining to confirm (typically 10 minutes)

• paymentTotal, currencyCode

• rooms array, each with a roomUuid — needed for confirmation

• cancellationPolicy

• taxes and fees breakdown

IMPORTANT: You must call confirm_reservation before the pending reservation expires.

Step 4: Confirm Reservation — confirm_reservation

Finalize the pending reservation with payment and guest details.

Required parameters:

Parameter	Type	Description
bookingReferenceId	string	From create_pending_reservation response
paymentMethod	string	CreditCard or VirtualCreditCard
cardNumber	string	Full credit card number (digits only)
cardholderName	string	Name on the card
cardExpiry	string	Expiry in MM/YYYY format
cardType	string	Card type code (see below)
cardCvv	string	CVV (3-4 digits)
guestTitle	string	e.g., Mr., Mrs., Ms.
guestFirstName	string	Guest first name
guestLastName	string	Guest last name
guestEmail	string	Guest email address
guestPhoneNumber	string	Guest phone number
rooms	array	Room guest details array

Each room guest object:

{
  "roomUuid": "<from create_pending_reservation response>",
  "guestTitle": "Mr.",
  "guestFirstName": "John",
  "guestLastName": "Doe",
  "guestRemarks": "Late check-in"
}

Accepted card types:

Code	Card
AX	American Express
DN	Diners Club
DS	Discover
JC	JCB
MC	Mastercard
CU	China UnionPay
VI	Visa

Note: The cardType must match one of the property's acceptedCardTypes. Using an unsupported card type will return a 400 error.

Optional parameters:

Parameter	Type	Description
guestAddress	string	Street address
guestCity	string	City
guestState	string	State or region
guestPostcode	string	Postal code
guestCountry	string	Country
guestRemarks	string	Special requests

Virtual Credit Card (VCC) parameters (required when paymentMethod is VirtualCreditCard):

Parameter	Type	Description
vccActivationDateTime	string	ISO 8601 activation datetime
vccDeactivationDateTime	string	ISO 8601 deactivation datetime
vccCurrency	string	VCC currency code
vccBalance	decimal	VCC balance amount

---

Post-Booking Operations

View Reservation — show_reservation

Parameter	Type	Description
bookingReferenceId	string	The booking reference ID

Returns: Reservation status (Confirmed or Cancelled), dates, payment total, taxes, fees, commission details, cancellation policy, and nonRefundableDateTime.

Pending reservations return 404.

List Reservations — list_reservations

Parameter	Type	Required	Description
dateType	string	Yes	checkIn, checkOut, or bookedOn
fromDate	string	Yes	Start date (max 365 days in the past)
toDate	string	Yes	End date (max 31 days from fromDate)
page	int	No	Page number (default 1)
perPage	int	No	Results per page (max 200, default 100)

Modify Reservation — modify_reservation

Update guest information on an existing reservation. Only non-price-impacting fields can be changed. Cannot modify after the check-in date.

Parameter	Type	Required	Description
bookingReferenceId	string	Yes	Booking reference ID
guestTitle	string	No	Guest title
guestFirstName	string	No	Guest first name
guestLastName	string	No	Guest last name
guestEmail	string	No	Guest email
guestPhoneNumber	string	No	Guest phone
guestAddress	string	No	Street address
guestCity	string	No	City
guestState	string	No	State/region
guestPostcode	string	No	Postal code
guestCountry	string	No	Country
guestRemarks	string	No	Remarks/special requests
rooms	array	No	Room guest updates (see below)

Room guest update object:

{
  "roomUuid": "<room identifier>",
  "guestTitle": "Mrs.",
  "guestFirstName": "Jane",
  "guestLastName": "Doe",
  "guestRemarks": "Extra pillows"
}

Provide only the fields you want to change — omitted fields remain unchanged.

Cancel Reservation — cancel_reservation

Parameter	Type	Description
bookingReferenceId	string	Booking reference ID

Constraints:

• Only reservations with policyType: "free-cancellation" can be cancelled

• Must be within the free cancellation period (freeCancellationUntilDays before check-in date, in the property's local timezone)

• Attempting to cancel a non-refundable reservation returns an error (400)

• Already cancelled or pending reservations return an error (404)

---

Property Content Export Workflow

The export tools are designed for property indexing and caching, separate from the booking workflow.

export_properties  →  export_property (per property)
  (enumerate)           (full content)

List All Properties — export_properties

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
perPage	int	No	100	Results per page (max 500, multiple of 10)

Returns: Array of { uuid, name } for all shoppable properties.

Requires content or inventory cache level permission on your channel.

Get Full Property Content — export_property

Parameter	Type	Required	Description
uuid	string	Yes	Property identifier
languages	array	No	Language codes for translated content

Returns comprehensive property data:

• Address, location, star rating, currency

• Amenities (translated), photos with position and captions

• Accepted card types

• Taxes (name, type, rate, application method)

• Fees (name, type, rate, application method)

• Commission percentages

• Check-in/check-out times, licenses

• Room types with:

  • Name, description, room area

  • Bed configurations (translated, with quantity)

  • Photos, amenities, views

  • Max occupancy (adults, children, total)

  • Room rates with rate plan details and cancellation policies

---

Reference

Data Models

Commission Structure

All pricing includes a commission breakdown:

{
  "totalCommissionPercentage": 18.0,
  "siteminderCommissionPercentage": 3.0,
  "channelCommissionPercentage": 15.0
}

totalCommissionPercentage = siteminderCommissionPercentage + channelCommissionPercentage

Cancellation Policy

{
  "policyType": "free-cancellation",
  "freeCancellationUntilDays": 3
}

Policy Type	Description
free-cancellation	Can be cancelled up to N days before check-in
non-refundable	Cannot be cancelled; freeCancellationUntilDays is null

Translated Text

Multi-language fields use the TranslationText structure:

{
  "text": "Deluxe King Room",
  "language": "en"
}

Price Breakdown

{
  "totalPrice": 350.00,
  "totalCommissionPercentage": 18.0,
  "siteminderCommissionPercentage": 3.0,
  "channelCommissionPercentage": 15.0
}

Tax and Fee Structure

{
  "taxes": [
    { "name": "GST", "amount": 35.00 }
  ],
  "fees": [
    { "name": "Resort Fee", "amount": 25.00 }
  ]
}

For export data, taxes and fees include additional detail:

{
  "taxes": [
    { "name": "GST", "taxType": "percentage", "rate": 10.0, "application": "per_stay" }
  ],
  "fees": [
    { "name": "Resort Fee", "feeType": "flat", "rate": 25.0, "application": "per_night" }
  ]
}

---

Error Handling

There are three categories of errors:

1. Authentication Errors (HTTP 401)

Returned when credentials are missing or invalid. This is an HTTP-level error, not a JSON-RPC response:

{
  "errors": [
    {
      "code": "credentials_required",
      "message": "missing x-sm-api-id or x-sm-api-key"
    }
  ]
}

2. Tool Execution Errors

When a tool call fails (e.g., invalid property UUID, expired reservation, validation error), the server returns a successful JSON-RPC response with isError: true:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Unable to retrieve property details - HTTP 404: {\"errors\":[{\"code\":\"PropertyNotFoundError\",\"message\":\"property not found\"}]}"
      }
    ],
    "isError": true
  }
}

The text field contains a human-readable error message. Always check the isError field to distinguish errors from successful results.

Common error codes in the text field:

HTTP Status	Meaning	Common Causes
400	Bad Request	Validation error, business rule violation (e.g., cancelling a non-refundable booking, invalid card type)
404	Not Found	Invalid UUID, expired pending reservation, already cancelled reservation
429	Rate Limited	Too many requests — wait for reset period

3. Protocol Errors

Returned for invalid JSON-RPC requests (e.g., unknown tool name, malformed params):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name",
    "data": "Tool not found: nonexistent_tool"
  }
}

---

Multi-Language Support

Content is available in 8 languages:

Code	Language
de	German
en	English
es	Spanish
fr	French
id	Indonesian
it	Italian
pt	Portuguese
th	Thai

Translated fields: Property descriptions, property types, amenity names, room type names, bed configurations, and views.

If the requested language is unavailable, content falls back to the property's default language.

For booking tools (list_properties, show_property), pass a single language parameter. For export tools (export_property), pass a languages array to retrieve content in multiple languages simultaneously.

---

Integration

How It Works

In MCP, the LLM autonomously discovers and calls tools. Your code doesn't manually orchestrate the booking steps — it connects the LLM to the MCP server, and the LLM decides which tools to call based on the user's request.

For example, when a user says "Find me a hotel in Sydney for May 1-3", the LLM will:

1. Discover available tools via tools/list

2. Call list_properties with the right parameters

3. Present results to the user

4. Call show_property, create_pending_reservation, confirm_reservation as the conversation progresses

MCP Client Configuration

Add the SiteMinder MCP server to your MCP client configuration:

{
  "mcpServers": {
    "siteminder-channels-plus": {
      "url": "https://<mcp-server-host>/mcp",
      "headers": {
        "x-sm-api-id": "your-channel-id",
        "x-sm-api-key": "your-secret-key"
      }
    }
  }
}

This configuration works with any MCP-compatible client including Claude Desktop, Cursor, and custom agents built with the MCP SDK.

Building a Custom Agent (TypeScript)

If you're building your own agent, connect to the MCP server and pass the tools to your LLM:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

// Connect to the MCP server
const transport = new StreamableHTTPClientTransport(
  new URL("https://<mcp-server-host>/mcp"),
  {
    requestInit: {
      headers: {
        "x-sm-api-id": "your-channel-id",
        "x-sm-api-key": "your-secret-key",
      },
    },
  }
);
const client = new Client({ name: "partner-agent", version: "1.0.0" });
await client.connect(transport);

// Discover available tools — pass these to your LLM
const { tools } = await client.listTools();

// In your agent loop, when the LLM requests a tool call:
const result = await client.callTool({
  name: toolCall.name,       // e.g. "list_properties"
  arguments: toolCall.arguments, // e.g. { latitude: -33.8688, ... }
});

// Check for errors before returning result to the LLM
if (result.isError) {
  // Handle tool error — the LLM can retry or inform the user
  console.error("Tool error:", result.content[0].text);
}

// Feed the result back to the LLM for the next step

Programmatic Use (Property Content Export)

The export tools are typically called programmatically (not via LLM) to build a local property catalog:

// Enumerate all properties
const listResult = await client.callTool({
  name: "export_properties",
  arguments: { page: 1, perPage: 500 },
});
const allProperties = JSON.parse(listResult.content[0].text);

// Fetch full content for each property
for (const prop of allProperties.properties) {
  const contentResult = await client.callTool({
    name: "export_property",
    arguments: { uuid: prop.uuid, languages: ["en", "fr"] },
  });
  const content = JSON.parse(contentResult.content[0].text);
  // Store in your local catalog...
}

---

Best Practices

Booking Flow

1. Confirm promptly. Pending reservations expire in ~10 minutes. Build your confirmation flow to complete within this window.

2. Validate card types. Before confirming, check the property's acceptedCardTypes to ensure the guest's card type is supported.

3. Handle expiration gracefully. If a pending reservation expires (404 on confirm), re-create it via create_pending_reservation.

4. Check cancellation policy. Before presenting cancellation options to users, verify the policyType and nonRefundableDateTime.

Data Constraints

Constraint	Value
Max rooms per reservation	10
Date format	yyyy-MM-dd
Max advance booking	500 days
Length of stay	1-30 nights
Max date range for list_reservations	31 days
Max lookback for fromDate	365 days
perPage for search	Max 100 (multiple of 10)
perPage for reservations	Max 200 (multiple of 10)
perPage for export	Max 500 (multiple of 10)

Property Content Caching

• Use the export_properties + export_property workflow for building and maintaining a local property catalog

• Refresh content periodically to pick up rate plan changes, new photos, and updated amenities

• The export API requires content or inventory cache level permission — request this during onboarding

Error Recovery

• On rate limit or server errors (429, 500+): Retry with exponential backoff (recommended: 1s, 2s, 4s, max 3 retries)

• On expired pending reservation (404): Re-create the pending reservation and confirm again

• On validation error (400): Do not retry — inspect the error message to identify the issue

Security

• Store x-sm-api-key and x-sm-api-id securely; never expose them in client-side code or logs

• Use HTTPS for all MCP server communication

• Ensure your systems comply with PCI DSS requirements when handling credit card data