> For the complete documentation index, see [llms.txt](https://docs.rateparity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rateparity.com/mcp.md).

# MCP Server

The RateParity API exposes a stateless MCP server over HTTP. MCP clients can use this endpoint to list and call tools for property information, rooms, reviews, rates, shopper results, and availability.

`POST` `https://api.rateparity.com/mcp`

The MCP endpoint uses JSON-RPC 2.0 payloads following the MCP HTTP transport.

## Authentication

The MCP server uses the same Bearer token authentication as the public REST API. See [Authentication](/authentication.md) for the standard authentication flow.

Required headers:

| Name            | Required | Value                                 |
| --------------- | -------- | ------------------------------------- |
| `Authorization` | Yes      | `Bearer YOUR_API_KEY`                 |
| `Content-Type`  | Yes      | `application/json`                    |
| `Accept`        | Yes      | `application/json, text/event-stream` |

Example:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}'
```

MCP tools also check that the authenticated user is authorized for the requested property code.

## Response Data

MCP tool responses include a short text summary and machine-readable data.

MCP clients should use:

```
result.structuredContent
```

The `content` array is intended for clients that display a short textual response.

## List Tools

Use the `tools/list` JSON-RPC method to retrieve the available MCP tools.

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_property_info",
        "description": "Fetch the complete external property information for a RateParity hotel code."
      },
      {
        "name": "get_property_rooms",
        "description": "Fetch the complete external room information for a RateParity hotel code."
      },
      {
        "name": "get_property_reviews",
        "description": "Fetch external review details for a RateParity hotel code."
      },
      {
        "name": "get_property_lowest_monthly_rates",
        "description": "Fetch the lowest monthly rates for a RateParity hotel code."
      },
      {
        "name": "shop_property_rate",
        "description": "Shop rates for a RateParity hotel code and stay dates."
      },
      {
        "name": "get_property_availability_single",
        "description": "Fetch single-property availability rates for a RateParity hotel code."
      }
    ]
  }
}
```

## Call a Tool

Use the `tools/call` JSON-RPC method. The `name` field is the MCP tool name, and `arguments` contains the tool input.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_property_info",
    "arguments": {
      "hotelCode": "MASTERPLAK"
    }
  }
}
```

## Tool Reference

### get\_property\_info

Fetches complete external property information for a RateParity hotel code.

**Input**

| Name        | Type   | Required | Description       |
| ----------- | ------ | -------- | ----------------- |
| `hotelCode` | string | Yes      | The property code |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_property_info",
    "arguments": {
      "hotelCode": "MASTERPLAK"
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Property information for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "code": "MASTERPLAK",
        "name": "master Plaka Athens",
        "bookurl": "https://masterplakaathens.reserve-online.net/?src=606"
      }
    }
  }
}
```

### get\_property\_rooms

Fetches complete external room information for a RateParity hotel code.

**Input**

| Name        | Type   | Required | Description       |
| ----------- | ------ | -------- | ----------------- |
| `hotelCode` | string | Yes      | The property code |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_property_rooms",
    "arguments": {
      "hotelCode": "MASTERPLAK"
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Room information for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "rooms": [
          {
            "code": "ROOM_CODE",
            "name": "Room name",
            "active": true
          }
        ]
      }
    }
  }
}
```

### get\_property\_reviews

Fetches review details for a RateParity hotel code.

**Input**

| Name                | Type             | Required | Description                                                        |
| ------------------- | ---------------- | -------- | ------------------------------------------------------------------ |
| `hotelCode`         | string           | Yes      | The property code                                                  |
| `page`              | integer          | No       | Page number. Default `1`                                           |
| `limit`             | integer          | No       | Page size. Default `10`                                            |
| `sort`              | string           | No       | Sort field. Default `dateReviewed`                                 |
| `asc`               | boolean          | No       | Sort ascending. Default `false`                                    |
| `verbose`           | boolean          | No       | Return verbose review details. Default `true`                      |
| `category`          | ReviewerCategory | No       | See [Reviewer Category Type](/datatypes.md#reviewer-category-type) |
| `score`             | ReviewScore      | No       | See [Review Score Type](/datatypes.md#review-score-type)           |
| `country`           | string           | No       | Reviewer country filter                                            |
| `reviewerLanguages` | list             | No       | Reviewer language filters                                          |
| `season`            | Season           | No       | See [Season Type](/datatypes.md#season-type)                       |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_property_reviews",
    "arguments": {
      "hotelCode": "MASTERPLAK",
      "page": 1,
      "limit": 3,
      "sort": "dateReviewed",
      "asc": false,
      "verbose": true
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Review information for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "score": 9.47,
        "reviews": 652,
        "userReviews": [
          {
            "id": 1953335,
            "title": "Excellent",
            "score": 10.0,
            "channel": "Google.com"
          }
        ],
        "totalFound": 439,
        "totalPages": 147
      }
    }
  }
}
```

### get\_property\_lowest\_monthly\_rates

Fetches the lowest monthly rates for a RateParity hotel code.

**Input**

| Name        | Type   | Required | Description       |
| ----------- | ------ | -------- | ----------------- |
| `hotelCode` | string | Yes      | The property code |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_property_lowest_monthly_rates",
    "arguments": {
      "hotelCode": "MASTERPLAK"
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Lowest monthly rates for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "hotelCode": "MASTERPLAK",
        "currency": "EUR",
        "lowestMonthlyRates": [
          {
            "month": 10,
            "year": 2026,
            "rate": 120.5,
            "day": "2026-10-26",
            "minStay": 2
          }
        ]
      }
    }
  }
}
```

### shop\_property\_rate

Shops rates for a RateParity hotel code and stay dates.

**Input**

| Name        | Type    | Required | Description                                    |
| ----------- | ------- | -------- | ---------------------------------------------- |
| `hotelCode` | string  | Yes      | The property code                              |
| `checkIn`   | date    | Yes      | Check-in date in `yyyy-MM-dd` format           |
| `checkOut`  | date    | Yes      | Check-out date in `yyyy-MM-dd` format          |
| `adults`    | integer | No       | Number of adults. Default `2`                  |
| `children`  | integer | No       | Number of children. Default `0`                |
| `rateId`    | string  | No       | Rate identifier                                |
| `channel`   | Channel | No       | See [Channel Type](/datatypes.md#channel-type) |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "shop_property_rate",
    "arguments": {
      "hotelCode": "MASTERPLAK",
      "checkIn": "2026-10-26",
      "checkOut": "2026-10-28",
      "adults": 2,
      "children": 0
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Shopper rates for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "currency": "EUR",
        "rates": [
          {
            "price": 120.5,
            "roomId": "ROOM_CODE",
            "rateId": "RATE_CODE",
            "roomName": "Room name",
            "lowestRate": true
          }
        ]
      }
    }
  }
}
```

### get\_property\_availability\_single

Fetches single-property availability rates for a RateParity hotel code.

**Input**

| Name            | Type    | Required | Description                           |
| --------------- | ------- | -------- | ------------------------------------- |
| `hotelCode`     | string  | Yes      | The property code                     |
| `checkIn`       | date    | Yes      | Check-in date in `yyyy-MM-dd` format  |
| `checkOut`      | date    | Yes      | Check-out date in `yyyy-MM-dd` format |
| `adults`        | integer | Yes      | Number of adults                      |
| `currency`      | string  | Yes      | Currency code, for example `EUR`      |
| `children`      | integer | No       | Number of children                    |
| `infants`       | integer | No       | Number of infants                     |
| `rooms`         | integer | No       | Number of rooms                       |
| `device`        | string  | No       | `DESKTOP` or `MOBILE`                 |
| `lang`          | string  | No       | Language code, for example `en`       |
| `timezone`      | string  | No       | Timezone, for example `Europe/Athens` |
| `remoteCountry` | string  | No       | Remote country code, for example `GR` |

Example request:

```bash
curl --location 'https://api.rateparity.com/mcp' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_property_availability_single",
    "arguments": {
      "hotelCode": "MASTERPLAK",
      "checkIn": "2026-10-26",
      "checkOut": "2026-10-28",
      "adults": 2,
      "currency": "EUR"
    }
  }
}'
```

Expected response shape:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Availability rates for MASTERPLAK"
      }
    ],
    "isError": false,
    "structuredContent": {
      "data": {
        "hotelCode": "MASTERPLAK",
        "checkIn": "2026-10-26",
        "checkOut": "2026-10-28",
        "adults": 2,
        "currency": "EUR",
        "rates": [
          {
            "id": "RATE_ID",
            "room": "ROOM_CODE",
            "roomDesc": "Room name",
            "rate": "RATE_CODE",
            "rateDesc": "Rate name",
            "board": 3,
            "boardDesc": "Bed & breakfast",
            "minStay": 2,
            "remaining": 2,
            "status": "AVL",
            "statusDesc": "Available",
            "pricing": {
              "price": 120.5,
              "memberPrice": 110.0,
              "excludedCharges": 0.0,
              "discount": 10.0
            },
            "bookingUrl": "https://example.reserve-online.net/"
          }
        ]
      }
    }
  }
}
```

## Input Format

Tool arguments must use plain JSON values. For example, `hotelCode` must be a string.

Correct:

```json
{
  "hotelCode": "MASTERPLAK"
}
```

Incorrect:

```json
{
  "hotelCode": {
    "value": "MASTERPLAK"
  }
}
```

## Error Behavior

### Missing or invalid token

Requests without a valid Bearer token return:

```
HTTP 401 Unauthorized
```

### Unauthorized property

If the authenticated user is not authorized for the requested property code, the tool call fails before fetching property data.

### Invalid request body

Invalid JSON-RPC payloads, missing required headers, malformed arguments, or invalid argument types return either an HTTP transport error or an MCP error response.