Як створити MCP-сервер: покроковий посібник з Python та TypeScript (2026)

Ви можете створити MCP-сервер, який Claude дійсно викликатиме, приблизно за 15 хвилин. Ми протестували це на Node 20 та Python 3.11: робочий інструмент add, що працює через stdio і підхоплюється Claude Desktop, зайняв 14 хвилин під час першої спроби та менше 5 хвилин, коли вже знаєш структуру. У цьому посібнику ми створюємо один і той самий сервер двічі: спочатку на Python із FastMCP 2.x, потім на TypeScript із @modelcontextprotocol/sdk 1.x, щоб ви могли обрати свій стек і скопіювати реальний код. Якщо ви хочете спершу розібратися в архітектурі та теорії протоколу, наш посібник із концепцій Model Context Protocol містить усю необхідну інформацію; тут же ми просто будуємо.

Швидкий старт із MCP-сервером: що саме ви будуєте

MCP-сервер — це невелика програма, яка надає інструменти, дані та шаблони промптів для AI-клієнтів, таких як Claude, Cursor або VS Code, через протокол Model Context Protocol. Ви пишете сервер один раз, і будь-який сумісний із MCP клієнт може його викликати. У цьому посібнику ви створите сервер із двома інструментами (калькулятор add та помічник `fetch_url»), запустите його локально через stdio, протестуєте та підключите до реального клієнта.

Ось усе, що вам потрібно перед початком роботи.

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

Що саме надає MCP-сервер?

Перш ніж писати код, корисно знати три речі, які може пропонувати сервер. MCP-сервер надає інструменти (функції, які модель може викликати, наприклад, «пошук у базі даних»), ресурси (дані лише для читання, які модель може завантажити, наприклад, файл або запис) та промпти (багаторазові шаблони промптів). Більшість серверів, які ви будете створювати, будуть орієнтовані на інструменти; ресурси та промпти є опціональними.

Визначення MCP-сервера: процес, який говорить мовою Model Context Protocol і рекламує список інструментів, ресурсів та промптів, які AI-клієнт може виявити та викликати під час виконання.

Клієнт (наприклад, Claude Desktop) виступає в ролі хоста. Він запускає або підключається до вашого сервера, запитує «які у тебе є інструменти?» і викликає їх, коли модель вирішує, що інструмент буде корисним. Ви ніколи не викликаєте модель із середини сервера. Потік даних йде в зворотному напрямку.

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

Як створити MCP-сервер на Python (крок за кроком)

Python — це найшвидший шлях до робочого сервера, оскільки FastMCP бере на себе протокольну частину і перетворює звичайні функції на інструменти за допомогою декоратора. Усе нижченаведене використовує офіційний Python SDK. Ось чотири кроки.

Крок 1: Налаштування проєкту. Використовуйте uv, який зараз є стандартом для Python-проєктів MCP:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Якщо ви віддаєте перевагу pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Крок 2: Написання сервера. Створіть файл server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Зверніть увагу на дві речі. Рядок документації (docstring) стає описом інструменту, який читає модель, тому пишіть його як інструкцію. А анотації типів (a: int) автоматично стають схемою вводу, тож FastMCP генерує JSON Schema за вас.

Крок 3: Запуск. mcp.run() запускає сервер на stdio — транспорті, який клієнти запускають локально. Під час розробки ви не запускаєте це безпосередньо; це робить клієнт. Для швидкої перевірки працездатності використовуйте dev-раннер:

uv run mcp dev server.py

Крок 4: Повернення чистого виводу. Важливий момент, який варто зазначити зараз: повертайте рядок або типізоване значення, а не «голий» вкладений словник, на який ви сподіваєтеся. Ми повернемося до причин цього в розділі про продакшен, але коротко кажучи, неоднозначні типи повернення можуть мовчки обрізатися в деяких клієнтах.

Це повноцінний MCP-сервер на Python. Два інструменти, реальні мережеві виклики, автоматична схема. Далі — те саме на TypeScript.

Як створити MCP-сервер на TypeScript (крок за кроком)

Шлях TypeScript використовує офіційний TypeScript SDK безпосередньо та zod для валідації вводу. Це трохи більш багатослівно, ніж FastMCP, але типи чудові, і це чисто деплоїться на Node-хости.

Крок 1: Налаштування проєкту.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Крок 2: Написання сервера. Створіть файл server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Крок 3: Запуск. Під час розробки: npx tsx server.ts. Для продакшену скомпілюйте за допомогою tsc і запустіть зібраний .js файл через Node. Зверніть увагу на структуру повернення: кожен інструмент повертає { content: [{ type: "text", text: ... }] }. Цей явний масив content є еквівалентом правила «повертай чистий рядок» з Python для TypeScript. SDK вимагає типізованих блоків контенту, а не сирих об'єктів.

Крок 4: Валідація вводу за допомогою zod. Схема z.string().url() відхиляє неправильний ввід до запуску вашого обробника, що є саме тим, що потрібно, коли модель генерує аргументи.

Ті самі два інструменти, та сама поведінка, ідіоматичний TypeScript. Тепер давайте вирішимо, як клієнти мають досягати вашого сервера.

stdio проти Streamable HTTP: який транспорт обрати?

MCP-сервери спілкуються через один із двох транспортів. stdio запускає сервер як локальний підпроцес, який клієнт запускає і з яким спілкується через стандартний ввід/вивід. Streamable HTTP запускає сервер як мережевий сервіс, до якого клієнти підключаються через HTTP. Обирайте залежно від того, де має жити сервер.

Загальне правило: будуйте та тестуйте на stdio, а переходьте на Streamable HTTP лише тоді, коли сервер потрібен більш ніж одній людині або машині. Більшості серверів ніколи не потрібно виходити за межі stdio. Виклики mcp.run() та StdioServerTransport() вище вже використовують stdio, тож для розробки ви готові.

Як тестувати свій MCP-сервер за допомогою Inspector

Перш ніж підключати свій сервер до Claude, протестуйте його ізольовано за допомогою MCP Inspector. Це браузерний інтерфейс, який підключається до вашого сервера, перелічує його інструменти та дозволяє викликати їх вручну. Запустіть його проти вашого сервера:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspector відкриє локальну сторінку, де ви побачите свої інструменти add та fetch_url, зможете здійснити тестовий виклик і прочитати сиру відповідь. Це найкраща звичка для розробки під MCP. Якщо схема інструменту malformed або повернене значення неправильне, ви побачите це тут за секунди, замість того щоб дивитися на тиху помилку всередині Claude. Таким чином ми виявили погану схему вводу, яка інакше коштувала б нам повного циклу налагодження через клієнт. Завжди тестуйте в Inspector насамперед.

Як підключити свій MCP-сервер до Claude Desktop, Claude Code та Cursor

Коли Inspector задоволений, спрямуйте реальний клієнт на ваш сервер. Кожен клієнт читає конфігураційний файл, який повідомляє йому, як запустити ваш сервер через stdio.

Claude Desktop. Відредагуйте claude_desktop_config.json (на macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Перезапустіть Claude Desktop, і ваші інструменти з'являться під піктограмою конекторів.

Claude Code. Додайте сервер однією командою зі свого проєкту: claude mcp add demo-server -- uv run server.py. Claude Code зберігає його у конфігурації проєкту та завантажує при запуску. Якщо ви також використовуєте хуки для скриптингу Claude Code, наш посібник із хуків Claude Code добре поєднується з кастомними MCP-інструментами.

Cursor. Додайте той самий блок mcpServers до .cursor/mcp.json у корені вашого проєкту. Структура збігається з Claude Desktop. Для реального прикладу MCP-сервера, що працює всередині Claude Code, подивіться, як ми інтегрували Higgsfield у Claude Code.

Використовуйте абсолютні шляхи в кожній конфігурації. Відносні шляхи є найпоширенішою причиною невдалого запуску сервера.

Деплой MCP-сервера в продакшен (автентифікація та хостинг)

Коли ваш сервер потрібно поширити, переведіть його зі stdio на Streamable HTTP і додайте три речі: автентифікацію, обробку помилок та хостинг.

• Автентифікація. Віддалені MCP-сервери повинні використовувати OAuth 2.1 згідно зі специфікацією авторизації MCP. Для внутрішніх інструментів мінімальним практичним рішенням є перевірка bearer-токена на HTTP-ендпоінті. Ніколи не публікуйте загальнодоступний сервер інструментів без автентифікації, оскільки інструмент, який виконує SQL-запити або звертається до внутрішніх API, є живою поверхнею для атак.
• Обробка помилок. Огорніть тіла інструментів у try/except (або try/catch) і повертайте типізоване повідомлення про помилку замість того, щоб генерувати виняток. Модель набагато краще обробляє «запит не вдався, ось чому», ніж розірване з'єднання.
• Хостинг. Підходить будь-яка платформа, яка запускає довготривалий процес Node або Python: невеликий VPS, Fly.io, Railway або контейнер у вашій власній інфраструктурі. Тримайте процес «теплим», оскільки холодний старт додає затримку до першого виклику інструменту.
• Конкурентність та вартість. Якщо ваші інструменти викликають LLM або платний API далі по ланцюжку, поставте перед ними шлюз. Наша добірка інструментів LLM-шлюзу охоплює обмеження швидкості та резервні варіанти, а інструменти контекстного інжинірингу допомагають запобігти роздуванню вікна контексту моделі виводом інструментів.

Для Python змініть виклик запуску на mcp.run(transport="streamable-http"); для TypeScript замініть StdioServerTransport на StreamableHTTPServerTransport із SDK. Визначення інструментів взагалі не змінюються — у цьому й полягає суть абстракції транспорту.

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

Ми створили MCP-сервери для внутрішнього використання в Techsy, і кілька уроків проявляються лише тоді, коли на них потрапляє реальний трафік. Ось що ми виміряли і де наткнулися на проблеми.

Перший сервер, який ми запустили, був інструментом лише для читання запитів Postgres, створеним за допомогою FastMCP 2.x на основі Python SDK mcp 1.x, пізніше переписаним на @modelcontextprotocol/sdk 1.x для порівняння. На стеку 2026 року (Node 20, Python 3.11) локальні виклики інструментів через stdio додавали приблизно 8–12 мс накладних витрат транспорту на виклик. Коли ми перенесли той самий сервер на Streamable HTTP на VPS, вартість одного виклику зросла до 40–70 мс, майже повністю через мережевий круговий обіг, а не через витрати протоколу. Холодний старт FastMCP займав близько 300 мс для процесу, саме тому ми тримаємо продакшен-процес «теплим».

Проблема, яка коштувала нам близько двох годин: інструмент, який повертав сирий Python dict, нормально відображався в Inspector, але приходив обрізаним у Claude Desktop. Обгортання поверненого значення як типізованого текстового рядка миттєво виправило ситуацію. Саме тому цей посібник скрізь повертає рядки та текстові блоки content замість вкладених об'єктів. Іншою звичкою, яка одразу виправдала себе, був запуск кожного сервера через npx @modelcontextprotocol/inspector перед тим, як торкатися конфігурації клієнта, що виявило malformed схему вводу під час переписування на TypeScript, яка інакше тихо провалилася б у Cursor.

Якщо ви обираєте, які інструменти будувати в сервери насамперед, наш список найкращих MCP-серверів у 2026 році є хорошим банком ідей.

Як Techsy підходить до розробки MCP

У Techsy ми будуємо MCP-сервери як частину систем AI-агентів, які постачаємо клієнтам, з'єднуючи агентів із внутрішніми базами даних, CRM та API через типізований шар інструментів. Наш підхід полягає в тому, щоб почати з вузького завдання (один добре протестований інструмент через stdio), перевірити його в Inspector, а потім підвищити його рівень до автентифікованого HTTP-сервісу лише тоді, коли він потрібен більш ніж одному агенту. Ми поєднуємо кастомні сервери з Claude Agent SDK, коли логіка агента стає складною.

Ось чесна версія: більшість команд надмірно ускладнюють свій перший сервер. Вам рідко потрібні HTTP, OAuth і десяток інструментів у перший день. Якщо вам потрібен свіжий погляд на інтеграцію MCP, отримайте безкоштовну консультацію, і ми скажемо вам, чи це завдання для одного інструменту через stdio, чи щось, що справді потребує інфраструктури.

Поширені запитання

Чи варто будувати мій MCP-сервер на Python чи TypeScript?

Використовуйте те, що ваша команда вже постачає. Python із FastMCP — це найкоротший шлях до першого робочого сервера, оскільки декоратор перетворює функцію на інструмент. TypeScript з офіційним SDK трохи більш багатослівний, але дає чудові типи та чисто деплоїться на Node-хости. Обидва створюють сервери, які поводяться однаково для клієнта.

Чи потрібен мені фреймворк на кшталт FastMCP для створення MCP-сервера?

Ні, але це допомагає. FastMCP поставляється разом з офіційним Python SDK mcp і усуває більшу частину шаблонного коду протоколу. Ви можете використовувати низькорівневий API Server для тонкого контролю, але для майже кожного сервера FastMCP (Python) або McpServer (TypeScript) є правильним інструментом і вимагає набагато менше коду.

Як налагодити MCP-сервер, який не працює?

Спершу запустіть його через MCP Inspector: npx @modelcontextprotocol/inspector, а потім вашу команду запуску. Inspector перелічує ваші інструменти та дозволяє викликати їх безпосередньо, тож ви можете підтвердити, що сервер працює, перш ніж звинувачувати клієнт. Якщо з Inspector усе гаразд, але клієнт не працює, перевірте, чи ваша конфігурація використовує абсолютні шляхи, і чи перезапустили ви клієнт.

Чи є FastMCP офіційною частиною MCP?

Так. FastMCP входить до складу офіційного Model Context Protocol Python SDK як високоуровневий інтерфейс сервера. Декоратор @mcp.tool(), який ви використовуєте, є рекомендованим способом створення серверів на Python, а не стороннім додатком.

Яка різниця між локальним та віддаленим MCP-сервером?

Локальний сервер працює на вашій машині через stdio, запускається клієнтом як підпроцес і найкраще підходить для особистих інструментів та розробки. Віддалений сервер працює як вебсервіс через Streamable HTTP і доступний для кількох клієнтів, що вимагає автентифікації OAuth 2.1. Спочатку будуйте локально, переходьте на віддалений режим лише тоді, коли потрібно ділитися.

На яких мовах можна створити MCP-сервер?

Model Context Protocol має офіційні SDK для Python, TypeScript, Java, Kotlin та C#, а також komuniti-SDK для інших мов. Оскільки MCP є дротовим протоколом, будь-яка мова, яка може читати та записувати JSON-RPC через stdio або HTTP, може реалізувати сервер, але офіційні SDK позбавляють вас цієї роботи.

Чи працює MCP-сервер із ChatGPT та Gemini, чи тільки з Claude?

MCP — це відкритий стандарт, прийнятий в екосистемі агентного AI, включаючи ChatGPT, Gemini, Cursor та VS Code Copilot. Один сервер, який ви створюєте, працює з будь-яким сумісним клієнтом. Вам не потрібно писати окрему інтеграцію для кожної моделі, і в цьому вся суть протоколу.

Скільки часу займає створення робочого MCP-сервера?

Перший сервер з одним або двома інструментами, що працюють через stdio, займає близько 15 хвилин після встановлення середовища виконання. Ми виміряли 14 хвилин для новачка на Node 20 і менше 5 хвилин для повторної збірки. Додавання автентифікації, HTTP-транспорту та продакшен-хостингу займає реальний час, а не сам сервер.

Про автора

Мерт Батур Гюрбюз є співзасновником Techsy.io, де команда постачає AI-агентів, системи автоматизації та голосові/SDR-пайплайни для B2B-клієнтів. Він навчається в Бірмінгемському університеті та пише про стек інструментів LLM, який команда Techsy реально використовує у продакшені. Підключайтеся на LinkedIn.

Мерт Батур Гюрбюз, співзасновник, Techsy.io, Бірмінгемський університет