Коротка відповідь: Щоб створити MCP-сервер, ви загортаєте систему чи джерело даних у протокол Model Context Protocol, щоб будь-який сумісний AI-агент міг їх викликати. Робота завжди однакова — шість кроків: обрати інструменти, ресурси та промпти, які сервер віддаватиме; зібрати каркас сервера на офіційному SDK; реалізувати кожен інструмент як типізовану функцію з чіткою схемою; обрати транспорт (stdio для локального, Streamable HTTP для віддаленого); додати автентифікацію та авторизацію, якщо сервер віддалений; потім протестувати його на реальному клієнті до викату. Сам протокол невеликий і стандартизований — до березня 2026 року MCP перетнув 97 мільйонів завантажень SDK на місяць і тепер керується Linux Foundation, де OpenAI, Google і Microsoft виступають співспонсорами. Складність не в протоколі. Складність у всьому навколо нього: спроєктувати інструменти так, щоб агент справді міг ними користуватися, коректно захистити віддалений сервер і довести, що все працює під навантаженням, перш ніж під’єднувати його до клієнтського агента.

Віддати один інструмент через stdio — справді невелика задача: офіційний quickstart розв’язує її за вечір. Віддати сервер, у який реальні агенти стукають тисячі разів на день, який тримає автентифікацію, безпечно падає і який можна налагодити, коли інструмент починає повертати сміття, — це інженерний проєкт. Нижче — що таке MCP-сервер насправді, як створити його крок за кроком, як обрати транспорт, як захистити віддалений сервер і які помилки тримають MCP-сервери на рівні демо.

Що таке MCP-сервер насправді

MCP-сервер — це програма, яка віддає можливості AI-агентам через єдиний стандартний інтерфейс. До MCP кожна команда, що хотіла дати агенту інструмент, писала власну разову інтеграцію; MCP замінює цей хаос «N на M» одним протоколом — саме тому він так швидко поширився. Той самий агент, який спілкується з вашим сервером, може спілкуватися з будь-яким із приблизно 9 650 серверів в офіційному реєстрі та будь-яким із ~15 900 репозиторіїв GitHub з тегом станом на травень 2026 року. Концептуальне тло — навіщо потрібен протокол і яку проблему він вирішує — ми розбираємо в матеріалі про те, що таке Model Context Protocol. Цей посібник — про збірку.

Сервер віддає три типи можливостей, і правильно їх розрізняти — це бо́льша частина проєктування:


Корисна модель: інструменти — це дієслова, ресурси — іменники, промпти — рецепти. Більшість серверів спираються переважно на інструменти, додають кілька ресурсів і використовують промпти ощадливо. Помилка новачка — звалити всі ендпоінти свого API в інструменти й вважати справу зробленою. Хороший MCP-сервер — курований, а не вичерпний.

До написання коду: визначте межі сервера

Головний чинник корисності MCP-сервера — якість проєктування інструментів, і це рішення ухвалюється до першого рядка коду. Агент не читає вашу документацію. Він читає назви інструментів, їхні описи та схеми параметрів — і вирішує за один прохід, без людини в контурі, який інструмент викликати і що передати. Розпливчасті назви та нечіткі схеми дають агента, який викликає не той інструмент або галюцинує аргументи.

Три питання, на які треба відповісти першими. Що агенту реально потрібно робити? Ідіть від задачі агента, а не від поверхні вашого API. Агенту підтримки потрібні , і — а не дзеркало з сорока REST-ендпоінтів один в один. Які інструменти пишуть, а які лише читають? Дії запису (повернення, видалення, надсилання) потребують інших огорож, ніж читання, і їх варто чітко розділити, щоб на руйнівних можна було вимагати підтвердження або суворішу авторизацію. Який мінімальний набір приносить користь? Сервер із шістьма добре названими й добре описаними інструментами кращий за той, що має шістдесят, між якими агент не може надійно обрати. Це harness engineering на боці сервера: простір дій, який ви віддаєте, — частина міркувань агента, а не нейтральна труба.

Як створити MCP-сервер крок за кроком

Коли межі визначені, збірка йде передбачуваним шляхом. Офіційні SDK (найзріліші — Python і TypeScript) беруть на себе обв’язку протоколу, тому бо́льша частина вашого коду — це власне логіка.

  1. Зберіть каркас сервера на офіційному SDK. Встановіть SDK для вашої мови, створіть екземпляр сервера, задайте йому ім’я та версію. SDK керує обробкою JSON-RPC-повідомлень, узгодженням можливостей і життєвим циклом, тож протокол на рівні дротів ви не реалізуєте.
  2. Опишіть кожен інструмент суворою схемою. Для кожного інструмента задайте точне ім’я, опис в одне речення, написаний для моделі (а не для людини-читача), і типізовану вхідну схему. Схема — це ваш контракт: саме вона не дає агенту передати рядок там, де потрібне ціле, і робить інструмент самодокументованим для клієнта.
  3. Реалізуйте логіку інструмента. Усередині обробника робіть справжню роботу — звертайтеся до бази, до внутрішнього API, виконуйте обчислення — і повертайте структурований результат. Тримайте обробники тонкими: валідуйте вхід, викликайте наявний сервісний шар, форматуйте вивід. Не зашивайте в MCP-обробник бізнес-логіку, яка потрібна й рештою системи.
  4. Додайте ресурси та промпти там, де вони допомагають. Віддавайте контекст лише для читання як ресурси (запис клієнта, документ із політикою), а будь-яку повторювану багатокрокову задачу спакуйте як промпт. Пропустіть це, якщо ваш сервер суто «про дії»; не кожному серверу потрібні всі три примітиви.
  5. Обробляйте помилки як дані, а не як падіння. Коли інструмент падає — поганий ввід, таймаут на боці залежності, проблема з правами — повертайте зрозумілу структуровану помилку, яку агент може прочитати й відновитися, а не кидайте необроблений виняток, що рве з’єднання. Агенти міркують над текстом помилки: хороша («замовлення не знайдено — перевірте ID замовлення») дозволяє агенту виправитися, а стектрейс — ні.
  6. Оберіть і під’єднайте транспорт. Вирішіть, чи працює сервер локально поруч із клієнтом (stdio), чи як мережевий сервіс, до якого дотягуються багато клієнтів (Streamable HTTP). Цей вибір задає все в деплої та безпеці, тому йому присвячено окремий розділ нижче.

Це і є робочий MCP-сервер. Від продакшен-рівня його відділяють наступні три розділи: вибір транспорту, шар безпеки й тестування.

stdio проти Streamable HTTP: вибір транспорту

MCP визначає два транспорти, і вибір не косметичний — він задає вашу модель безпеки, деплой і межу масштабування сервера.

stdio запускає сервер як локальний підпроцес клієнта, спілкування йде через стандартний ввід-вивід. Мережі немає, автентифікації між клієнтом і сервером немає, бо клієнт запускає сервер напряму й передає секрети через змінні оточення. Це правильний вибір для особистих утиліт, інструментів розробника й усього, що працює на тій самій машині, що й агент. Просто та швидко — і не масштабується далі одного користувача, бо немає мережі, якою під’єднається другий.

Streamable HTTP, що з’явився в редакції специфікації від 18 червня 2025 року, запускає сервер як мережевий сервіс, до якого багато клієнтів дотягуються по HTTP. Він замінив старий транспорт HTTP+SSE і тепер є варіантом за замовчуванням для всього, що не є суто локальним. Сервер на цьому транспорті — віддалений MCP-сервер, і екосистема явно сходиться саме до нього: реальні продукти викочують віддалені, доступні мережею сервери. Ціна цієї досяжності — ви отримуєте задачу автентифікації та авторизації, якої в stdio не було.

Правило вибору просте. Робите інструмент для себе чи однієї машини розробника? Беріть stdio. Робите сервер, який викликатимуть продукт, команда чи безліч агентів мережею? Будуйте його на Streamable HTTP від самого початку й вважайте роботу з безпеки нижче частиною збірки, а не окремим пізнім етапом. Прикручувати авторизацію до сервера, що розраховував на довіреного локального викликача, болючіше, ніж закласти її в перший день.

Як захистити віддалений MCP-сервер

Щойно сервер доступний мережею, він стає поверхнею атаки, і специфікація конкретна в тому, як його захищати. Редакція від 18 червня 2025 року зробила OAuth 2.1 основою авторизації MCP. Коректно захищений віддалений MCP-сервер вимагає PKCE для всіх клієнтів, використовує RFC 9728 (Protected Resource Metadata), щоб клієнти могли виявити, як автентифікуватися, використовує RFC 8414 для метаданих сервера авторизації та RFC 8707 (resource indicators), щоб виданий токен був прив’язаний до вашого конкретного сервера й не міг бути переграний проти іншого.

Практична порада від спільноти безпеки однозначна: впроваджуйте OAuth 2.1 з resource indicators з першого дня, а не відкладайте авторизацію «на потім». Поверхня атаки добре вивчена, і специфікація дає ясний шлях через динамічну реєстрацію клієнта та PKCE. Відкласти — означає перебудовувати модель довіри сервера, коли він уже викочений.

Автентифікація — лише половина роботи. MCP-сервер за своєю суттю — це спосіб дати мовній моделі робити реальні дії у ваших системах, а отже, він успадковує всю проблему prompt injection. Якщо агента, що викликає ваш сервер, можна шкідливим вмістом схилити до виклику вашого інструмента , жодне ідеальне налаштування OAuth вас не врятує. Продакшен-сервери видають вузько обмежені токени, розділяють інструменти читання й запису, вимагають явного підтвердження або суворіших перевірок на руйнівні дії та логують кожен виклик інструмента, щоб погану послідовність можна було відстежити й зупинити. Безпека тут — не один потік OAuth, а весь ланцюг від токена до інструмента й до побічного ефекту.

Тестування та оцінка вашого MCP-сервера

Сервер, який повертає правильну відповідь, коли ви викликаєте його руками, не протестований — він показаний у демо. Причина в тому, що споживач — не людина з чистими входами, а недетермінована модель, яка викличе ваші інструменти в порядку, якого ви не передбачили, з аргументами, яких ви не чекали, у відповідь на входи, які ви ніколи не писали.

Тестуйте на трьох рівнях. Перший — юніт-тестуйте кожен обробник звичайним чином: на заданий вхід чи дає він вірний структурований вивід і вірну структуровану помилку при збої? Другий — тестуйте сервер на реальному MCP-клієнті: під’єднайте його до справжнього агента й подивіться, чи може агент виявити ваші інструменти, обрати потрібний і передати коректні аргументи, спираючись лише на ваші імена та описи. Тут і розкривається розпливчастий дизайн: якщо агент постійно обирає не той інструмент, лагодити треба опис, а не модель. Третій — ганяйте eval’и на наскрізній поведінці: оцінений набір реалістичних задач, які агент має виконати за допомогою вашого сервера, щоб ловити регресії при додаванні інструмента або зміні схеми. Поєднуйте це зі спостережуваністю: трасуйте кожен виклик інструмента, його аргументи, затримку та результат, бо в продакшені сервер падає тихо — по одному поганому виклику за раз, рівно так, як зазвичай ламаються агентні системи.

Часті помилки, через які MCP-сервери не доходять до продакшену

Збої повторюються в різних команд, і майже жоден із них не про протокол.


Як до цього підходить Moai Team

Ми ставимося до MCP-сервера як до частини поверхні міркувань агента, а не як до тонкої обгортки над API. Це означає, що ми йдемо від задачі агента й проєктуємо невеликий, чітко описаний набір інструментів, розділяючи читання та запис так, щоб руйнівні дії несли власні огорожі. Для віддалених серверів ми будуємо на Streamable HTTP з OAuth 2.1, PKCE і прив’язаними до ресурсу токенами з першого коміту, бо прикручувати авторизацію заднім числом дорожче, ніж закласти її одразу. Кожен збій інструмента ми обробляємо як структуровані дані, з яких агент може відновитися, вибудовуємо токени й підтвердження навколо реальності prompt injection, яку успадковує будь-яка система з викликом інструментів, і не вважаємо сервер готовим, доки навколо нього немає eval’ів і трасування. Мета — не сервер, який працює, коли ми викликаємо його руками. Мета — сервер, яким агент може коректно користуватися тисячі разів на день, не йдучи тихо в збій.

Часті запитання

Що таке MCP-сервер?

MCP-сервер — це програма, яка віддає можливості AI-агентам через Model Context Protocol, єдиний стандартний інтерфейс, що замінив разові інтеграції, які команди раніше писали під кожен інструмент. Сервер може віддавати три речі: інструменти (функції, які агент викликає для дії), ресурси (дані у вигляді файлів, які агент читає) та промпти (багаторазові шаблони задач). Оскільки протокол стандартизований — і тепер керується Linux Foundation за крос-вендорної підтримки Anthropic, OpenAI, Google, Microsoft та інших — будь-який сумісний агент може працювати з будь-яким сумісним сервером.

Як створити MCP-сервер?

Використовуйте офіційний SDK (найзріліші — Python і TypeScript) і пройдіть шість кроків: визначте інструменти, ресурси та промпти, які агенту реально потрібні; зберіть каркас сервера на SDK; опишіть кожен інструмент суворою типізованою схемою та описом для моделі; реалізуйте логіку інструмента поверх наявних сервісів; обробляйте помилки як структуровані дані, а не падіння; і оберіть транспорт — stdio для локального, Streamable HTTP для віддаленого. SDK бере на себе обв’язку протоколу, тому бо́льша частина коду — це власне логіка інструментів і рішення навколо неї.

У чому різниця між транспортами stdio та Streamable HTTP?

stdio запускає сервер як локальний підпроцес клієнта — без мережі й без автентифікації; ідеально для особистих інструментів та утиліт розробника на одній машині, але не масштабується на багатьох користувачів. Streamable HTTP, що з’явився у специфікації від 18 червня 2025 року, запускає сервер як мережевий сервіс, до якого дотягуються багато клієнтів, і це варіант за замовчуванням для всього, що викочується як продукт. Плата — віддаленому серверу потрібен шар автентифікації та авторизації (OAuth 2.1 з PKCE і resource indicators), якого локальному stdio-серверу не треба.

Як захистити віддалений MCP-сервер?

Закладайте OAuth 2.1 з першого дня. Специфікація MCP від 18 червня 2025 року вимагає PKCE для всіх клієнтів, RFC 9728 (Protected Resource Metadata) для виявлення, RFC 8414 для метаданих сервера авторизації та RFC 8707 (resource indicators), щоб токени були прив’язані до вашого конкретного сервера. Окрім автентифікації, ставтеся до сервера як до поверхні з викликом інструментів, що успадковує проблему prompt injection: видавайте вузькі токени, розділяйте інструменти читання й запису, вимагайте підтвердження на руйнівні дії та логуйте кожен виклик, щоб шкідливу чи некоректну послідовність можна було відстежити й зупинити.

Moai Team створює MCP-сервери та агентів, які ними користуються, чесно — куровані інструменти, спроєктовані під те, як модель справді міркує, OAuth 2.1 і принцип найменших привілеїв з першого коміту, eval’и та спостережуваність навколо всього цього, щоб воно трималося в продакшені, а не лише в демо. Заплануйте дзвінок.