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.

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:

1. 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 to connections_find.
2. Search for trips Use connections_find with 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.
3. Present the search results Results include rich data such as available fares, station details, intermediate stops and (optionally) walking steps.
4. Check availability Use connections_vacancy once the traveller picks a connection and fare, to confirm the trip is still bookable and to get the most up-to-date price.
5. Optional — get the seat map Use get_seat_map if the carrier supports seat selection, and let the traveller choose.
6. Complete the sale Either generate a checkout URL with get_checkout_link and hand the traveller off to the Distribusion checkout page, or — if reservations are enabled for your account — hold and confirm the booking in-conversation with create_reservation and confirm_reservation.
7. 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

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

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.

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

Real-time trip data

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/list reflects 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_vacancy immediately before checkout or reservation — the price returned there is the authoritative one.