Ride-Hailing MCP server (beta)
Connect your AI assistant to your company's Cabify account to read journeys, spend and employees.
If your company uses an AI assistant, you can connect it to your Cabify account through our Model Context Protocol (MCP) server. The assistant can then answer questions such as "how is Ana's ride going?", "how much would a ride from the office to the airport cost?" or "how much did we spend in June, by cost centre?" with your company's own data.
There is nothing to install. The server is part of the Ride-Hailing API, and you connect with the same credentials you use for the rest of the API.
BetaThe MCP server is in beta. It only reads data, and it is available in the sandbox environment only. Its tools and their answers may change while it is in beta.
Connecting
Connecting takes four steps. The first three are the ones you follow for the rest of the API: if you already have a valid sandbox access token, go straight to step 4.
1. Choose the environment
Everything that follows, from the credentials to the endpoint, belongs to one environment.
| Environment | MCP endpoint | Access token endpoint |
|---|---|---|
| Sandbox | https://cabify-sandbox.com/mcp | https://cabify-sandbox.com/auth/api/authorization |
| Production | Not available yet |
The server runs on the same host as the rest of the API. It speaks MCP over the Streamable HTTP transport, so it only answers POST.
Sandbox has its own data, separate from production: your assistant only sees the employees, journeys and sales you created there. See Sandbox environment.
2. Get your API credentials
You need an integration for the environment you chose: an OAuth UUID and a Secret. Admin users create them in the Integrations section of the Cabify web app. If you don't have one yet, follow Get your API key. An integration created in one environment doesn't work in the other.
Your assistant sees your whole companyAn access token has the same access rights as an admin user in your company. Anyone who can use an assistant configured with it can read your company's journeys, spend and employees. Share that assistant only with people who should see that data.
3. Get an access token
The server doesn't accept the OAuth UUID and Secret directly. Exchange them for an access token, as for any other API call:
curl -X POST -d "grant_type=client_credentials&client_id=OAUTH_UUID&client_secret=SECRET" \
https://cabify-sandbox.com/auth/api/authorizationThe parameter is called client_id because the OAuth2 standard names it so, but it takes your integration's OAuth UUID, not your Cabify account's client_id. See Get your Access Token.
The response carries the token in access_token:
{
"token_type": "Bearer",
"expires_in": 2591999,
"access_token": "1Lex4yzYz0M1NoMa-kfE1Uj3BdDd18"
}Keep it in an environment variable named after its environment, which is what the commands in step 4 read:
export CABIFY_RIDE_HAILING_SANDBOX_TOKEN="1Lex4yzYz0M1NoMa-kfE1Uj3BdDd18"The token expires after expires_in seconds, about 30 days. Your assistant can't renew it: when it expires, the server answers 401, and most assistants show the server as failed or disconnected. Get a new token as above and update it in your assistant's configuration.
4. Add the server to your assistant
Add one server per environment, named after it.
With Claude Code:
claude mcp add --transport http cabify-ride-hailing-sandbox https://cabify-sandbox.com/mcp \
--header "Authorization: Bearer ${CABIFY_RIDE_HAILING_SANDBOX_TOKEN}"With any client that reads a JSON configuration, such as Cursor:
{
"mcpServers": {
"cabify-ride-hailing-sandbox": {
"url": "https://cabify-sandbox.com/mcp",
"headers": {
"Authorization": "Bearer <your-sandbox-access-token>"
}
}
}
}Why one server per environment:
- You always know which environment answered. Assistants tell tools apart by the server they belong to, so every call names its environment.
- The host and the token change together. You can't end up with a sandbox token on the production host, or read one environment while believing it is the other.
- Each token expires on its own, so renewing one never breaks the other.
To check that it works, ask your assistant something like "how many active employees do we have in sandbox?". If it can't reach the server, call the endpoint directly. This request should answer with the server's name, cabify-ride-hailing, and the protocol version:
curl -X POST https://cabify-sandbox.com/mcp \
-H "Authorization: Bearer ${CABIFY_RIDE_HAILING_SANDBOX_TOKEN}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'A 401 means the token is missing, wrong or expired, or that it belongs to the other environment: get a new one (step 3). A 403 means the token is valid but can't use the Ride-Hailing API.
What your assistant can do
Every tool works on the company that owns the access token. It only ever sees that company's data, and you never pass a company or client id.
Journeys
| Tool | What it does | Ask, for example |
|---|---|---|
get_journey_state | How a journey is going right now: its state, the driver's name, the car and where the car is. | "How is Ana's ride going?", "Has the car arrived?" |
get_journey | A journey's stops, scheduled time, price and how it ended. | "Has this journey finished?", "How much did it cost?" |
estimate_journey | The car categories available for a ride, with their price, how long the car takes to arrive, and the ride's distance and duration. It books nothing. | "How much would a ride from the office to the airport cost?" |
get_hub | Whether a place is in a hub, such as an airport or a train station, and its meeting points, with directions. | "Where do I meet the driver at the airport?" |
Spend
| Tool | What it does | Ask, for example |
|---|---|---|
list_sales | Your company's sales between two days: what Cabify charged for each journey, and its cost centre. | "How much did we spend in June, by cost centre?" |
list_user_sales | One employee's sales between two days. | "How much did Ana spend in June?" |
get_journey_sales | What Cabify charged for one journey, and its cost centre. | "How much were we charged for this ride?" |
list_labels | Your company's labels, which employees pick when they book and you use as cost centres. | "Which cost centres do we have?" |
A journey's sale shows up once the journey is closed: about 10 minutes after it ends in sandbox, and about 2 hours in production. See Journey Sales. Amounts are in cents of their currency (in currency units for CLP), and the assistant is told never to add up amounts in different currencies.
Employees
| Tool | What it does | Ask, for example |
|---|---|---|
find_users | Finds employees by name, surname or email. | "Estimate a ride for Ana García" |
get_user_by_email | An employee, by their email. | "Who is [email protected]?" |
get_user | An employee, by their id. | "Who requested this journey?" |
list_users | Your company's employees, a page at a time. | "How many active employees do we have?" |
find_users returns up to 20 employees and looks among at most 1,000. In a bigger company, the assistant may need the employee's email.
Places are coordinates
The API works with coordinates, [latitude, longitude], and has no tool that turns an address into coordinates. The server tells your assistant never to invent them: it has to get them with its own tools, or ask you for a more precise place. It is also told to show you a Google Maps link with the stops in order before it estimates a ride, and to wait for your OK. Check that link: Cabify only sees the coordinates, never the address you asked for.
In sandbox, the simulated drivers only work in central Madrid. To follow a journey from start to end, book it with the REST API with its pickup in that area. See Simulated drivers.
What it cannot do
- Book, cancel or change anything. The server only reads. Booking and cancelling journeys, and managing employees, labels and Flexible Rides, stay on the REST API.
- Read Flexible Rides. There are no Flexible Rides tools yet.
- Search this documentation. The server reads your account, not these docs. To give your assistant the docs, point it to llms.txt, as explained in Welcome.
- Sign you in, or renew its token. The server doesn't offer MCP's sign-in (OAuth) flow. Your assistant has to let you set an
Authorizationheader for the server, and you paste a new token about every 30 days (step 3).
What the tools return
Whatever a tool returns becomes part of your assistant's conversation. It reaches the AI provider behind your assistant and is handled under that provider's terms. Choose the assistant, and its data settings, with that in mind.
The tools return what the assistant needs to answer, and leave out what it doesn't:
| Tools | Return | Leave out |
|---|---|---|
Employees: find_users, get_user, get_user_by_email, list_users | id, name, surname, email, language, employee code, default cost centre, whether they are disabled, and whether they can book for others | phone number, the addresses receipts are copied to, whether they are an admin, and their permission group |
get_journey_state | the driver's name, the car's model, colour and plate, and where the car is now | the driver's phone number and the route |
get_journey | the stops (address, coordinates, the instructions for the driver and when they were reached), each stop contact's name, the requester's id, the price, and the public link to follow the journey | the stop contacts' phone numbers |
Spend: list_sales, list_user_sales, get_journey_sales | each sale's amount, taxes, date and cost centre, with the journey's pickup and drop-off address and coordinates | the stops' contacts |
estimate_journey | each car category's price, arrival time, distance and duration | the route |
list_labels | each label's id, slug, name, description and whether it is active |
Journeys and sales tell where your employees went, and when.
Good to know
- One message per request. The server answers one JSON-RPC message per request and rejects batches. It keeps no session and never sends messages on its own, so
GETandDELETEon the endpoint answer405. - Protocol versions. It supports MCP versions
2025-11-25,2025-06-18and2025-03-26. A request with anotherMCP-Protocol-Versiongets a400. A client that tries a newer version first, as Claude Code does, then falls back on its own. - Rate limit. The MCP endpoint has its own rate limit, apart from the rest of the API. Past it, the server answers
429, and your assistant is told to wait and retry. - Errors. A tool that fails answers with an error result rather than an HTTP error, which is how MCP reports it. The result has an
errorcategory and a message that tells the assistant what to do next:invalid_argument: an argument is wrong, and the message says which.not_found: it doesn't exist, or isn't your company's.internal: something failed on Cabify's side. The assistant is told to retry once, then to tell you.
- Expired token. A missing, invalid or expired token gets a
401with aWWW-Authenticateheader and a body that explains how to get a new one.
Updated about 7 hours ago
