MCP-сервер TAP.
Техническая документация

1. Назначение

Сервер предоставляет клиентам Model Context Protocol доступ к каталогу действующих предложений локальных организаций Республики Казахстан: салоны красоты, стоматологические и медицинские клиники, косметология, массаж, SPA. По каждой услуге передаются цена, размер скидки, срок действия предложения и число свободных мест.

Без персонального доступа сервер работает только на чтение: состав сведений совпадает с опубликованным на сайте thetap.live, запись оформляется на сайте. Запись из чата доступна только владельцу персонального доступа, см. раздел 5.5. Оплата средствами сервера не производится.

2. Точка доступа

POST https://thetap.live/mcp
ТранспортStreamable HTTP, без канала Server-Sent Events
Формат обменаJSON-RPC 2.0, кодировка UTF-8
Версия протокола2025-06-18; принимаются также 2025-03-26 и 2024-11-05
Авторизацияне применяется, доступ анонимный
Управление сессиейне применяется, состояние между запросами не сохраняется
Заголовок запросаContent-Type: application/json

Метод GET возвращает код 405: канал «сервер — клиент» не открывается. Метод OPTIONS возвращает код 204. Кросс-доменные запросы разрешены для всех источников; передача учётных данных не предусмотрена.

3. Порядок подключения

3.1. Claude

  1. Раздел настроек Connectors, действие Add custom connector.
  2. Поле Name — значение TAP.
  3. Поле Remote MCP server URL — адрес, указанный в разделе 2.
  4. Поля OAuth Client ID и OAuth Client Secret не заполняются.
  5. Подтверждение действием Add.

3.2. Иные клиенты

Поддерживается любой клиент MCP, реализующий транспорт Streamable HTTP. Параметры авторизации не заполняются.

3.3. Проверка доступности

curl -s -X POST https://thetap.live/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Методы протокола

МетодВозвращаемый результат
initializeВерсия протокола, перечень возможностей, сведения о сервере, инструкции для клиентской модели
tools/listПеречень инструментов со схемами входных параметров
tools/callРезультат вызова инструмента, см. раздел 5
pingПустой результат, подтверждение доступности
resources/list, prompts/listПустые перечни; соответствующие возможности сервером не объявляются

Уведомления, то есть сообщения без поля id, обрабатываются без формирования ответа; возвращается код 202. Передача нескольких сообщений в одном запросе поддерживается для совместимости с клиентами предшествующих версий протокола.

5. Инструменты

Все инструменты, кроме prepare_booking и create_booking, имеют признак readOnlyHint. Результат вызова передаётся в поле content[0].text в виде строки, содержащей объект JSON.

5.1. search_offers

Поиск действующих предложений в каталоге.

ПараметрТипОбязательностьОписание
querystringнетНаименование услуги. Принимаются формулировки на русском, английском и частично на казахском языке
categorystringнетКатегория каталога, см. list_categories
citystringнетНаселённый пункт
regionstringнетСтрана: kz — Казахстан, us — США (Калифорния), all — обе. Если не указана, определяется по city или месту в запросе, иначе kz
max_priceintegerнетВерхняя граница цены в валюте страны: тенге для kz, доллары для us
limitintegerнетКоличество записей, от 1 до 20. Значение по умолчанию — 10

Запрос

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search_offers",
           "arguments":{"query":"маникюр","city":"Алматы","max_price":8000}}}

Результат

{
  "found": 2,
  "offers": [
    {
      "id": "o113",
      "title": "Маникюр + укрепление",
      "business": "Pilochka Nail Bar",
      "price": 6999,
      "old_price": 10000,
      "discount": 30,
      "currency": "KZT",
      "category": "Маникюр",
      "city": "Алматы",
      "url": "https://thetap.live/offer/113?src=mcp"
    }
  ]
}

5.2. get_offer

Получение полного описания предложения.

ПараметрТипОбязательностьОписание
idstringдаИдентификатор предложения из результатов поиска, например o113

При отсутствии предложения либо истечении срока его действия возвращается результат с признаком isError.

5.3. list_categories

Перечень категорий каталога с указанием числа действующих предложений.

ПараметрТипОбязательностьОписание
categorystringнетПри указании возвращается перечень подкатегорий внутри заданной категории

5.4. search и fetch

Инструменты передают те же сведения, что search_offers и get_offer, в структуре, применяемой режимом исследования ChatGPT. Инструмент search принимает обязательный параметр query и возвращает объект {"results":[{"id","title","url"}]}. Инструмент fetch принимает обязательный параметр id и возвращает объект {"id","title","text","url","metadata"}.

5.5. Запись из чата

Доступна по карточкам с полем chat_booking: true (календарь салона в zapis.kz). Услугу, мастера, дату и время выбирает пользователь; сервер не подбирает их сам.

ИнструментПараметрыРезультат
get_booking_optionsoffer_idСалон, услуга с ценой из прайса салона, мастера этой услуги
get_available_datesoffer_id, service_id, master_idСвободные даты на две недели
get_available_timesте же и dateСвободное время на дату, пояс UTC+5
prepare_bookingте же и timeЖивая проверка времени, удержание на 5 минут, данные для показа и confirmation_token. Брони не создаёт
create_bookingconfirmation_token, user_confirmedПовторная живая проверка и бронь. При status: confirmed: услуга, салон, мастер, дата, время, идентификаторы, manage_url

Первые три инструмента доступны без авторизации. prepare_booking и create_booking требуют персонального доступа, который выдаёт TAP: ключ передаётся заголовком Authorization: Bearer или параметром grant в адресе сервера. Доступ привязан к имени и телефону его владельца, клиент их не передаёт. Без ключа эти инструменты не показываются в tools/list.

Повтор create_booking с тем же токеном возвращает ту же бронь. Об успехе можно сообщать только при status: confirmed. При status: unknown исход неизвестен, повторять попытку нельзя.

6. Формат объекта предложения

ПолеТипОписание
idstringИдентификатор предложения
titlestringНаименование услуги
businessstringНаименование организации
priceintegerЦена по предложению, в валюте currency
old_priceintegerЦена без скидки, в валюте currency
discountintegerРазмер скидки, процентов
currencystringКод валюты: KZT или USD
countrystringСтрана: KZ или US
categorystringПуть по каталогу, уровни разделены символом «/»
citystringНаселённый пункт
addressstringАдрес места оказания услуги
descriptionstringОписание услуги, не более 600 символов
ratingstringРейтинг организации
reviewsintegerКоличество отзывов
verifiedbooleanПризнак проверенной организации
spots_leftintegerЧисло свободных мест
expires_atstringДата и время окончания действия предложения
bookingstringtap — запись через сайт TAP; external — запись непосредственно в организации
urlstringАдрес страницы предложения

Поля, не имеющие значения, в составе ответа отсутствуют. В выдачу включаются исключительно действующие предложения: не отключённые организацией и не истёкшие по сроку.

7. Лимиты

ПоказательЗначение
Запросов в минуту с одного клиента30
Запросов в сутки с одного клиента300
Записей в результате одного вызоване более 20
Размер тела запросане более 256 КБ
Стоимость доступане взимается

При превышении лимита возвращается код 429 и заголовок Retry-After.

8. Коды ошибок

КодУсловие возникновения
-32700Тело запроса не является корректным документом JSON
-32600Сообщение не соответствует спецификации JSON-RPC 2.0
-32601Запрошенный метод не поддерживается
-32602Инструмент не существует либо его наименование не указано
-32000Превышен лимит обращений

Ошибки выполнения инструмента передаются в составе результата с признаком isError и текстовым описанием, без формирования ошибки уровня JSON-RPC. Сведения о внутренних сбоях сервера наружу не передаются.

9. Состав и обработка данных

Условия обработки данных установлены документами: политика конфиденциальности, публичная оферта.

10. Ограничения функциональности

Средствами сервера не выполняются:

11. Контактные данные

Адрес для обращений по вопросам работы сервера: hello@thetap.live

TAP MCP Server.
Technical Documentation

1. Purpose

The server grants Model Context Protocol clients access to a catalog of live offers from local organisations of the Republic of Kazakhstan: beauty salons, dental and medical clinics, cosmetology, massage, spa. Each service is supplied with its price, discount rate, offer expiry date and the number of remaining spots.

Without personal access the server is read-only: the data supplied is identical to the data published on thetap.live, and booking is completed on the website. Booking from chat is available only to a holder of personal access, see section 5.5. The server does not process payments.

2. Endpoint

POST https://thetap.live/mcp
TransportStreamable HTTP, no Server-Sent Events channel
Exchange formatJSON-RPC 2.0, UTF-8 encoding
Protocol version2025-06-18; 2025-03-26 and 2024-11-05 are also accepted
Authenticationnot applied, access is anonymous
Session handlingnot applied, no state is retained between requests
Request headerContent-Type: application/json

The GET method returns code 405: no server-to-client channel is opened. The OPTIONS method returns code 204. Cross-origin requests are permitted from any origin; credential transfer is not provided for.

3. Connection procedure

3.1. Claude

  1. Settings section Connectors, action Add custom connector.
  2. Field Name — value TAP.
  3. Field Remote MCP server URL — the address stated in section 2.
  4. Fields OAuth Client ID and OAuth Client Secret are left blank.
  5. Confirmation by the Add action.

3.2. Other clients

Any MCP client implementing the Streamable HTTP transport is supported. Authentication parameters are left blank.

3.3. Availability check

curl -s -X POST https://thetap.live/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Protocol methods

MethodResult returned
initializeProtocol version, capability list, server information, instructions for the client model
tools/listList of tools with input parameter schemas
tools/callResult of a tool invocation, see section 5
pingEmpty result, availability confirmation
resources/list, prompts/listEmpty lists; the corresponding capabilities are not declared by the server

Notifications, that is messages without an id field, are processed without forming a response; code 202 is returned. Transmission of several messages in a single request is supported for compatibility with clients of preceding protocol versions.

5. Tools

All tools except prepare_booking and create_booking carry the readOnlyHint attribute. The invocation result is supplied in the content[0].text field as a string containing a JSON object.

5.1. search_offers

Search of live offers in the catalog.

ParameterTypeRequiredDescription
querystringnoService name. Wordings in Russian, English and partly Kazakh are accepted
categorystringnoCatalog category, see list_categories
citystringnoLocality
regionstringnoCountry: kz — Kazakhstan, us — USA (California), all — both. If omitted, inferred from city or a place in the query, otherwise kz
max_priceintegernoUpper price bound in the country currency: tenge for kz, dollars for us
limitintegernoNumber of records, 1 to 20. Default value — 10

Request

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search_offers",
           "arguments":{"query":"manicure","city":"Almaty","max_price":8000}}}

Result

{
  "found": 2,
  "offers": [
    {
      "id": "o113",
      "title": "Маникюр + укрепление",
      "business": "Pilochka Nail Bar",
      "price": 6999,
      "old_price": 10000,
      "discount": 30,
      "currency": "KZT",
      "category": "Маникюр",
      "city": "Алматы",
      "url": "https://thetap.live/offer/113?src=mcp"
    }
  ]
}

Catalog content is held in Russian; queries in other languages are matched against it.

5.2. get_offer

Retrieval of the full offer description.

ParameterTypeRequiredDescription
idstringyesOffer identifier from search results, for example o113

Where the offer does not exist or its validity period has elapsed, a result carrying the isError attribute is returned.

5.3. list_categories

List of catalog categories stating the number of live offers.

ParameterTypeRequiredDescription
categorystringnoWhere supplied, the list of subcategories within the given category is returned

5.4. search and fetch

These tools supply the same data as search_offers and get_offer in the structure used by ChatGPT deep research. The search tool takes a mandatory query parameter and returns the object {"results":[{"id","title","url"}]}. The fetch tool takes a mandatory id parameter and returns the object {"id","title","text","url","metadata"}.

5.5. Booking from chat

Available for offers with chat_booking: true (the salon's calendar is on zapis.kz). The user chooses the service, master, date and time; the server does not pick them.

ToolParametersResult
get_booking_optionsoffer_idSalon, service with the price from the salon's price list, masters for that service
get_available_datesoffer_id, service_id, master_idAvailable dates for two weeks
get_available_timesthe same plus dateAvailable times for the date, UTC+5
prepare_bookingthe same plus timeLive availability check, a 5-minute hold, details to show the user and a confirmation_token. Creates no booking
create_bookingconfirmation_token, user_confirmedA second live check and the booking. With status: confirmed: service, salon, master, date, time, identifiers, manage_url

The first three tools need no authorization. prepare_booking and create_booking require personal access issued by TAP: the key is sent in an Authorization: Bearer header or as the grant parameter of the server address. Access is bound to its holder's name and phone, which the client does not send. Without a key these tools are absent from tools/list.

Repeating create_booking with the same token returns the same booking. Report success only on status: confirmed. On status: unknown the outcome is unknown and the attempt must not be repeated.

6. Offer object format

FieldTypeDescription
idstringOffer identifier
titlestringService name
businessstringOrganisation name
priceintegerOffer price, in currency
old_priceintegerPrice before discount, in currency
discountintegerDiscount rate, per cent
currencystringCurrency code: KZT or USD
countrystringCountry: KZ or US
categorystringCatalog path, levels separated by “/”
citystringLocality
addressstringAddress where the service is provided
descriptionstringService description, 600 characters maximum
ratingstringOrganisation rating
reviewsintegerNumber of reviews
verifiedbooleanVerified organisation attribute
spots_leftintegerNumber of remaining spots
expires_atstringDate and time the offer ceases to be valid
bookingstringtap — booking through the TAP website; external — booking directly with the organisation
urlstringOffer page address

Fields holding no value are omitted from the response. Only live offers are included: those not disabled by the organisation and not elapsed by date.

7. Limits

ParameterValue
Requests per minute per client30
Requests per day per client300
Records per single invocation20 maximum
Request body size256 KB maximum
Access chargenone

Where a limit is exceeded, code 429 and the Retry-After header are returned.

8. Error codes

CodeCondition
-32700The request body is not a valid JSON document
-32600The message does not conform to the JSON-RPC 2.0 specification
-32601The requested method is not supported
-32602The tool does not exist or its name is not supplied
-32000The request limit has been exceeded

Tool execution errors are supplied within the result carrying the isError attribute and a textual description, without forming a JSON-RPC level error. Details of internal server failures are not disclosed.

9. Data scope and processing

Data processing terms are established by the following documents: privacy policy, public offer.

10. Functional restrictions

The server does not perform:

11. Contact details

Address for enquiries concerning operation of the server: hello@thetap.live