Щось всі навколо тільки і говорять що ~~про море~~ про MCP – тож прийшов час і самому розібратись в темі.

Отже, сьогодні розберемося з основними поняттями – “що воно взагалі таке”, потім напишемо власний “мікро-MCP сервер”, а в наступному пості – щось більш реальне, про роботу з VictoriaLogs.

Зміст

Обмеження LLM

Будь-яка Large Language Model – це система “сама в собі”: в неї немає доступу до зовнішніх ресурсів і вона не може виконати якісь дії в реальному світі, в реальному оточенні – наприклад, виконати shell-команду на вашому ноутбуці чи надіслати API-запит до GitHub або до AWS.

З часом з’явилась концепція “агентів” – локальних сервісів, які модель може викликати або такі дії виконати.

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

Тому врешті-решт з’явився новий стандарт, протокол – Model Context Protocol (MCP), який як раз дозволив розширити можливості LLM та агентів через єдиний і стандартний спосіб описати контекст того, з чим модель буде мати справу.

And so… The MCP?

Отже, Model Context Protocol – це протокол, “схема”, яка описує стандарт, за яким модель може взаємодіяти із зовнішнім середовищем.

Саму специфікацію можна почитати тут – Specification.

Якщо дуже просто, то MCP – це “інтерфейс”, через який LLM може виконувати якісь дії.

Схема роботи MCP – клієнт-серверна:

MCP-клієнт, через який ми передаємо запит у вигляді natural language – “створи новий Pull Request в моєму GitHub-репозиторії”
та MCP-сервер, до якого LLM звертається, аби цей запит транслювати у формат “сходити на такий-то URL, пройти аутентифікацію з таким-то токеном, виконати такий-то API-запит”

В ролі клієнта може виступити будь-яке рішення, яке вміє говорити з LLM – Cursor IDE, мобільний застосунок, або навіть просто CLI-утиліта.

А в ролі сервера – сервіс, до якого наш клієнт може звернутись із запитом.

Архітектура MCP

Якщо говорити більш детально, то у нас є кілька компонентів:

MCP Host: наприклад, Cursor або Windsurf – приймає запит від юзера, формує структурований MCP-запит (виклик функції або tool), і надсилає його до MCP-клієнта
MCP Client: це сама LLM (або AI-агент) + її інтерпретатор (interpreter, runtime, tool router), і вони разом приймають запит від MCP Host, визначає, який саме tool треба використати, виконують цей виклик (через MCP Server), та повертають результат
MCP Server: сервіс, який надає один чи декілька tools для MCP Client, та виконує запити від MCP Client, наприклад – запускає shell-команди
Data Sources та Remote Services: власне те, з чим напряму буде комунікувати MCP-сервер – логи, бази даних, API-сервери

Сам flow виконання запиту можна визначити так:

User -> MCP Host
- MCP Host -> MCP Client (LLM/агент обробляє запит, визначає інструмент)
  - MCP Client -> MCP Server (використовує tool)
    - MCP Server -> Data Sources та Remote Services (отримує дані, формує відповідь)
  - MCP Server -> MCP Client
- MCP Client -> MCP Host
MCP Host -> User

Документація – Core architecture.

Компоненти MCP

Отже, MCP використовує модель клієнт-сервер, і описує три ключові компоненти (або примітиви):

Resources: дані, до яких треба звернутись – логи, метрики, база даних, API-відповіді (docs)
Prompts: шаблони або форми подачі запитів до LLM – визначають, як саме ми формулюємо питання, щоб модель краще зрозуміла, яку функцію (tool) викликати (docs)
Tools: функції, які доступні на MCP-сервері для виклику MCP-клієнтом, і які викликає модель чи агент після аналізу запиту користувача (docs)
- такими функціями тут можуть бути як функції, наприклад на Python, так і API-ендпоінти або shell-команди

Транспорти MCP

Для комунікації між клієнтом та сервером MCP визначає Transports – канали зв’язку, через які передаються запити та відповіді.

Наразі є три основних типи (MCP все ще активно розроблюється, тому можливо будуть нові):

stdio: стандартні потоки stdin/stdout, що використовується коли клієнт та сервер працюють локально
SSE (Server-Sent Events): односторонній канал від сервера до клієнта для передачі даних з результатами виконання запиту у вигляді подій
- SSE може бути реалізований як stream-like даних передача – тобто, передача великих відповідей невеликими chunks (частинами), або як повернення однієї події одним повідомленням
- в такому разі клієнт використовує стандартний HTTP POST для відправки самого запиту
Streamable HTTP: двосторонній канал, у якому клієнт отримує відповідь від сервера через HTTP streaming

Документація – Transport layer.

RAG vs MCP

Але ж у нас вже є Retrieval-Augmented Generation, RAG? Нашо нам новий інструмент?

Бо RAG виконує пошук інформації в зовнішніх середовищах, і повертає до моделі контекст, дані.

А з MCP – модель виконує саме дії: пошук інформації, запуск Docker-контейнеру на ноутбуці тощо.

Створення MCP Server

Окей – з основними поняттями розібрались, тепер давайте спробуємо створити власний MCP і підключити до якогось IDE.

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

MCP Server на Python

Писати будемо на Python з використанням Python SDK.

Створюємо директорію, активуємо virtual environment:

$ mkdir -p MCP/my-mcp-server
$ cd MCP/my-mcp-server
$ python -m venv .venv
$ . .venv/bin/activate

Встановлюємо бібліотеки:

$ pip install mcp mcp[cli] requests

Пишемо сам код:

#!/usr/bin/env python3

from mcp.server.fastmcp import FastMCP

# instantiate an MCP server client
mcp = FastMCP("My MCP Tools")


# Register a tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers and return the result"""
    return a + b


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

Тут:

FastMCP: бібліотека для створення MCP-серверів, яка реалізує специфікацію Model Context Protocol
- from mcp.server.fastmcp import – входить у Python SDK
tools: функції, які зможе використовувати LLM – див. Tools
run: метод для запуску FastMCP-серверу – див. Running Your FastMCP Server

Використання MCP Inspector

Є дуже прикольно штука для дебагу MCP-серверів – Inspector. Див. документацію тут>>>. Потребує в системі NodeJS >= 18.

Запускаємо:

$ npx @modelcontextprotocol/inspector python3 mcp_server.py
Starting MCP inspector...
⚙ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 
...

І відкриваємо в браузері http://127.0.0.1:6274, де в Tools можемо побачити наш tool add:

Додавання MCP Server до Windsurf

Так як у нас бібліотека mcp встановлена в Python virtual environment, то для її використання в IDE нам потрібен повний шлях.

В терміналі, в якому у нас активований venv виконуємо:

$ realpath .venv/bin/mcp
/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/mcp

Файл налаштувань MCP для Windsurf – ~/.codeium/windsurf/mcp_config.json.

Або просто відкриваємо Windsurf Settings:

Клікаємо Add Server > Add custom server:

І нам відкриється файл mcp_config.json з прикладом додавання серверу:

Додаємо наш:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/home/setevoy/Scripts/Python/MCP/my-mcp-server/.venv/bin/mcp",
      "args": [
        "run",
        "/home/setevoy/Scripts/Python/MCP/my-mcp-server/mcp_server.py"
      ]
    }
  }
}

Повертаємо до Settings, клікаємо Refresh – і маємо отримати наш новий сервер, у якого є один tool – add:

І він жеж має з’явитись у вікні чату:

Пробуємо його використати:

Йой! It works!

LLM (у випадку з Windsurf дефолтна буде Cascade) сама визначила, що в неї є доступ до MCP-серверу, який може виконати математичну операцію add, і використала його.

Найс.

В наступному пості – напишемо власний MCP-сервер для роботи з VictoriaLogs – просто, аби детальніше подивитись як воно працює, бо команда VictoriaMetrics вже робить власний сервер (ще не випустили, але я вже помацаю 🙂 ).

Див. наступну частину по MCP – AI: пишемо MCP-сервер для VictoriaLogs.