# agents.md reservations.ai is agent native. This file is the entry point for any AI agent, autonomous system, or agent framework looking to transact travel through our platform. Everything below is intended to be parsed by a machine as easily as read by a human. ## TL;DR for agents 1. Discover tools: `curl https://mcp.reservations.com/public/mcp -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'` 2. Search: call `search_properties` with destination, dates, guest count. No credentials required. 3. Quote: call `get_rates` to fetch live rates with all taxes and fees. 4. To reserve: register as an agent at `POST /agents/register` with a user principal and spend cap. Receive a bearer token and AEC pool balance. 5. Execute: call `create_booking` then `confirm_booking`. AEC refunds 100 percent on completion. No UI, no OAuth dances, no human in the loop required. ## Endpoints | Purpose | URL | Auth | | ------------------------ | ---------------------------------------------- | ------------------- | | Public MCP | `https://mcp.reservations.com/public/mcp` | None | | Authenticated MCP | `https://mcp.reservations.com/mcp` | Bearer token | | Agent registration | `https://mcp.reservations.com/agents/register` | None (machine only) | | Agent to agent (A2A 0.1) | `https://mcp.reservations.com/a2a` | Bearer token | | Capability manifest | `https://reservations.ai/manifest.json` | None | | REST API | `https://api.reservations.com` | Bearer token | | Sandbox | `https://sandbox.reservations.com` | Sandbox token | | Voice pilot lead form | `https://reservations.ai/voice-demo.html` | None | | Travel Assistant access | `https://reservations.ai/voice-demo.html` | Review required | ## Discovery surface | File | URL | | ----------------------------- | ------------------------------------------------------- | | llms.txt | `https://reservations.ai/llms.txt` | | llms-full.txt | `https://reservations.ai/llms-full.txt` | | agents.md | `https://reservations.ai/agents.md` | | agents.json | `https://reservations.ai/agents.json` | | manifest.json | `https://reservations.ai/manifest.json` | | .well-known/mcp.json | `https://reservations.ai/.well-known/mcp.json` | | .well-known/agent.json | `https://reservations.ai/.well-known/agent.json` | | .well-known/ucp | `https://reservations.ai/.well-known/ucp` | | .well-known/ai-plugin.json | `https://reservations.ai/.well-known/ai-plugin.json` | | openapi.yaml | `https://reservations.ai/openapi.yaml` | | sitemap_agentic_discovery.xml | `https://reservations.ai/sitemap_agentic_discovery.xml` | ## Protocol JSON RPC 2.0 over HTTP. Full MCP spec conformance (protocol version `2024-11-05`). REST endpoints follow OpenAPI 3.1. Agent to agent over A2A 0.1. ## Calling a tool Every tool is invoked with the `tools/call` method. Discovery (`tools/list`) and all read tools are public and need no credentials. Example, search hotels: ```bash curl https://mcp.reservations.com/public/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_properties", "arguments": { "destination": "Miami, FL", "check_in": "2026-07-10", "check_out": "2026-07-13", "adults": 2 } } }' ``` Authenticated tools (`create_booking`, `confirm_booking`, `cancel_booking`, `modify_booking`, `get_booking`) use the same shape against `https://mcp.reservations.com/mcp` with an `Authorization: Bearer ` header. ## Roadmap Hotels and lodging are live today. The following verticals are in active development on the same MCP surface and follow the same tool pattern (search, rates, availability, policy, two phase reservation). They are not callable yet. Tool names are provisional. | Vertical | Status | Planned tools | | ---------------------- | -------------- | ---------------------------------------------------------------------------- | | Flights | In development | `search_flights`, `get_fares`, `create_flight_order`, `confirm_flight_order` | | Car rentals | In development | `search_cars`, `get_car_rates`, `create_car_booking` | | Activities and tours | In development | `search_activities`, `get_activity_details`, `create_activity_booking` | | Show and event tickets | In development | `search_events`, `get_seat_map`, `create_ticket_order` | Call `tools/list` against the live endpoint to see exactly what is callable right now. Anything not returned by `tools/list` is not yet shipped. ## Tool catalog ### Public tools (no auth) | Tool | Purpose | AEC cost | | -------------------- | ---------------------------------------------- | -------- | | `tools/list` | Discover MCP schema | 0.10 | | `search_properties` | Query inventory by destination, dates, filters | 0.25 | | `get_rates` | Live rates with all taxes and fees | 0.50 | | `check_availability` | Real time availability with optional soft hold | 0.40 | | `get_policy` | Cancellation and change policy fetch | 0.15 | | `get_amenities` | Full amenity list, images, room types | 0.20 | ### Authenticated tools (Reservation Partner tier required) | Tool | Purpose | AEC cost | Refund on close | | ----------------- | -------------------------------------------------- | -------- | --------------- | | `create_booking` | Atomic reservation with payment tokenization | 2.00 | Yes | | `confirm_booking` | Two phase commit finalize | 1.00 | Yes | | `cancel_booking` | Cancel respecting property policy | 1.50 | No | | `get_booking` | Retrieve reservation record by confirmation number | 0.10 | No | | `modify_booking` | Change dates, guest count, room type | 1.00 | Partial | A typical closed reservation path consumes 3.40 AEC across 6 calls, all refunded on completion. Net infrastructure cost for a successful agent is zero. ## Agent registration Agents self register. No browser flow. ```bash curl -X POST https://mcp.reservations.com/agents/register \ -H "Content-Type: application/json" \ -d '{ "agent_id": "my-agent-1.0", "principal": "user_abc123", "pre_auth": { "max_usd": 2500, "scope": ["hotel"], "expires_at": "2026-12-31T00:00:00Z" }, "aec_pool": 500.00 }' ``` Response: ```json { "agent_token": "ra_live_...", "aec_balance": 500.0, "rate_limit": { "rpm": 1200 }, "manifest_url": "/manifest.json", "status": "active" } ``` The agent token is bound to: - `principal`: the user on whose behalf the agent acts - `pre_auth.max_usd`: the maximum cumulative spend during the token lifetime - `pre_auth.scope`: which product categories (hotel, car, activity) - `pre_auth.expires_at`: token expiration Exceed any bound, the token is revoked. No exceptions. ## Partner tiers | Tier | Cost | Auth | Tools | | ------------------- | ------------------------------------------------------------ | ------------------------- | ---------------------------------- | | Search Partner | Free | None | Public MCP (6 tools) | | Reservation Partner | Revenue share, eSign auto contract, 500 USD AEC pool minimum | Bearer | Public + authenticated | | Enterprise | Custom MSA + SOW | Bearer | All + white label | | Voice Pilot | Outcome based, pay per completed reservation, 0 USD upfront | Bearer (issued at deploy) | Voice + reservation reconciliation | See `https://reservations.ai/pricing.html` for the full rate card. ## Supported clients Native MCP support: - Claude Desktop, Claude Code, Claude mobile - ChatGPT (via apps surface) - Cursor (MCP server config) - Windsurf (Codeium MCP) Any client speaking JSON RPC 2.0 over HTTP can connect. Python and Node SDKs available for non MCP frameworks. ## Rate limits - Public MCP: 100 requests per hour per IP - Authenticated MCP (Reservation Partner): 1200 requests per minute per token - Enterprise: negotiated per contract Soft throttling kicks in at 80 percent of limit with a `Retry-After` header. Hard revocation on repeated breach patterns. ## Errors Standard JSON RPC 2.0 error envelope: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params", "data": { "field": "check_in", "reason": "Must be ISO 8601 date" } } } ``` Common codes: - `-32600` Invalid Request - `-32601` Method not found - `-32602` Invalid params - `-32603` Internal error - `4001` Rate limited (custom) - `4010` AEC balance insufficient (custom) - `4020` Token expired or revoked (custom) - `4030` Scope or spend cap exceeded (custom) ## Data freshness - Rates: cached up to 5 minutes. Real time on `get_rates` call. - Availability: real time on every `check_availability` call. Soft holds persist 10 minutes. - Property data: updated hourly. - Reservations: immediate consistency on authenticated endpoints. ## Voice channel for agents Beyond MCP, the same brain runs on voice. AI travel platforms that want to expose a voice reservation flow to their own users can route inbound voice over SIP to our voice agent, or whitelabel our outbound voice. See `https://reservations.ai/voice-demo.html` for the scoping form. ## Contact - Developer support: developers@reservations.ai - Partnerships: partnerships@reservations.ai - Security issues: security@reservations.ai ## Meta - Last updated: 2026-05-27 - MCP protocol version: 2024-11-05 - Platform version: 2.5.0 - Live since: 2024 - Parent organization: Lexyl Travel Technologies