Developer portal

This is the Sorted Travel developer portal. Sign up is not required. Connect the public MCP server, read the documentation, and follow a quickstart.

• Quickstart
• API keys
• Rate limits
• Idempotency
• Errors
• Versioning
• Documentation

Quickstart

Integration is Model Context Protocol over Streamable HTTP. Point an MCP host at this URL. No OAuth handshake and no API key.

https://sorted.travel/mcp

Cursor

Add the server to mcp.json, then reload MCP tools.

{
  "mcpServers": {
    "sorted-travel": {
      "url": "https://sorted.travel/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http sorted-travel https://sorted.travel/mcp

Claude and ChatGPT

Add a custom connector / remote MCP server and paste https://sorted.travel/mcp. Machine-readable connection metadata lives in the MCP server card, the agentic resource catalog, and the Agent Skills index. Recommendation, place, and weather tools declare MCP Apps metadata (_meta.ui.resourceUri) pointing at ui://sorted/recommendations and ui://sorted/place so hosts can render the destination cards in conversation.

Then ask where to go from an airport, or what a named place is like. If you only have a city name, start with resolve_destination so the host gets a destination handle such as paris.

API keys

You do not create or manage API keys for Sorted Travel. The MCP server is public and read-only. There is no developer signup, no key dashboard, and no email gate before you integrate. If a host still asks for a credential, leave it blank.

Rate limits

Every MCP HTTP response includes IETF RateLimit-Policy, RateLimit, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers so agents can self-throttle. A public GET to /mcp (no API key) returns HTTP 200 with those headers. When a window is exhausted, the server returns 429 Too Many Requests with Retry-After set to the seconds remaining in that window. Read the remaining count and slow down before you hit a 429.

Idempotency

POST /mcp accepts an optional Idempotency-Key header. Generate one key per JSON-RPC call and reuse it if the network drops mid-request. The server replays the original response for 24 hours so a retry does not run the tool twice or consume another rate-limit token. Reusing a key with a different body returns 422. A concurrent retry while the first request is still running returns 409 with Retry-After.

Errors

Unknown /mcp paths return 404 with application/problem+json (RFC 9457). The body includes a machine-readable error code, a message, and a hint that points at this page, /openapi.json, and POST /mcp. Do not retry a 404 against the same path.

Versioning

The MCP URL stays https://sorted.travel/mcp. There is no /v1/ path prefix. The tool and JSON contract is SemVer 1.0.0, published identically as OpenAPI info.version, the MCP server card version, the API-Version response header, and GET /mcp contractVersion.

Major means a stable tool or field is removed, renamed, or changed in meaning. Minor means additive tools or fields. Patch means documentation or spec-only corrections. You may send API-Version: 1.0.0 to pin the contract. Unknown values are ignored; the API-Version response header reports the version actually served.

Additive changes ship without notice. A major bump in API-Version is the signal that the previous contract is gone. There is no deprecation window.

Documentation

Use these tools for trip planning context. They do not search or book flights, hotels, or activities. Send travelers to the place_url, discover_url, or flights_url fields in the tool payload.

resolve_destination

Resolve a city, country, region, or airport onto live Sorted handles. Call this when you do not already have a destination handle or IATA code.

get_recommended_destinations

Rank destinations from a departure airport by month, weather, visa hassle, safety, budget, and interests.

get_destination_info

On-the-ground facts for one handle: brief, safety, currency, phone code, eSIM notes, and taxi apps.

get_destination_weather

Current weather, a 7-day forecast, monthly climate, and best months to visit.

Full destination URLs are https://sorted.travel/places/{handle}. If you only have a city, country, region, or airport name, call resolve_destination instead of inventing a handle. Human-oriented product copy is on About and llms.txt.

Machine-readable API documentation is published as OpenAPI 3.1 at /openapi.json.

The tools never invent destinations or prices.