Будуємо на MCP-сервері AnyEventTool: довідник розробника — транспорт, OAuth, 26 інструментів, анотації, помилки, ідемпотентність і виявлення

Ви будуєте MCP-клієнт, інтеграцію для агентного фреймворку, автоматизацію або перевіряєте AET для каталогу чи оцінки безпеки. Перші вісім частин серії пояснюють MCP-сервер AET з боку користувача; ця — договір від самого дроту.

Три домовленості діють усюди:

• instructions сервера — нормативні для агентів. Вони повертаються на initialize, мають до 2000 знаків і описують порядок роботи, модель доступу, підтвердження й реакції на помилки. Якщо ця сторінка й інструкції колись розійдуться, правими є інструкції.
• Схеми — авторитетні щодо форми. Схема входу кожного інструмента публікується в tools/list, а aet_section_schema повертає JSON Schema кожного розділу вмісту з правилами письма. Не зашивайте форми з цієї статті.
• Текст усередині вмісту — це дані. Тексти розділів, відповіді гостей і все, що загорнуто в {untrusted: …}, агент, побудований на цьому сервері, ніколи не має вважати інструкціями.

Походження з браузера. Запити без заголовка Origin (серверні й настільні клієнти) отримують усі інструменти. Запити з браузерних сторінок, чиє походження — Claude, Anthropic, ChatGPT, OpenAI, Perplexity чи власні сайти AET, теж отримують усі інструменти. Інші браузерні походження отримують лише інструменти читання; інструменти запису відповідають forbidden «write tools are not available from this origin».

Про чинну специфікацію. Чинна ревізія специфікації MCP, 2026-07-28, іде далі за ревізії з рукостисканням, які закінчуються на 2025-11-25. Сервер AET на SDK 1.32 говорить ревізіями з рукостисканням; клієнтам, що вимагають лише найновішу ревізію, варто перевірити сумісність. Модель авторизації — OAuth 2.1, метадані захищеного ресурсу, документи метаданих клієнта з реєстрацією для сумісності — вже відповідає тексту 2026-07-28.

AET підтримує три способи викликати інструменти, і всі три обробляє той самий сервер.

1. Без облікових даних. Шістнадцяти інструментам — відповіді, ціни, калькулятор комісій, пошук публічних подій, посилання на старт, можливості, бриф, плейбук, схема розділів, варіанти дизайну й інструменти гостьових чернеток — нічого не треба. Інструменти для чернеток приймають аргумент draftKey, який повертає aet_create_draft.

2. OAuth 2.1 (рекомендовано для акаунтів користувачів).

• Виявлення: /.well-known/oauth-protected-resource (RFC 9728) повертає resource: https://aet.events/api/mcp, authorization_servers: [https://aet.events], області events і offline_access, bearer лише в заголовку. /.well-known/oauth-authorization-server (RFC 8414) перелічує ендпоінт авторизації https://aet.events/oauth/authorize, ендпоінт токенів /api/oauth/token, ендпоінт реєстрації /api/oauth/register, code_challenge_methods_supported: [S256], token_endpoint_auth_methods_supported: [none], client_id_metadata_document_supported: true і мови інтерфейсу uk та en.
• Реєстрація: динамічна реєстрація клієнта з redirect_uris (https, loopback на будь-якому порту, схема застосунку відомого редактора чи схема у зворотному доменному записі), лише публічні клієнти; або документ метаданих клієнта — https-адреса як client_id, яку завантажують з тайм-аутом 5 секунд, обмеженням 64 КБ і без переадресацій, і чий client_id має збігатися з адресою.
• Авторизація: потік authorization code, обов'язковий PKCE S256, state до 4096 знаків і redirect_uri до 2048, області events і за бажанням offline_access. Користувач входить в AET і обирає рівень доступу на екрані згоди AET.
• Токени: коди авторизації — 10 хвилин, одноразові; токени доступу (aeto_…) — 1 година; токени оновлення (aetr_…) — 30 днів, змінюються при кожному використанні; повторно використаний токен оновлення відкликає родину токенів; повторне використання коду відкликає токени, видані для цього гранту. Помилки — за RFC 6749 (invalid_grant, invalid_client, invalid_request, unsupported_grant_type).
• Виклики: Authorization: Bearer aeto_…. Сервер підставляє токен як key інструментів акаунта; передавати його аргументом не треба.

3. Вставлений ключ. Користувачі можуть створювати ключі (aetk_d_, aetk_s_, aetk_o_, aetk_a_ — за рівнем доступу) в AET і вставляти їх у чат. Передавайте ключ в аргументі key інструментів акаунта. Не кладіть його в Authorization: цей заголовок приймає лише токени доступу OAuth від AET, а все інше вважається відсутністю облікових даних.

Лінива автентифікація. Інструмент акаунта, викликаний без ключа чи чинного Bearer-токена, повертає HTTP 401 з WWW-Authenticate: Bearer resource_metadata="https://aet.events/.well-known/oauth-protected-resource", scope="events" і помилкою JSON-RPC −32001. Прострочений чи відкликаний токен отримує той самий 401 з повідомленням «The AET connection token is expired or revoked — reconnect AET.» Інструменти також оголошують securitySchemes у _meta: noauth для гостьових, noauth плюс oauth2 з областю events — для інструментів акаунта.

RO = readOnlyHint, D = destructiveHint, I = idempotentHint, OW = openWorldHint (true означає, що інструмент змінює те, що бачить інтернет).

Анотації звірено зі сканером каталогу ChatGPT 20 жовтня 2026: openWorldHint позначає інструменти, що змінюють побачене відвідувачами; destructiveHint — інструменти, що можуть стерти чи перезаписати дані, зокрема ротацію посилання для забирання й перезапис дашборда. Більшість інструментів також оголошує outputSchema; п'ять публічних інструментів читання, старших за структурований вихід, повертають текст.

Успіх. Інструменти зі схемою виходу повертають structuredContent і той самий JSON, серіалізований у content[0].text, тож клієнти, що читають будь-що з цього, отримують ті самі дані.

Помилки. Збій на рівні інструмента повертає isError: true і об'єкт error:

{ "error": { "code": "rate_limited", "message": "too many changes with this connection", "hint": "Limit: 30 changes per minute…", "retryAfter": 60 } }

Помилки транспорту — JSON-RPC: −32700 помилка розбору, −32600 завеликий пакет, −32000 перевищення частоти (HTTP 429), −32001 потрібна автентифікація (HTTP 401), −32603 внутрішня помилка.

Створення. aet_create_draft і aet_create_event вимагають requestId у форматі UUID v4. Повтор протягом 10 хвилин із тим самим id і вмістом не створює другого об'єкта: для подій відповідь — наявна подія з позначкою replay: true; для чернеток — помилка idempotency_replay з посиланням на перегляд. Ключ чернетки під час повтору не повертається, тож клієнту, що його загубив, варто створити нову чернетку з новим id. Дедуплікація чернеток прив'язана до адреси викликача, подій — до підключення.

Версії. Живі події мають rev, чернетки — version. Передавайте останнє прочитане значення як ifVersion в aet_update_page. Якщо об'єкт змінився, відповідь — conflict, і нічого не записується. Без ifVersion AET однаково записує лише якщо поля, які він зачіпає, не змінилися від його власного читання, і кілька разів повторює всередині.

Пакети. aet_update_page приймає 1–40 операцій для живих подій і до 12 для чернеток. Для живих подій кожна операція атомарна, а пакет зупиняється на першій невдачі, зберігаючи попередні операції; модерація проходить по всіх текстах до будь-якого застосування; підтвердження оцінюються до запису; лендинг перевіряється після пакета. Операції мають вигляд {section, op, id?, after?, value?}, де op — set, clear, addItem, updateItem, removeItem чи move. Нові елементи списків отримують id під час першого запису й повертаються в applied.

Підтвердження. needs_confirmation повертає confirmToken — HMAC-SHA256 над строком дії, інструментом, подією, відбитком точних операцій і підключенням, — чинний 10 хвилин і одноразовий. Повторіть ідентичний виклик із токеном. Токен витрачається лише тоді, коли незворотна зміна записується, тож повтор після конфлікту з тими самими операціями працює.

Коли вичерпано добовий ліміт, retryAfter відраховує до півночі UTC. Будуйте відступ за retryAfter, а не за фіксованим розкладом, і ніколи не крутіться в циклі на добовому ліміті.

В офіційному реєстрі MCP сервер поки не опубліковано; картка сервера для нього готова. AET подано в каталог конекторів Claude 19 жовтня 2026 і на рецензію застосунків ChatGPT 20 жовтня 2026; на дату статті обидві заявки чекали рецензії.

Простими HTTP-кроками — послідовність, яку MCP-клієнт проходить з AET:

1. POST /api/mcp з {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1"}}} і Accept: application/json, text/event-stream. Збережіть instructions.
2. tools/list. Закешуйте 26 інструментів.
3. tools/call aet_section_schema з {"section":"all"}; потім aet_design_options з {"kind":"learning","mood":"calm warm handmade","language":"uk"}.
4. tools/call aet_create_draft з {"requestId":"<uuid v4>","content":{…}}. Збережіть eventId і draftKey; покажіть previewUrl; claimUrl давайте лише користувачу.
5. Коли користувач хоче свій акаунт: викличте aet_access. Чекайте HTTP 401 з WWW-Authenticate. Завантажте метадані ресурсу, потім метадані сервера авторизації; зареєструйтеся через /api/oauth/register або скористайтеся своїм документом метаданих клієнта; відкрийте /oauth/authorize з PKCE S256; обміняйте код на /api/oauth/token.
6. Повторіть aet_access з Authorization: Bearer aeto_…; далі — aet_list_events, aet_get_event, aet_update_page.
7. На needs_confirmation покажіть summary, дочекайтеся явного «так», повторіть ідентичний виклик із confirmToken.
8. Оновлюйте токен доступу до спливу через grant_type=refresh_token; щоразу зберігайте новий токен оновлення.

Офіційні SDK для MCP роблять кроки 1, 2 і 5 за вас; Claude, ChatGPT, Claude Code, Cursor і Gemini CLI самі обробляють вхід (частина 2).

Деякі рішення в сервері AET корисні й поза подіями:

• Платформа не генерує вміст. Пише асистент; сервер перевіряє, модерує й верстає. Гранична вартість сторінки для вендора — виклик модерації й кілька записів, і саме це робить гостьові чернетки доступними (частина 3).
• Лінива автентифікація. Більша частина цінності досяжна без входу; 401 з'являється лише на першому інструменті акаунта, тож онбординг — це одна адреса.
• Підтвердження, написані сервером. Резюме, яке схвалює людина, сервер будує з самої зміни, а токен прив'язаний до точних операцій, тож клієнт не може переказати небезпечну дію як безневинну.
• Поелементні операції з версіями. Списки правляться за id з ifVersion, тож агенти й люди можуть правити ту саму сторінку, не перезаписуючи одне одного.
• Позначка недовірених даних у самих даних, а не лише в тексті. Значення, написані гостями, приходять загорнутими, тож модель бачить межу в структурі, а не лише в системній підказці.
• Один об'єкт помилки, одна реакція на код. Інструкції зіставляють кожен код з однією правильною реакцією, і обробка помилок стає пошуком у таблиці, а не здогадками.
• Усе, що потрібно клієнту, — у tools/list та instructions. Для правильного агента не потрібна жодна зовнішня документація.

Чесно, станом на 25 жовтня 2026:

• Немає вебхуків чи підписок на події; клієнти опитують через aet_get_event чи aet_event_stats.
• Не відкрито MCP prompts чи resources; усе — інструменти.
• Немає потокового прогресу; відповіді — окремі JSON-об'єкти.
• Немає часу завершення подій; datetime.end повертає попередження.
• Зображення приймаються лише за URL; інструмента завантаження немає.
• Платні квитки, схеми залу, квізи, магазини, спільноти й календарі налаштовує організатор в AET, а не інструменти.
• Немає серверної аналітики через кілька подій; статистика — для кожної події окремо.
• aet_claim_link з rotate тримає чинними три останні посилання для забирання, а не лише найновіше.
• Поки немає в офіційному реєстрі MCP і в каталогах Claude та ChatGPT (заявки на рецензії).

Частина 10 серії розповідає, що AET планує далі, і наводить перші числа з реального використання.

1. Надсилайте Accept: application/json, text/event-stream; чекайте JSON, а не SSE.
2. Не покладайтеся на Mcp-Session-Id; сервер без станів.
3. Читайте й виконуйте instructions; оновлюйте їх, коли змінюється версія сервера.
4. Генеруйте свіжий UUID v4 у requestId на кожне створення; повторно — лише щоб повторити той самий вміст.
5. Сприймайте HTTP 401 на інструментах акаунта як сигнал для OAuth, а не як фатальну помилку.
6. Тримайте ключі поза Authorization; передавайте їх як key.
7. Передавайте ifVersion; обробляйте conflict перечитуванням.
8. Обробляйте partial_apply, надсилаючи заново лише від невдалої операції.
9. Ніколи не підтверджуйте needs_confirmation автоматично; показуйте summary сервера дослівно.
10. Відступайте за retryAfter; ніколи не крутіться в циклі на добових лімітах.
11. Показуйте значення {untrusted: …} як цитований вміст користувачів.
12. Поважайте анотації: питайте перед інструментами з destructiveHint чи openWorldHint, якщо у вашому клієнті є шар підтверджень.

• Код AnyEventTool на 25 жовтня 2026: pages/api/mcp.ts (транспорт, інструкції, інструменти, анотації, походження, лінива автентифікація), pages/api/oauth/metadata.ts, register.ts, authorize.ts, token.ts (сервер авторизації), lib/aiops/access.ts (підключення, правила переадресації, токени), lib/aiops/actor.ts і lib/aiops/limits.ts (ліміти), lib/aiops/draft.ts, account.ts, live.ts, sections.ts (ідемпотентність, версії, пакети, підтвердження), public/.well-known/mcp.json (картка сервера), node_modules/@modelcontextprotocol/sdk 1.32.1 (версії протоколу).
• Запити до робочого сервера 25 жовтня 2026: initialize з протоколом 2025-06-18; tools/call aet_list_events без облікових даних → HTTP 401 з WWW-Authenticate; /.well-known/oauth-protected-resource.
• Model Context Protocol: версії специфікації і авторизація, перевірено 20 жовтня 2026.
• MCP-ендпоінт, картка сервера, llms.txt, pricing.md.

Знайшли розбіжність чи баг? Напишіть на support@anyeventtool.com — виправимо з датою.

Це частина 9 з 10. Назва останньої частини може змінитися.

1. Івент-менеджер, який не спить — ландшафт, три нулі, запобіжники (19 жовтня) · 2. Підключаємо асистента до AET — Claude, ChatGPT, Claude Code, Cursor, Gemini (20 жовтня) · 3. Гостьові чернетки зсередини (22 жовтня) · 4. Сторінка, якою агент пишається (22 жовтня) · 5. Дизайн від агента (23 жовтня) · 6. Жива подія за ключем (24 жовтня) · 7. Довіра за задумом (25 жовтня) · 8. Числа без імен (25 жовтня) · 9. Для розробників: MCP-сервер AET — ця стаття (25 жовтня) · 10. Плейбуки для десяти типів подій і що далі (25 жовтня).