MCP Server
The Retailer API MCP Server is a Model Context Protocol server that exposes Distribusion's Retailer API as typed tools for AI agents. It is designed for server-to-server use: an agentic application connects to it over MCP Streamable HTTP, discovers the available tools, and calls them to search connections, check availability and price, answer carrier policy questions, retrieve real-time trip data, and take the traveller through to checkout or a reservation.
Please note that this is an enterprise API feature. Reach out to your Partnership Manager for more information about unlocking this and other advanced features.
Connecting
The server speaks MCP over the Streamable HTTP transport at https://api.distribusion.com/mcp/.
Authentication
Every request must carry an MCP Server API key in the api-key header. This key is specific to the MCP Server and the Retailer Agent, and is not your regular Retailer API key — see API Authentication. Contact your Partnership Manager to get one.
POST https://api.distribusion.com/mcp/
api-key: <RAPI_MCP_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream
The MCP Server resolves your MCP key to your retailer account server-side and calls the Retailer API on your behalf. Your Retailer API key is never transmitted to, or required by, the client. Every tool call is executed with your retailer's own credentials and permissions, so results, prices and carrier availability match what your Retailer API account is entitled to.
Situation | Response |
Missing, unknown or revoked |
|
Authentication service temporarily unavailable |
|
Key changes (including revocation) propagate within a few minutes. If you rotate a key, allow a short window before the old one stops working everywhere.
How to Use
The MCP Server is intended to be used in a Server-to-Server fashion, in other words, it is not intended to be used in personal AI applications, such as Claude Desktop, or Cursor. Instead, it is targeted towards Agentic application frameworks, such as LangChain, Google ADK, LlamaIndex, and many more.
For instance, using Langchain MCP Adapters, the connection would be setup like this:
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
client = MultiServerMCPClient(
{
"distribusion": {
"transport": "streamable_http",
"url": "https://api.distribusion.com/mcp/",
"headers": {
"api-key": "<RAPI_MCP_API_KEY>"
},
}
}
)
tools = await client.get_tools()
agent = create_react_agent("openai:gpt-4.1", tools)
response = await agent.ainvoke({"messages": "london to paris tonight"})
Here's an example of a simple agent using Google ADK:
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
root_agent = Agent(
name="retailer_agent",
description="An agent that searches for ground transportation trips",
model="gemini-2.5-flash",
instruction="""
Help the user find ground transportation trips.
Follow this flow:
1. Resolve the departure and arrival places to location codes using search_location
2. Search for trips using those location codes and a departure date using connections_find
3. Present the results to the user
4. Based on the user's selection:
4.1. Check the availability and current price using connections_vacancy
4.2. If the trip is available:
4.2.1. Get the seat map (if available) and ask the user for a seat selection using get_seat_map
4.2.2. Use get_checkout_link to create a checkout link and present it to the user
You may use the other tools available to answer additional questions.""",
tools=[
MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.distribusion.com/mcp/",
headers={"api-key": os.getenv("DISTRIBUSION_MCP_API_KEY", "")},
)
),
],
)
The MCP Server returns a set of server instructions during the MCP initialize handshake, describing the recommended tool flow and the guardrails around availability and checkout. Most frameworks surface these to the model automatically. If your framework does not, read them from the initialize result and prepend them to your system prompt — agents follow the flow far more reliably with them.
The above example showcases a simple system prompt that instructs the agent to use the MCP Server accordingly. More detailed instructions or different combinations may be written depending on the use case, but generally, agents should follow this flow, analogous to the standard API flow described in Flow Overview:
- Resolve the departure and arrival locations Use
search_location, which returns stations, cities and areas in one ranked result set. You can also pass IATA, UIC or geo-coordinates directly toconnections_find. - Search for trips Use
connections_findwith the resolved codes and a departure date. The search can be filtered by carrier or vehicle type, restricted to direct connections, narrowed to departure and return time windows, and can include a return trip and multiple passengers of different ages and discount cards, all in one call. - Present the search results Results include rich data such as available fares, station details, intermediate stops and (optionally) walking steps.
- Check availability Use
connections_vacancyonce the traveller picks a connection and fare, to confirm the trip is still bookable and to get the most up-to-date price. - Optional — get the seat map Use
get_seat_mapif the carrier supports seat selection, and let the traveller choose. - Complete the sale Either generate a checkout URL with
get_checkout_linkand hand the traveller off to the Distribusion checkout page, or — if reservations are enabled for your account — hold and confirm the booking in-conversation withcreate_reservationandconfirm_reservation. - Optional — answer additional questions At any point: carrier policies, terms and conditions, fare rules, cheaper travel dates, or the live status of a departure.
Note that the above setups are not time-aware. You may need to add a tool to the agent so that it knows the current date and time. Otherwise, the user must input exactly the travel dates, like “I want to travel on August 7th 2025” instead of “I want to travel next friday”.
You can use the MCP Inspector to explore the MCP Server interactively before wiring it into your agent.
Features
Location and carrier lookup
Tool | Description | Key Features |
| Preferred. Resolve any place name to a location code — station, city or area — in a single call, i.e. “Paddington”, “London” or “Berlin Airport”. | Returns each match with its |
| Search by carrier name (e.g., "Flixbus"). Used to filter search results to specific companies. | Finds 4-letter carrier codes (like |
| List the discount cards, loyalty programmes and promotional offers a carrier accepts. | Feeds the |
search_stations, search_cities and search_areas are still available but are deprecated in favour of search_location. They remain in the tool list for backwards compatibility; new integrations should not use them.
Trip search, pricing and checkout
Tool | Description | Key Features |
| Search for trips from location A to location B on a specified date. | Accepts station, city or area codes, IATA and UIC codes, or geo-coordinates with a radius — and can mix types (e.g. depart from an IATA code, arrive at a UIC train station). Supports one-way or return trips in one call, departure and return time windows, carrier and vehicle-type filters, direct-only search, per-passenger ages, discount cards, result sorting and optional walking steps. |
| Verify availability and price of a selected trip before checkout. | Mandatory step before checkout, to confirm the seat is still available and the price has not changed. Also returns the fare and passenger breakdown used by the checkout step. |
| View and select specific seats for a trip. | Check window vs. aisle availability and seat surcharges. Only carriers that support pre-assigned seating return a map; for the rest the tool responds cleanly that seat selection is unavailable rather than failing the turn. |
| Generate a booking URL for the selected trip. | Produces a secure Whitelabel checkout URL that carries the full selection — outbound and return legs, fare classes, passenger types, discount cards and chosen seats — plus the confirmed price, so the traveller lands on a pre-filled checkout. |
| Find the cheapest dates to travel. | Returns the minimum price per day across a date range for a route. Ideal for travellers with flexible schedules. |
Reservations
Where a checkout link is not the right hand-off — for example a counter agent or a fully conversational purchase — the server can hold and confirm a booking directly.
Tool | Description | Key Features |
| Create a reservation hold before payment. | Called after |
| Confirm a held reservation and issue the tickets. | Takes purchaser and passenger details plus a payment method: |
| Poll a reservation after confirmation. | Confirmation is asynchronous; poll until the booking reaches a final state before telling the traveller it succeeded. |
| Release a hold. | Use when the traveller aborts, or when payment fails before confirmation. |
Reservation tools are enabled per retailer. Once enabled, your account has its own limits — permitted carriers, maximum passengers per booking and maximum booking value. Until reservations are enabled, these tools still appear in the tool list and calls to them return an explicit “not allowed” response, so use get_checkout_link in the meantime. Talk to your Partnership Manager to have reservations enabled for your account.
Carrier policies and terms
Tool | Description | Key Features |
| Get carrier information: luggage policy, passenger types, general conditions. | Look up luggage limits, passenger requirements and general terms for a specific carrier. |
| Get information about a fare class for a carrier. | Explains what a specific fare includes — refundability, ticket validity, post-booking conditions and fare features (e.g. “Economy vs. Flex”). |
| Ask a natural-language question against the carrier Terms & Conditions knowledge base. | Semantic search over the full T&C corpus, optionally scoped to one carrier. Lets the agent answer specific questions — “can I take a bike?”, “what happens if I miss my bus?” — with grounded, carrier-accurate text instead of guessing. |
Real-time trip data
Tool | Description | Key Features |
| Get live delay and GPS data for one specific connection. | The tool to use for “where is my bus?” and “is my trip delayed?”. Matches the connection to the live feed and clearly distinguishes “running on time” from “no real-time data available for this carrier or trip”. |
| Get real-time trip updates for a carrier. | Delay and schedule-change feed across a carrier's rides, for broader monitoring use cases. |
| Get real-time vehicle positions for a carrier. | Live vehicle coordinates, suitable for driving a map view. |
Real-time data is only available for carriers that publish a live feed. For all other carriers these tools return an explicit “no data” result, which the agent should report as such rather than presenting it as an on-time confirmation.
Notes
- Server-to-server only. Your MCP key authenticates your retailer account, not an end user. Keep it on your backend and never ship it to a browser, a mobile app or an end-user desktop MCP client.
- Tool availability varies by account. The tool list returned by
tools/listreflects what your deployment exposes; reservation tools in particular are gated per retailer, as described above. Always drive your agent from the discovered tool list rather than a hard-coded one. - Agents are not time-aware by default. Give your agent a current-date tool, or resolve relative dates before calling the search tools.
- Search results are capped. Large searches are truncated to a workable number of connections; narrow the time window, carrier list or vehicle types rather than expecting an exhaustive result set.
- Prices move. Always re-check with
connections_vacancyimmediately before checkout or reservation — the price returned there is the authoritative one.
If a Retailer API capability you need is not yet exposed as a tool, raise it with your Partnership Manager.
On this page
- MCP Server