Skip to main content
Glama
FortripEngineering

Duffel MCP Server

by FortripEngineering
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Duffel MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with the Duffel API for searching and booking flights, accommodations, and managing travel bookings.

Features

✈️ Flight Operations

  • Search Flights - Find available flights with pricing, schedules, and airline information

  • Get Offer Details - Retrieve up-to-date pricing and availability for specific offers

  • Create Orders - Book flights with passenger details and payment

  • Manage Orders - View and manage existing bookings

🌍 Supporting Resources

  • Search Airports - Find airports by name, city, or IATA code

  • List Airports - Browse airports with country filtering

🎯 Key Capabilities

  • 300+ Airlines - Access to major airlines via NDC, GDS, and LCC

  • Real-time Data - Live pricing, availability, and seat selection

  • Flexible Search - One-way, round-trip, multi-city support

  • Smart Responses - JSON or Markdown formatted output

  • Error Handling - Clear, actionable error messages

Installation

Prerequisites

  • Python 3.12 or higher

  • Duffel API account (sign up here)

  • Duffel API access token

  • uv (fast Python package manager)

Install uv

On macOS with Homebrew:

brew install uv

Or via the official installer (macOS/Linux):

curl -LsSf https://astral.sh/uv/install.sh | sh
# then restart your shell or source the profile output by the installer

Project setup

  1. Clone or download the server file/repo

  2. Create the virtual environment and install dependencies with uv:

uv sync

This uses pyproject.toml to create .venv and install exact versions.

  1. Set up environment variable:

export DUFFEL_ACCESS_TOKEN="your_duffel_token_here"

Get your token from the Duffel Dashboard:

  • Navigate to: More → Developers → Access Tokens

  • Create a test token for testing (free, unlimited balance)

  • Create a live token for production bookings

Usage

Running the Server

Run with uv (uses the synced virtualenv automatically):

uv run python duffel_mcp.py

Configuration for Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "duffel": {
      "command": "uv",
      "args": ["run", "python", "/path/to/duffel_mcp.py"],
      "env": {
        "DUFFEL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Configuration for Other MCP Clients

For other MCP clients, follow their specific configuration format, ensuring:

  • The server is launched with Python 3.12+

  • DUFFEL_ACCESS_TOKEN environment variable is set

  • Server communicates via stdio

Available Tools

1. duffel_search_flights

Search for available flights based on journey requirements.

Parameters:

  • slices - Journey legs (origin, destination, date)

  • passengers - List of travelers (use age for best accuracy)

  • cabin_class - Optional: economy, premium_economy, business, first

  • max_connections - Optional: limit stops (0 = direct flights)

  • response_format - json or markdown

Example:

{
  "slices": [
    {
      "origin": "JFK",
      "destination": "LAX",
      "departure_date": "2025-12-15"
    },
    {
      "origin": "LAX",
      "destination": "JFK",
      "departure_date": "2025-12-22"
    }
  ],
  "passengers": [
    {"age": 35},
    {"age": 32},
    {"age": 8}
  ],
  "cabin_class": "economy",
  "max_connections": 1
}

2. duffel_get_offer

Retrieve current pricing and details for a specific offer.

Parameters:

  • offer_id - Offer ID from search results

  • response_format - json or markdown

Important: Always call this before booking to ensure offer is still valid and get current pricing.

3. duffel_create_order

Create a flight booking with passenger details and payment.

Parameters:

  • offer_id - Offer ID to book

  • passengers - Complete passenger details (name, DOB, contact)

  • payments - Payment information

  • response_format - json or markdown

⚠️ Warning: This creates real bookings! Use test tokens for development.

Example:

{
  "offer_id": "off_00009htYpSCXrwaB9DnUm0",
  "passengers": [
    {
      "id": "pas_00009hj8USM7Ncg31cBCL",
      "given_name": "John",
      "family_name": "Smith",
      "born_on": "1985-03-15",
      "email": "john.smith@example.com",
      "phone_number": "+14155551234",
      "gender": "m",
      "title": "mr"
    }
  ],
  "payments": [
    {
      "type": "balance",
      "amount": "520.00",
      "currency": "USD"
    }
  ]
}

4. duffel_get_order

Retrieve details for an existing order.

Parameters:

  • order_id - Order ID from booking

  • response_format - json or markdown

5. duffel_search_airports

Search for airports by name, city, or code.

Parameters:

  • query - Search term (e.g., "London", "Heathrow", "LHR")

  • limit - Max results (1-100, default: 20)

  • response_format - json or markdown

6. duffel_list_airports

List airports with optional country filter.

Parameters:

  • country_code - Optional: ISO country code (e.g., "US", "GB")

  • limit - Results per page (1-200, default: 50)

  • response_format - json or markdown

Typical Workflows

Booking a Flight

  1. Search for flights:

Search for round-trip flights from New York to London, departing Dec 15, returning Dec 22, 
2 adult passengers, economy class, direct flights only

  1. Get offer details:

Get the latest pricing for offer off_00009htYpSCXrwaB9DnUm0

  1. Create booking:

Book this offer with passengers: John Smith (john@example.com, +14155551234, DOB 1985-03-15) 
and Jane Smith (jane@example.com, +14155551235, DOB 1987-07-20). Use balance payment for $1,450.00 USD.

Finding Airports

What airports are in the London area?
What's the airport code for San Francisco International?

Best Practices

✅ Do's

  1. Use age over type - Provides better accuracy across airlines

  2. Check offer expiry - Offers expire in 15-30 minutes

  3. Verify before booking - Always retrieve offer for current price

  4. Test mode first - Use test tokens during development

  5. Handle async responses - Some bookings return 200/202 with webhook notifications

❌ Don'ts

  1. Don't retry failed bookings - If order creation fails, don't retry the same request

  2. Don't cache offers - Always fetch fresh data before booking

  3. Don't ignore validation errors - They guide toward correct usage

  4. Don't use expired offers - Check expires_at timestamp

Error Handling

The server provides clear, actionable error messages:

  • offer_expired - Perform new search

  • offer_no_longer_available - Select different offer

  • price_changed - Retrieve offer again for updated price

  • validation_error - Check parameter formats and requirements

  • payment_declined - Verify payment details

Testing

Test Mode

Duffel provides unlimited test balance:

  1. Create a test access token in dashboard

  2. Use "type": "balance" for payments

  3. Search and book without actual charges

  4. Use test airline: "Duffel Airways"

Manual Testing

# Set test token
export DUFFEL_ACCESS_TOKEN="duffel_test_xxx"

# Run server with uv
uv run python duffel_mcp.py

Then interact through your MCP client to test various workflows.

API Reference

For complete Duffel API documentation:

Troubleshooting

"DUFFEL_ACCESS_TOKEN environment variable not set"

Set the environment variable with your Duffel API token.

"offer_expired" errors

Offers have short expiry times (15-30 min). Perform a new search.

"validation_error" on booking

  • Check passenger names match government ID exactly

  • Verify date format is YYYY-MM-DD

  • Ensure payment amount matches offer total

  • Confirm all required fields are provided

"No flights found"

  • Verify airport codes are valid IATA codes (use duffel_search_airports)

  • Check dates are in future

  • Try broader search criteria (more connections, different cabin class)

Webhooks not received

  • Configure webhook URLs in Duffel Dashboard

  • Check your email for booking confirmations

  • Use duffel_get_order to manually check order status

License

This MCP server is provided as-is for integration with Duffel API. See Duffel's terms of service for API usage terms.

Support

Contributing

Contributions welcome! Potential enhancements:

  • Stays API integration (hotel bookings)

  • Order modifications and cancellations

  • Seat selection tools

  • Baggage management

  • Loyalty program integration

  • Advanced filtering options

Version History

  • v0.1.0 - Initial release

    • Flight search and booking

    • Order management

    • Airport search

    • Markdown and JSON output formats

Available Tools

6 tools
duffel_create_orderA
Create a flight booking (order) for the specified offer and passengers.

⚠️ IMPORTANT: This creates a real booking and may involve payment. This action:
- Creates a confirmed airline reservation
- May charge the payment method (if not using test mode)
- Issues a booking reference from the airline
- Is typically non-refundable or has cancellation fees

Before calling this tool:
1. Verify the offer is current using duffel_get_offer
2. Confirm all passenger details are accurate (names match IDs)
3. Check payment amount matches offer total
4. Ensure user understands booking terms

Required data:
- Offer ID from search results
- Complete passenger details (names as on ID, date of birth, contact info)
- Payment information matching offer total

The tool returns:
- Order ID for reference
- Airline booking reference
- Confirmation details
- Ticket information

Response codes:
- 201: Order created successfully (immediate confirmation)
- 200: Booking confirmed, details arriving soon (webhook notification will follow)
- 202: Booking processing (check webhooks or email for confirmation)

Use test mode tokens for testing to avoid actual charges.

Returns order details in specified format (JSON or Markdown).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond annotations: it discloses that this creates real bookings with payment implications, is typically non-refundable, and has specific response codes (201, 200, 202) with different meanings. Annotations provide basic hints (not read-only, not idempotent, etc.), but the description elaborates on real-world consequences like airline reservations and webhook notifications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (warning, prerequisites, required data, returns, response codes, testing note) and front-loaded critical information. Some redundancy exists (e.g., 'Returns order details' appears twice), but overall it's efficient with no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (real-world booking with payment), lack of schema descriptions, and presence of an output schema, the description is highly complete. It covers purpose, usage, behavioral risks, parameter expectations, response handling, and testing guidance, leaving minimal gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 1 parameter (params referencing CreateOrderInput), the description compensates well by explaining required data: offer ID, passenger details (names, DOB, contact), and payment information. It doesn't detail the exact structure of CreateOrderInput but provides meaningful semantic context about what the parameter should contain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a flight booking') and resource ('order for the specified offer and passengers'), distinguishing it from sibling tools like duffel_get_offer (read-only) and duffel_search_flights (search). It goes beyond the title by specifying it's for flight booking with offer and passenger inputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (after verifying offer with duffel_get_offer, confirming passenger details, checking payment, and understanding terms) and when not to use (without test mode tokens to avoid charges). It names the alternative tool (duffel_get_offer) and includes prerequisites in a numbered list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

duffel_get_offerA
Read-onlyIdempotent
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).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, idempotent, and open-world behavior. The description adds valuable context beyond annotations: it specifies that offers 'expire after 15-30 minutes,' which is crucial for timing usage. However, it doesn't mention rate limits or authentication needs, leaving some behavioral aspects uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose. Each bullet point and usage guideline sentence adds specific value without redundancy. The 'Important' note is concise and critical, making every part of the text earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (retrieving dynamic flight data), the description is complete. It covers purpose, usage scenarios, critical timing constraints, and key data returned. With annotations covering safety and idempotency, and an output schema handling return format details, no significant gaps remain for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the description provides no details about the single parameter (e.g., what 'params' contains or how to specify the offer). However, with an output schema present, the description doesn't need to explain return values. The baseline is 3 since the schema handles parameter documentation, but the description adds no semantic clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'retrieve' and resource 'detailed information and current pricing for a specific flight offer.' It distinguishes from siblings like duffel_search_flights (which searches) and duffel_create_order (which books). The title 'Get Flight Offer Details' reinforces this specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists four scenarios for when to use this tool (e.g., 'User selects a flight from search results,' 'Before booking to confirm current price'). It also provides a critical exclusion: 'Always retrieve the offer immediately before booking to ensure pricing is current,' which implicitly advises against using stale data from other sources.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

duffel_get_orderA
Read-onlyIdempotent
Retrieve complete details for an existing flight order.

This tool fetches:
- Order status and booking reference
- Flight itinerary and schedule
- Passenger information
- Payment and pricing details
- Documents and tickets
- Change and cancellation options

Use this when:
- User needs to review their booking
- Checking order status
- Before making changes or cancellations
- Retrieving booking reference for airline website

Returns order details in specified format (JSON or Markdown).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover key behavioral traits (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true), but the description adds valuable context by specifying what details are retrieved (e.g., 'Documents and tickets', 'Change and cancellation options') and mentioning the return format ('JSON or Markdown'), enhancing understanding beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points for fetched details and a clear 'Use this when:' section, all in a compact format. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (retrieving flight order details), the description is complete: it covers purpose, usage guidelines, and behavioral context. With annotations providing safety and idempotency info, and an output schema handling return values, no critical gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description does not explain the single parameter (likely an order ID or reference). However, with only one parameter and high annotation coverage (e.g., openWorldHint suggests it queries existing data), the baseline is 3 as the schema must carry the burden, and the description adds no parameter-specific information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Retrieve complete details') and resource ('existing flight order'), distinguishing it from siblings like duffel_create_order (creation) and duffel_get_offer (offers). It provides a comprehensive list of what details are fetched, making the purpose explicit and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a dedicated 'Use this when:' section with four explicit scenarios (e.g., 'User needs to review their booking', 'Before making changes or cancellations'), providing clear guidance on when to use this tool versus alternatives like duffel_create_order or duffel_search_flights.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

duffel_list_airportsA
Read-onlyIdempotent
List airports with optional country filter.

This tool retrieves a paginated list of airports. Results can be filtered by country
using ISO 3166-1 alpha-2 country codes (e.g., 'US', 'GB', 'FR').

Use this when:
- Exploring available airports
- Getting airports in a specific country
- Building airport selection lists

Note: For finding a specific airport, use duffel_search_airports instead.

Returns airports in specified format (JSON or Markdown).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, open-world, idempotent, and non-destructive properties. The description adds valuable behavioral context about pagination, country filtering format (ISO 3166-1 alpha-2 codes), and return format options (JSON or Markdown), enhancing understanding beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured with a clear opening statement, bulleted usage guidelines, explicit alternative tool mention, and return format note. Every sentence adds value with zero wasted words, making it highly efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, rich annotations covering safety properties, and the presence of an output schema (which handles return value documentation), the description provides complete contextual coverage including purpose, usage scenarios, parameter semantics, behavioral details, and sibling differentiation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage for the single parameter, the description fully compensates by explaining the country filter parameter's purpose, format (ISO 3166-1 alpha-2 codes), and providing examples ('US', 'GB', 'FR'), adding substantial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'retrieves' and resource 'paginated list of airports' with specific filtering capability. It explicitly distinguishes from sibling tool duffel_search_airports, making the purpose distinct and well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use this when' scenarios (exploring airports, country-specific lists, building selection lists) and explicitly names when NOT to use it ('For finding a specific airport, use duffel_search_airports instead'), offering complete guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

duffel_search_airportsA
Read-onlyIdempotent
Search for airports by name, city, or IATA code.

This tool helps users find correct airport codes for flight searches by:
- Searching airport names (e.g., "Heathrow", "Charles de Gaulle")
- Searching city names (e.g., "London", "Paris")
- Validating IATA codes (e.g., "LHR", "CDG")

Results include:
- Airport name and IATA code
- City and country information
- GPS coordinates
- Time zone

Use this when:
- User provides city/airport names instead of codes
- Verifying airport codes before search
- Finding all airports in a city
- User unsure of exact airport code

Returns matching airports in specified format (JSON or Markdown).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable context beyond annotations by detailing what results are included (airport name, IATA code, city/country info, GPS coordinates, time zone) and specifying return format options (JSON or Markdown). Annotations already cover read-only, open-world, idempotent, and non-destructive traits, so the description appropriately supplements with practical behavioral details without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, search methods, results, usage guidelines, return format) and every sentence adds value. It's front-loaded with the core purpose and efficiently organized without redundant information, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, rich annotations, and presence of an output schema, the description provides complete contextual information. It covers purpose, usage scenarios, result details, and format options, leaving no significant gaps for an AI agent to understand and invoke the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage for the single parameter, the description partially compensates by explaining the search capabilities (by name, city, or IATA code) and providing examples. However, it doesn't detail the parameter's structure, required fields, or validation rules, leaving gaps in parameter understanding despite the added semantic context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('search for airports by name, city, or IATA code') and distinguishes it from sibling tools like duffel_list_airports by emphasizing search functionality rather than listing. It explicitly mentions what resources it operates on (airports) and how it helps users find correct airport codes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool through a dedicated 'Use this when:' section with four specific scenarios (e.g., 'User provides city/airport names instead of codes', 'Verifying airport codes before search'). It clearly differentiates use cases from potential alternatives without being misleading.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

duffel_search_flightsA
Read-only
Search for available flights based on journey requirements.

This tool creates an offer request and returns available flight options with pricing,
schedules, and airline information. Each offer includes:
- Total price and currency
- Flight segments with timings
- Airline and aircraft details
- Cabin class and baggage allowance
- Offer ID for booking

Use this when users want to:
- Find flights between destinations
- Compare prices and schedules
- Check availability for specific dates
- Get flight options before booking

Important notes:
- Offers expire after 15-30 minutes (check expires_at)
- Use passenger age instead of type for better accuracy
- Round trips require 2 slices (outbound + return)
- Direct flights: set max_connections=0

Returns flight offers in specified format (JSON or Markdown summary).
ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it notes that offers expire after 15-30 minutes (important for timing), recommends using passenger age for accuracy, explains how to handle round trips and direct flights, and mentions the return format options. While annotations cover read-only and non-destructive aspects, the description enriches this with operational details without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by bullet points for offer details, usage scenarios, and important notes. Every sentence adds value without redundancy, making it efficient and easy to scan for key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is largely complete: it covers purpose, usage, behavioral nuances, and output format. With an output schema present, it appropriately omits detailed return value explanations. However, the low schema description coverage (0%) means parameter semantics are not fully addressed, leaving a minor gap in overall context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter documentation. It implicitly references parameters like destinations, dates, max_connections, and passenger age through usage examples and notes, but does not explicitly list or define all parameters. This provides some semantic context but falls short of fully documenting the input schema, aligning with the baseline expectation when schema coverage is low.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Search for available flights'), identifies the resource ('based on journey requirements'), and distinguishes it from siblings like duffel_create_order (booking) and duffel_get_offer (retrieving specific offers). It explicitly mentions creating an offer request and returning flight options with detailed components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('when users want to: Find flights between destinations, Compare prices and schedules, Check availability for specific dates, Get flight options before booking'), which clearly differentiates it from sibling tools like duffel_create_order for booking or duffel_get_offer for retrieving specific offers. It also includes practical tips like using passenger age and handling round trips.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap. The tools cover specific actions like creating orders, retrieving offers/orders, listing/searching airports, and searching flights, all with well-defined boundaries. An agent can easily distinguish between them based on their unique functions.

Naming Consistency5/5

All tool names follow a consistent 'duffel_verb_noun' pattern (e.g., duffel_create_order, duffel_get_offer, duffel_search_flights). This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style.

Tool Count5/5

With 6 tools, the server is well-scoped for flight booking and search functionality. Each tool serves a distinct and necessary role in the workflow, from searching flights and airports to managing orders, without being overly sparse or bloated.

Completeness4/5

The tool set covers core flight booking operations comprehensively, including search, retrieval, and creation. However, there are minor gaps such as the absence of tools for updating or canceling orders, which could limit full lifecycle management, though agents might work around this by using existing tools for status checks.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FortripEngineering/duffel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server