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.

The Booking.com MCP server implements the Model Context Protocol (MCP) specification 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.

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.

All requests require valid Booking.com 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.

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).

All requests must include:

Authorization: Bearer <your-bearer-token>

Invalid or expired credentials return either:

• 401 Unauthorized
• 403 Forbidden

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.

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.

Use the MCP Inspector to retrieve the live schema at any time, and explore all available tools and their parameter definitions:

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.

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.

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

{
  "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": {}
  }
}

Use the MCP Inspector CLI 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.

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>"

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>"

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' \

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

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

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.