¶ Overview

The Rides MCP server accepts flexible location input through the LocationSpecification type. Both origin and destination fields use this type. The server resolves the location to a lat/lng coordinate before calling Uber’s Rides Demand Gateway.

---

¶ Providing Locations

At least one of the following fields must be set in each LocationSpecification:

¶ text_query (Recommended)

A natural language string describing the location. The MCP server passes this to Uber’s Maps API for geocoding.

{ "text_query": "SFO Airport" }
{ "text_query": "1 Market Street, San Francisco, CA" }
{ "text_query": "Times Square, New York" }

¶ point

An explicit latitude/longitude coordinate with a confidence level.

{
  "point": {
    "latitude": 37.6213,
    "longitude": -122.3790,
    "confidence": "HIGH"
  }
}

Confidence	When to use
HIGH	GPS-derived coordinate, accurate to street level
MEDIUM	Approximate coordinate (city-level, neighborhood centroid)
LOW	Very rough estimate; server may request clarification

¶ location_id + location_provider

An explicit location reference from a prior Uber location lookup. Use when you have a stable Uber location identifier.

{
  "location_id": "ChIJVVVVVVVVVVVRYVQEKJjFmgI",
  "location_provider": "uber"
}

¶ formatted_address

A structured street address string.

{ "formatted_address": "1 Market Street, San Francisco, CA 94105" }

---

¶ Combining Fields

You can provide multiple fields together. The server uses the most precise available input:

{
  "text_query": "SFO Airport Terminal 2",
  "point": { "latitude": 37.6213, "longitude": -122.3790, "confidence": "HIGH" }
}

---

¶ Handling Ambiguous Locations

If the text query matches multiple locations and the server cannot determine which one the user intends, it returns ERROR_CODE_LOCATION_AMBIGUOUS.

Example: "Springfield" matches multiple US cities.

When this error is returned, the AI agent must:

1. Ask the user to clarify which location they mean (e.g., “Did you mean Springfield, IL or Springfield, MO?”)
2. Retry the tool call with the clarified location

¶ 3-Iteration Limit

The AI agent must not loop more than 3 tool call iterations per user request when resolving location ambiguity. If the location cannot be resolved within 3 attempts, inform the user that you were unable to find their location and suggest they specify a full address.

---

¶ Handling Vague Locations

Some location queries are too vague to resolve to a single point. Examples:

• "a coffee shop" — no specific location
• "New York City" — too broad for a pickup point
• "near downtown" — relative reference with no anchor

For these queries, the AI agent should ask the user for a more specific address before calling the tool. Do not call get_estimates_between_two_locations with a vague origin or destination — it will return an error or an unhelpful result.

Recommended behavior:

• "Get me an Uber from downtown" → Ask: “Where in downtown would you like to be picked up? A street address or intersection would work.”
• "Coffee shop near Union Square" → Ask: “Which coffee shop? Or would you like me to use Union Square as the pickup point?”

---

¶ City-Specific Rules

Some cities have special location handling requirements:

• Airports: For airport pickups, the resolution may involve access point selection (terminal-level). Use the most specific text_query you have (e.g., "SFO Terminal 2 Departures" rather than just "SFO").
• Dense venues: For high-density venues like stadiums or convention centers, include the venue name in text_query so the server can apply zone-level routing.

---

¶ Location Resolution Flow

AI calls get_estimates_between_two_locations
    │
    ▼
MCP server resolves location
    │
    ├─ Resolved uniquely → returns estimates
    │
    └─ Ambiguous / not found → ERROR_CODE_LOCATION_AMBIGUOUS
           │
           ▼
       AI asks rider for clarification
           │
           ▼
       AI retries with clarified location (max 3 total attempts)