REST API versioning
The agent REST API is documented at https://www.extralingo.com/api/v1 (OpenAPI version 1.0.0). The same endpoints also work under unversioned /api/* and remain supported. Breaking changes ship under a new major path (for example /api/v2) with at least 6 months notice before we remove old paths. MCP remains at POST /mcp on the site root.
Connection
- Endpoint:
https://www.extralingo.com/mcp- Transport:
- Streamable HTTP (JSON-RPC 2.0 at POST /mcp)
- MCP protocol versions:
2025-06-18, 2025-03-26- Server version:
3.0.1
Authentication
Read tools (search, catalogues, price quotes, load trip by id) need no token.
Write tools require OAuth 2.1: authorization code with PKCE S256, scopes trips, requests and bookings. Discover the protected resource metadata at /.well-known/oauth-protected-resource.
Tools
The list below is generated from the live MCP tool registry on this server.
| Tool | Description | Access |
|---|---|---|
| search_language_schools | Search and rank language schools. Returns school_id, url, indicative from-price, and reviews. Prices are not a booking quote; call calculate_trip_price before quoting a total. | Read-only |
| search_destinations | Search cities, countries, and school names. Use before search_language_schools to resolve place names to slugs. | Read-only |
| get_school_filters | Valid filter values for search_language_schools (languages, countries, cities, course types, and other facets). | Read-only |
| get_school | School briefing: profile, cancellation policy, reviews, image URLs, bookings_live flag, and optional hero image for chat UI. Requires school_id from search_language_schools. | Read-only |
| list_courses | Live course catalogue for a bookings_live school (course ids, weeks, prices). Use returned course ids inside save_trip configuration. | Read-only |
| list_starting_dates | Allowed course start dates (typically Mondays) for a school. Use startDate values in list_courses and configuration.startDate. | Read-only |
| list_accommodations | Accommodation groups for a school. Use group ids in save_trip configuration (accommodationGroupId). | Read-only |
| get_course_details | Details for one course id from list_courses (pricing rows, supplements, metadata). | Read-only |
| get_accommodation_details | One group from list_accommodations (group_id): type, room_types, meal/board options, distance, amenities, age and min-stay rules, and week prices for startDate and currency. Use after list_accommodations, before save_trip or calculate_trip_price, or to answer questions about one option. Week prices are indicative; call calculate_trip_price for a checkout total. | Read-only |
| calculate_trip_price | Live checkout quote for a configuration. Not a booking. Call before create_booking and before telling the student a final price. | Read-only |
| save_trip | Create or update a server-side trip draft. Returns trip_id, url, trip_url, and continue_url (/s/{id}) so the student can restore selections on Extralingo.com. Not a booking. Requires OAuth trips scope (Bearer token). | Creates a request / requires sign-in |
| get_trip | Load a saved trip by trip_id from save_trip. Returns continue_url for website handoff with configuration restored. | Read-only |
| email_trip | Email continue_url (/s/{id}) to the verified account inbox. Requires OAuth trips scope. Rate-limited. Not a booking; you can share continue_url without emailing. | Creates a request / requires sign-in |
| create_booking | Submit an unpaid booking for a bookings_live school (same path as the website Book now flow). The school still confirms availability; Extralingo emails the student; down payment is due within 5 days of school confirmation via Extralingo only. Never tell the user they are confirmed or paid. Requires OAuth bookings scope (Bearer token). Optional idempotency_key replays the same payload within 24 hours. | Creates a request / requires sign-in |
| request_quote | Ask the school for a personal quote when bookings_live is false or the student is not ready to book. Requires OAuth requests scope. Optional idempotency_key. | Creates a request / requires sign-in |
| request_discussion | Trip discussion: trip_id or school_id+configuration plus message. ask_school_question: question without a trip. request_quote: personal quote (comments) when not booking. School gets the config; Extralingo emails the verified account and coordinates replies. Returns kind, newBookingId, redirectUrl, message (not a booking). OAuth scope requests. Optional idempotency_key. | Creates a request / requires sign-in |
| ask_school_question | Send a question to the school without a full trip configuration. Requires OAuth requests scope. Optional idempotency_key. | Creates a request / requires sign-in |
How to connect
Use streamable HTTP against the endpoint above. Check your client’s current documentation for the exact config format.
- Claude (Connectors / remote MCP): add a custom connector with URL https://www.extralingo.com/mcp and complete OAuth when prompted for write tools.
- Cursor: add a streamable-http MCP server pointing at https://www.extralingo.com/mcp (see Cursor docs for mcp.json / MCP settings).
- Generic clients: POST JSON-RPC initialize, then tools/list and tools/call. Send Accept: application/json, text/event-stream and reuse Mcp-Session-Id from the initialize response.
Machine-readable resources
- Site index for agents
- Many public pages also respond to Accept: text/markdown.
- MCP server card
- Agent resource directory (ARD)
- AI catalog (same payload as ARD)
- OpenAPI 3.1 (REST)
- Authentication guide
Listed on
Contact
Questions about the MCP server or API integration:
