Ви щодня використовуєте Claude або ChatGPT. Вже набили руку — промпти, уточнення, весь цей танець. Але щоразу, коли потрібні дані з корпоративної CRM, трекера завдань або внутрішньої бази, ви перетворюєтесь на живий USB-кабель: копіюєте з вкладки А, вставляєте у вкладку Б, і так по колу, поки душа не покине тіло.
Ось що більшість туторіалів соромляться сказати прямо: відстань між «ШІ, що знає інтернет» і «ШІ, що знає ваш бізнес» — рівно один Python-файл. Не міграція на нову платформу. Не шестизначний контракт із вендором. Один файл з декоратором і докстрінгом. Протокол уже існує, його підтримали всі великі ШІ-компанії, і підключити його можна за один вечір. Показую як.
Чому очевидні рішення не працюють
«Просто використай API» — чудова порада, от тільки у вашого ШІ немає рук. Він не може сам викликати REST API вашої компанії (URL, що повертає дані, коли ввічливо попросиш). Можна вставити документацію API в чат, але це пожирає контекстне вікно — скільки тексту ШІ може «бачити» одночасно, його робоча пам'ять — і копіювати все одно доведеться вам. Інтеграції в стилі Zapier існують, але вони жорсткі: наперед визначені тригери, наперед визначені дії, і прайс-лист, від якого ваш фінансовий директор плаче.
Насправді вам потрібен спосіб дозволити ШІ самому знаходити й викликати ваші внутрішні інструменти — без вас у ролі посередника.
MCP: стандарт, який це вирішив
MCP (Model Context Protocol) — це універсальний роз'єм для ШІ-інструментів. Уявіть USB-C, але для підключення ШІ до ваших даних. Anthropic зробили його відкритим у листопаді 2024. До березня 2026 року SDK набрав 97 мільйонів завантажень на місяць. OpenAI, Google і Microsoft підключились. Станом на 26 квітня 2026 року в реєстрах проіндексовано понад 17 000 MCP-серверів.
Python SDK дозволяє зібрати робочий сервер в одному файлі. Ось як.
Крок 1: Встановіть SDK
Потрібен Python 3.10+ і або uv (рекомендований пакетний менеджер від Anthropic), або звичайний pip.
# Варіант А: uv (рекомендований)
uv init my-mcp-server && cd my-mcp-server
uv add "mcp[cli]" httpx
# Варіант Б: pip
pip install "mcp[cli]" httpx
httpx — це Python-бібліотека для HTTP-запитів. Через неї ваш сервер витягує дані з зовнішніх API. Якщо ваші дані живуть у базі даних, замініть його на відповідний драйвер.
Крок 2: Напишіть сервер
Створіть server.py. Ось повний MCP-сервер, що отримує погодні сповіщення від Національної метеослужби США — реальний API, без ключів автентифікації, ідеально для навчання:
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP
# FastMCP — високорівнева обгортка, яка перетворює
# звичайні Python-функції на MCP-інструменти
mcp = FastMCP("weather")
NWS_API_BASE = "https://api.weather.gov"
async def make_request(url: str) -> dict[str, Any] | None:
headers = {
"User-Agent": "mcp-weather-demo/1.0",
"Accept": "application/geo+json",
}
async with httpx.AsyncClient() as client:
try:
response = await client.get(
url, headers=headers, timeout=30.0
)
response.raise_for_status()
return response.json()
except Exception:
return None
@mcp.tool()
async def get_alerts(state: str) -> str:
"""Get active weather alerts for a US state.
Args:
state: Two-letter US state code (e.g. CA, NY)
"""
data = await make_request(
f"{NWS_API_BASE}/alerts/active/area/{state}"
)
if not data or "features" not in data:
return "No alerts found."
alerts = []
for feature in data["features"][:5]:
props = feature["properties"]
alerts.append(
f"Event: {props.get('event', 'Unknown')}\n"
f"Area: {props.get('areaDesc', 'Unknown')}\n"
f"Severity: {props.get('severity', 'Unknown')}"
)
return "\n---\n".join(alerts) or "No active alerts."
if __name__ == "__main__":
mcp.run(transport="stdio")
Приблизно 40 рядків реального коду. Декоратор @mcp.tool() — скорочений запис у Python, який реєструє вашу функцію як інструмент, доступний для ШІ — робить основну роботу. FastMCP зчитує ваші тайп-хінти (state: str) і докстрінг (опис у потрійних лапках), щоб автоматично згенерувати визначення інструменту, яке ШІ зрозуміє.
Це і є базовий патерн. Кожен MCP-сервер, який ви бачили — Slack, GitHub, Figma, усі 17 000+ — це той самий скелет із більшою кількістю ендпоінтів.
Крок 3: Підключіть до Claude Desktop
Claude Desktop читає JSON-конфіг (файл налаштувань у певному форматі), щоб знати, які MCP-сервери запускати. Шукайте його тут:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Створіть або відредагуйте:
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/my-mcp-server",
"run",
"server.py"
]
}
}
}
Замініть /absolute/path/to/my-mcp-server на реальний повний шлях. Відносні шляхи не працюють — на цьому спотикаються всі з першого разу.
Перезапустіть Claude Desktop. Шукайте іконку молотка внизу праворуч від поля вводу. Натисніть — має з'явитися get_alerts у списку. Якщо не бачите, перевірте ~/Library/Logs/Claude/mcp*.log на macOS.
Крок 4: Запитайте Claude щось
Напишіть: "Are there any weather alerts in California right now?"
Claude бачить, що має інструмент get_alerts, просить дозвіл його викликати, звертається до вашого сервера і відповідає живими даними NWS, до яких п'ять хвилин тому не мав доступу.
Це той самий момент «ага». Ваш чатбот щойно перестав бути загальним.
Крок 5: Замініть погодний API на свій
Тепер поміняйте make_request на будь-який API, який використовує ваша команда — Jira, Linear, внутрішній дашборд. Якщо є ендпоінт, що повертає дані, до ШІ-інструменту залишається одна функція. Патерн завжди один:
- Напишіть
async-функцію, що забирає дані - Навісьте декоратор
@mcp.tool() - Напишіть чіткий докстрінг (нижче поясню, чому це критично)
- Додайте в конфіг, перезапустіть
Кілька принципів проєктування, які відрізняють корисні MCP-інструменти від дратівливих: називайте інструменти парою дієслово-іменник (get_alerts, search_tickets, create_issue), щоб модель могла зрозуміти намір із самої назви. Тримайте кожен інструмент зосередженим на одній дії — функція, яка одночасно отримує, фільтрує і записує назад, це три інструменти, що прикидаються одним. І щодо параметрів — віддавайте перевагу явним типізованим аргументам перед рядками-«ковдрами»; state: str з докстрінгом «Two-letter US state code» дає моделі достатньо інформації для самостійної валідації.
Граблі, на які ви наступите
1. Опис інструменту — це і є продукт
Дослідження Університету Квінс від лютого 2026 проаналізувало 856 MCP-інструментів на 103 серверах. Результат: 97,1% описів інструментів мали щонайменше один дефект якості. 56% навіть не пояснювали своє призначення. Коли дослідники покращили описи, показник успішності завдань зріс на +5,85 відсоткових пунктів. Ваш докстрінг — це не документація, це інтерфейс, який читає ваш ШІ. Пишіть його як продуктову специфікацію: мета, пояснення параметрів, обмеження, приклади.
2. Ніколи не print() в stdout
Для серверів на stdio (саме це використовує Claude Desktop) виведення в stdout ламає JSON-RPC повідомлення — протокол, через який ваш ШІ та сервер спілкуються. Ваш сервер мовчки ламається, і ви 45 хвилин дивитесь у порожнечу. Використовуйте print("debug", file=sys.stderr) або модуль logging з Python.
3. Безпека — це ВАША відповідальність
MCP не має вбудованої автентифікації для локальних серверів. Це нормально, поки він працює на вашому ноутбуці через stdio — просто локальний процес. Але в ту мить, коли ви задумаєте виставити його через HTTP: стоп. OWASP MCP Top 10, опублікований на початку 2026, існує саме тому, що люди пропустили цей крок. Понад тридцять CVE по MCP-інструментах лише за січень-лютий 2026. У самому FastMCP була вразливість command injection (CVE-2025-64340, розкрита наприкінці 2025) у всіх версіях нижче 3.2.0.
Якщо ваш сервер працює з внутрішніми API, ставтесь до нього як до будь-якого бекенд-сервісу: валідуйте кожен вхідний параметр від моделі (вона буде галюцинувати значення — розраховуйте на це), забезпечте мінімальні привілеї, щоб кожен інструмент мав доступ лише до потрібних даних, і зафіксуйте версії залежностей. Локальний stdio — єдиний безпечний дефолт, поки ви не розібрались з автентифікацією як слід.
4. Шлях у конфігу має бути абсолютним
Відносні шляхи в claude_desktop_config.json мовчки не працюють. Без помилки, без логу — просто відсутня іконка молотка і розробник, що повільно втрачає віру в людство. Використовуйте /Users/yourname/... на macOS — розгортання тільди тут ненадійне.
Що ви можете зробити прямо зараз
У вас є повторюваний патерн. Будь-який API, який ваша команда вже використовує — трекер завдань, CRM, внутрішній дашборд, база даних — відстань в один Python-файл від того, щоб стати чимось, що ваш ШІ може запитувати напряму. Без черги на вендорську інтеграцію. Без податку Zapier. Без копі-пасту між вкладками як у 2019-му.
Стіна між «ШІ, що знає інтернет» і «ШІ, що знає ваш бізнес» тепер має двері. І ви їх збудували в менше рядків, ніж типовий конфіг-файл.
