# MCP Server implementation guide

**Learn how to integrate with the Booking.com MCP server and build MCP-compatible AI applications. This guide explains how to authenticate, discover available tools, invoke them through the Model Context Protocol (MCP), and implement best practices for reliable integration.**

## Implementation overview

The Booking.com MCP server implements the [Model Context Protocol (MCP) specification](https://modelcontextprotocol.io/specification/2025-06-18) and exposes AI-optimised tools that can be discovered and invoked dynamically by MCP-compatible clients.

A typical integration follows this flow:

1. Authenticate with the Booking.com MCP server.
2. Discover available tools using `tools/list`.
3. Retrieve the live schema for each tool.
4. Build tool requests from the published schema.
5. Invoke tools using `tools/call`.
6. Process the returned `structuredContent`.


## Server fundamentals

The Booking.com MCP server has the following characteristics:

* **Affiliate scoped** – The tools available to your application depend on your affiliate ID.
* **Message format** – JSON-RPC 2.0.
* **Authentication** – Requests require a bearer token.
* **AI-first design** – Tool schemas and responses are optimised for LLMs and programmatic clients.
* **Stateless** – Every request is independent.


## Authentication

All requests require valid Booking.com credentials.

### Credentials

During onboarding, you receive:

- **Affiliate ID** – Identifies your Booking.com partner account.
- **Bearer token** – Authenticates every request. Since this is a sensitive information, Booking.com advises to store it securely and avoid committing it to version control or sharing it.


### Endpoint

All MCP server requests use a path-based endpoint that includes the affiliate ID:

```
POST https://demandapi-mcp.booking.com/v1/mcp/:affiliateId
```

Replace `:affiliateId` with your affiliate ID (e.g., 1234567).

Only POST requests are supported.

### Required headers

All requests must include:

```
Authorization: Bearer <your-bearer-token>
```

Invalid or expired credentials return either:

* `401 Unauthorized`
* `403 Forbidden`


## Discovering available tools

Unlike traditional REST APIs, MCP clients discover available capabilities dynamically.

* Call the `tools/list` method to retrieve the tools available to your account together with their live schemas.
* The tools exposed by the Booking.com MCP server depend on your affiliate configuration.


Current tools include:

- `accommodations_search`
- `accommodations_room_search`
- `attractions_search`
- `cars_search`
- `flights_search`
- `answer_property_qa_by_ids`


Tools are invoked through the `tools/call` method.

The response returned by `tools/list` is the authoritative source for your account.

### Understanding tool schemas

Every MCP tool publishes a live schema describing:

* Parameters
* Types
* Validation rules
* Input constraints
* Response format.


Unlike static REST documentation, the schema evolves together with the server.

Always retrieve the schema directly from the server rather than relying on copied parameter tables. Treat the live schema as the single source of truth.

## Inspecting the server

Use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to retrieve the live schema at any time, and explore all available tools and their parameter definitions:

```bash
npx -y @modelcontextprotocol/inspector
```

The Inspector lets you:

* Discover available tools.
* View live schemas.
* Inspect parameters.
* Validate requests.
* Test tool calls.


Because the Inspector retrieves information directly from the server, it always reflects the latest version of every tool.

## Calling tools

After discovering the available tools and their schemas, invoke them using the `tools/call` method.

The request must conform to the live schema returned by `tools/list`.

For programmatic integrations, always build requests from the published schema rather than hard-coding parameters.

### Understand the response

The tool returns a JSON-RPC response containing:

1. `content` **(For LLMs)**– Array of JSON strings optimised for AI reasoning and conversation generation.
2. `structuredContent` **(For Clients)** – Fully parsed JSON object with complete accommodation details. Optimised for programmatic processing


**Example response for accommodations_search**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"accommodations\":[{\"id\":12345,\"name\":\"Hotel Example Paris\",\"price\":{\"book\":135,\"currency\":\"USD\"},\"main_photo\":{\"url\":\"[https://cf.bstatic.com/](https://cf.bstatic.com/)...\"}}]}"
      }
    ],
    "structuredContent": {
      "accommodations": [
        {
          "id": 12345,
          "name": "Hotel Example Paris",
          "url": "[https://www.booking.com/hotel/fr/example-paris.html](https://www.booking.com/hotel/fr/example-paris.html)",
          "deeplink_url": "booking://hotel/12345",
          "price": {
            "base": 120,
            "book": 135,
            "total": 270,
            "currency": "USD",
            "extra_charges": {
              "included": 15,
              "excluded": 0
            }
          },
          "main_photo": {
            "url": "[https://cf.bstatic.com/xdata/images/hotel/](https://cf.bstatic.com/xdata/images/hotel/)..."
          }
        }
      ]
    },
    "_meta": {}
  }
}
```

## Testing and debugging

### Using the MCP Inspector

Use the [MCP Inspector CLI](https://modelcontextprotocol.io/docs/tools/inspector) for validating integrations.

Typical workflow:

1. Verify authentication.
2. Retrieve available tools.
3. Inspect the live schema.
4. Test a minimal request.
5. Incrementally add optional parameters.


## Examples

### List available tools

```bash
npx @modelcontextprotocol/inspector --cli \
  [https://demandapi-mcp.booking.com/v1/mcp/1234567](https://demandapi-mcp.booking.com/v1/mcp/1234567) \
  --transport http \
  --method tools/list \
  --header "Authorization: Bearer <your-bearer-token>"
```

### Call a tool

```bash
npx @modelcontextprotocol/inspector --cli \
https://demandapi-mcp.booking.com/v1/mcp/1234567 \
--transport http \
--method tools/call \
--tool-name accommodations_search \
--header "Authorization: Bearer <your-bearer-token>"
```

### Test a tool - Example with accommodation search

```bash
npx @modelcontextprotocol/inspector --cli \
  https://demandapi-mcp.booking.com/v1/mcp/1234567 \
  --transport http \
  --method tools/call \
  --tool-name accommodations_search \
  --tool-arg 'destination=Paris' \
  --tool-arg 'checkin_date=2025-12-01' \
  --tool-arg 'checkout_date=2025-12-03' \
  --tool-arg 'number_of_guests=2' \
  --tool-arg 'number_of_rooms=1' \
  --tool-arg 'user_country_code=gb' \
```

## Common integration issues

| Status | Cause | Resolution |
|  --- | --- | --- |
| `400 Bad Request` | Invalid request parameters | Validate against the live schema. |
| `401 Unauthorized` | Missing or invalid bearer token | Verify your credentials. |
| `403 Forbidden` | Invalid affiliate or insufficient permissions | Verify your onboarding configuration. |
| `429 Too Many Requests` | Rate limit exceeded | Retry using exponential backoff. |


### Rate limiting

If you exceed rate limits, the server returns `429 Too Many Requests`.

We recommend implementing exponential backoff to ensure fair access and stable integration.

## Best practices

Follow these recommendations when building MCP-compatible applications.

* Discover available tools dynamically using `tools/list`.
* Build requests from the published schema instead of hard-coded parameters.
* Treat the live schema as the authoritative source.
* Prefer `structuredContent` for programmatic processing.
* Start with simple tool calls before introducing advanced parameters.
* Monitor schema changes as part of your release process.
* Handle authentication and rate-limit errors gracefully.
* Validate all requests against the live schema before sending them.