Duffel MCP Server

Instructions

Retrieve detailed information and current pricing for a specific flight offer.

This tool fetches the latest version of an offer, including:
- Up-to-date pricing and availability
- Complete flight schedule and routing
- Passenger requirements and restrictions
- Baggage allowance and cabin details
- Cancellation and change policies

Use this when:
- User selects a flight from search results
- Before booking to confirm current price
- To check if an offer is still available
- To get passenger IDs needed for booking

Important: Always retrieve the offer immediately before booking to ensure pricing
is current, as offers expire after 15-30 minutes.

Returns offer details in specified format (JSON or Markdown).

Implementation Reference

• duffel_mcp/tools/flights.py:127-189 (handler)

  The handler function that implements the core logic of the duffel_get_offer tool, fetching offer details from Duffel API, validating expiration, and formatting output.

  async def get_offer(params: GetOfferInput) -> str:
      """
      Retrieve detailed information and current pricing for a specific flight offer.
      
      This tool fetches the latest version of an offer, including:
      - Up-to-date pricing and availability
      - Complete flight schedule and routing
      - Passenger requirements and restrictions
      - Baggage allowance and cabin details
      - Cancellation and change policies
      
      Use this when:
      - User selects a flight from search results
      - Before booking to confirm current price
      - To check if an offer is still available
      - To get passenger IDs needed for booking
      
      Important: Always retrieve the offer immediately before booking to ensure pricing
      is current, as offers expire after 15-30 minutes.
      
      Returns offer details in specified format (JSON or Markdown).
      """
      try:
          response = await make_api_request(
              method="GET",
              endpoint=f"/air/offers/{params.offer_id}"
          )
          
          offer = response["data"]
          
          expires_at = datetime.fromisoformat(offer["expires_at"].replace("Z", "+00:00"))
          if expires_at < datetime.now().astimezone():
              return (
                  f"⚠️ This offer has expired at {offer['expires_at']}.\n\n"
                  "Offers typically expire 15-30 minutes after creation. "
                  "Please perform a new flight search to get current offers."
              )
          
          if params.response_format == ResponseFormat.JSON:
              return truncate_text(format_json_response(offer))
          
          else:  # Markdown format
              result = format_markdown_flight_offer(offer)
              
              passengers = offer.get("passengers", [])
              if passengers:
                  result += "\n### Passengers\n"
                  for i, pax in enumerate(passengers, 1):
                      result += f"{i}. **ID**: `{pax['id']}` - Type: {pax.get('type', 'N/A')}\n"
              
              conditions = offer.get("conditions", {})
              if conditions:
                  result += "\n### Booking Conditions\n"
                  if conditions.get("change_before_departure"):
                      result += f"- Change allowed: {conditions['change_before_departure'].get('allowed', False)}\n"
                  if conditions.get("refund_before_departure"):
                      result += f"- Refund allowed: {conditions['refund_before_departure'].get('allowed', False)}\n"
              
              return truncate_text(result)
              
      except Exception as e:
          return f"Error retrieving offer: {str(e)}\n\nTroubleshooting:\n- Verify the offer ID is correct (starts with 'off_')\n- Check if the offer has expired\n- Offer might have been booked by someone else"

• duffel_mcp/models/flights.py:117-130 (schema)

  Pydantic input schema defining parameters for duffel_get_offer: offer_id (required, validated pattern) and response_format.

  class GetOfferInput(BaseModel):
      """Input for retrieving a specific flight offer."""
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid')
  
      offer_id: str = Field(
          ...,
          description="Duffel offer ID (e.g., 'off_00009htYpSCXrwaB9DnUm0')",
          pattern="^off_[a-zA-Z0-9]+$"
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'json' for raw data or 'markdown' for readable summary"
      )

• duffel_mcp/tools/flights.py:117-126 (registration)

  MCP decorator registering the tool with name 'duffel_get_offer' and operational annotations.

  @mcp.tool(
      name="duffel_get_offer",
      annotations={
          "title": "Get Flight Offer Details",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True
      }
  )