Какой язык лучше для MCP Server?

Python (официальный SDK mcp с FastMCP) — для быстрого старта; TypeScript (@modelcontextprotocol/sdk) — для frontend/full-stack. Протокольный слой идентичен.

stdio или HTTP-транспорт?

Локальная IDE-разработка: stdio. Multi-client, SaaS или командный доступ: HTTP + SSE (Streamable HTTP) с аутентификацией.

Чем отличаются Tools и Resources?

Tools выполняют действия (поиск, запись, API). Resources предоставляют данные только для чтения (конфиг, файлы) через URI.

Разработка MCP Server с нуля: вызов AI-инструментов

Q: Зачем VNC при отладке MCP на удалённом Mac?

Автоматизация браузера, связка ключей и запись экрана вызывают диалоги TCC macOS. SSH не может нажать «Всегда разрешать» — нужна графическая сессия.

01

Введение: зачем ИИ нужен MCP?

Даже сильные модели не знают ваших CRM-клиентов и вчерашних логов. Путь отрасли ясен: Function Calling → Plugins → MCP. Первые два часто vendor-specific; MCP стандартизирует обнаружение и вызов инструментов — написали один раз, используете в разных клиентах.

01
Боль: Claude / GPT должен ходить в БД, API и файлы — у каждого свой формат.
02
Сценарий: читать Markdown-заметки в Cursor, смотреть GitHub Issues в Claude Desktop.
03
Обещание: от пустой папки до deployable сервера — с кодом и таблицей ошибок.

02

Что такое MCP? Сначала протокол, потом код

2.1 Происхождение

Anthropic выпустила MCP в ноябре 2024, чтобы стандартизировать связь ИИ с инструментами и решить проблему N×M адаптеров. Контекст — в нашей статье про MCP и HTTP.

2.2 Архитектура

Модель Client ↔ Server: Client на стороне ИИ (Claude Desktop, Cursor); Server отдаёт возможности через JSON-RPC:

T
Tools: вызываемые функции — поиск, вычисления, запросы к БД.
R
Resources: читаемые данные — файлы, URL, конфиг.
P
Prompts: параметризуемые шаблоны промптов.

2.3 Коммуникация

Основа — JSON-RPC 2.0. Транспорт: stdio (локальный subprocess, дефолт Cursor) или HTTP + SSE / Streamable HTTP (удалённый). Жизненный цикл: handshake → initialize → запросы → shutdown.

2.4 Сравнение

Измерение	MCP	OpenAI Function Calling	LangChain Tools
Стандарт	Открытый протокол	Proprietary	Привязка к фреймворку
Транспорт	stdio / HTTP	HTTP	HTTP
Cross-model	Да	Нет	Частично
Resources / Prompts	Нативно	Нет	Нет
Экосистема 2026	10 000+ серверов	Зрелая	Зрелая

03

Подготовка среды разработки

3.1 Выбор языка

Python (mcp, FastMCP) для новичков; TypeScript (@modelcontextprotocol/sdk) для frontend/full-stack. В статье — Python, TS для справки.

Окружение

# Python
python -m venv .venv && source .venv/bin/activate
pip install mcp httpx pydantic

# TypeScript (справка)
npm init -y && npm install @modelcontextprotocol/sdk

3.2 Структура проекта

my-mcp-server/

my-mcp-server/
├── server.py            # точка входа
├── tools/               # calculator.py, web_search.py
├── resources/           # file_reader.py
├── prompts/             # templates.py
├── tests/test_tools.py
├── pyproject.toml
└── README.md

3.3 Инструменты отладки

1
MCP Inspector: npx @modelcontextprotocol/inspector python server.py
2
Claude Desktop: редактировать claude_desktop_config.json.
3
Cursor: Settings → MCP → добавить command + args.

04

Первый MCP Server: Hello World

server.py · минимальный сервер

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """Приветствует человека"""
    return f"Hello, {name}! Это ваш первый MCP-инструмент."

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

После python server.py в Cursor укажите {"command":"python","args":["/abs/path/server.py"]} — say_hello должен появиться в списке инструментов.

Cursor / Claude Desktop

✓
Абсолютные пути к server.py и Python из venv.
✓
После изменений перезапустить MCP-соединение или окно Cursor.
✓
Явно попросить вызов инструмента в чате и проверить регистрацию.

05

Tools: функции, вызываемые ИИ

5.1 Базовая структура

Сигнатура = документация: типы, возврат и docstring управляют выбором инструмента. Имена: snake_case, глагол в начале (search_web). Ошибки — структурированный JSON, не голые exceptions.

5.2 Сложные параметры (Pydantic)

Поисковый инструмент со схемой

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Поисковый запрос")
    max_results: int = Field(default=5, description="Макс. результатов")
    language: str = Field(default="ru", description="Язык результатов")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Веб-поиск, возвращает список результатов"""
    ...

5.3 Пять полезных инструментов

Инструмент	Назначение	Замечание
Калькулятор	Мат. выражения	ast.literal_eval, не eval
Файлы	Чтение/запись локально	Whitelist, нормализация путей
HTTP	Внешние API	Timeout, retry, лимит размера
SQL-запрос	Read-only SQL	Параметры, без DDL
Время	Now, часовые пояса	ISO 8601

5.4 Async-инструменты

async fetch_url

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Загружает содержимое URL"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text

5.5 Обработка ошибок

!
Сеть/IO: timeout 15–30 с.
!
Чувствительные ops: auth (API key, разрешённые пути).
!
{"error": "...", "hint": "..."} для retry модели.

06

Resources: динамический контент для ИИ

Resource vs Tool: Resource — поставщик данных (read-only); Tool — действие. Адресация через URI: file://, http://, custom://.

Статические и динамические Resources

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """Конфигурация приложения"""
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Профиль пользователя по ID"""
    return json.dumps(db.query_user(user_id))

Типы: текст (text/plain, JSON), бинарные (изображения, PDF), потоки (live-данные). Практика: filesystem-сервер с listing, чтением, опциональным watch.

07

Prompts: переиспользуемые шаблоны

MCP Prompts — параметризуемые фрагменты для единообразия промптов в команде.

Prompt для code review

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Шаблон ревью кода"""
    return [PromptMessage(
        role="user",
        content=TextContent(type="text", text=f"""Проверьте этот {language}-код:
1. Качество  2. Баги и безопасность  3. Производительность

```{language}
{code}
```""")
    )]

Multi-turn шаблоны (user + assistant) для интервью или debug-помощника. Клиент вызывает prompts/get.

08

Продвинутый уровень: HTTP-транспорт (удалённый MCP)

Характеристика	stdio	HTTP + SSE
Деплой	Локально	Удалённый сервер
Задержка	Очень низкая	Сеть
Multi-client	Нет	Да
Сценарий	IDE локально	SaaS / команда

Streamable HTTP

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

Production: Bearer Token, CORS, rate limiting. Не выставляйте неаутентифицированный HTTP-MCP в интернет.

09

Отладка и тесты

9.1 MCP Inspector

Графически тестировать tools/list, tools/call, JSON-RPC-логи и сценарии ошибок.

9.2 Unit-тесты (pytest + ClientSession)

test_calculator_tool

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert result.content[0].text == "4"

9.3 Частые ошибки

Ошибка	Причина	Решение
Инструмент не виден	Неверный путь в config	Проверить абсолютный путь
Ошибка JSON	Несериализуемый тип	Преобразовать в str или dict
Timeout	Медленное выполнение	Async + timeout
Permission denied	Путь / TCC	Whitelist / VNC для диалога

10

Production-деплой

10.1 Docker

Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

10.2 Облачные варианты

•
Railway / Render: быстро для side projects.
•
Lambda / Cloud Run: serverless — cold start, ограничения stdio.
•
VPS + Nginx: reverse proxy, TLS, rate limit.

10.3 Observability

Структурированные логи, метрики Prometheus, Sentry, /health. Декларировать версию MCP, расширять tools обратно совместимо.

11

Практика: MCP Server базы знаний

Цель: ИИ ищет локальные Markdown-заметки, семантический индекс, создание заметок. В Cursor: «Что я записал про MCP на прошлой неделе?»

Стек

Компонент	Рекомендация
Векторная БД	ChromaDB / Qdrant (локально)
Embeddings	text-embedding-3-small
File watch	watchfiles для инкрементального индекса

Ключевые Tools

1
index_notes: сканировать каталог, векторный индекс.
2
semantic_search: семантический поиск.
3
write_note: создать или дописать Markdown.
4
Resource: notes://{path} для одной заметки.

semantic_search экономит токены vs вставка всей библиотеки и даёт более точные ответы.

12

Экосистема MCP и перспективы 2026

Пять шагов (включая удалённый Mac)

1
Выбрать хост (Cursor / Claude Desktop), проверить MCP в версии 2026.
2
Разработка локально через stdio, Inspector для tools/list.
3
Зарегистрировать в Cursor MCP, smoke test Hello World.
4
Browser-, keychain-, screen-capture-серверы: GUI-сессия macOS для TCC (SSH недостаточно).
5
HTTP + Docker + auth в prod; связать с руководством Agent Skill и браузерным MCP.

13

FAQ

Python (mcp + FastMCP) — быстрее всего; TypeScript (@modelcontextprotocol/sdk) для Node-команд. Протокольный слой идентичен.

IDE локально: stdio. Multi-user / SaaS: HTTP + SSE / Streamable HTTP с аутентификацией.

Tools выполняют действия; Resources предоставляют данные для чтения через URI.

Browser MCP, связка ключей и запись экрана вызывают диалоги TCC macOS. SSH не может нажать «Всегда разрешать» — нужна VNC-GUI на хосте.

Заключение

MCP — стандартный протокол AI-tooling; цепочка от Hello World до production — ключевая компетенция AI-инженера в 2026. Какой инструмент вы построите следующим?

Скрытая стоимость редко в коде, а в среде выполнения: Windows + cloud Mac + Cursor MCP требуют TCC-диалоги, venv и логи Inspector в одной desktop-сессии. Свой Mac mini добавляет сон, обновления ОС и амортизацию; 8 ГБ RAM быстро не хватает при векторном индексе и параллельных серверах.

Чтобы проверять MCP почасово с GUI на той же машине, что и Cursor, арендуйте удалённый Mac через VNCMac — основная кнопка ведёт на тарифы, пакеты на главной.

Разработка MCP Server с нуля:
пошаговое руководство по вызову AI-инструментов

Введение: зачем ИИ нужен MCP?

Что такое MCP? Сначала протокол, потом код

2.1 Происхождение

2.2 Архитектура

2.3 Коммуникация

2.4 Сравнение

Подготовка среды разработки

3.1 Выбор языка

3.2 Структура проекта

3.3 Инструменты отладки

Первый MCP Server: Hello World

Cursor / Claude Desktop

Tools: функции, вызываемые ИИ

5.1 Базовая структура

5.2 Сложные параметры (Pydantic)

5.3 Пять полезных инструментов

5.4 Async-инструменты

5.5 Обработка ошибок

Resources: динамический контент для ИИ

Prompts: переиспользуемые шаблоны

Продвинутый уровень: HTTP-транспорт (удалённый MCP)

Отладка и тесты

9.1 MCP Inspector

9.2 Unit-тесты (pytest + ClientSession)

9.3 Частые ошибки

Production-деплой

10.1 Docker

10.2 Облачные варианты

10.3 Observability

Практика: MCP Server базы знаний

Стек

Ключевые Tools

Экосистема MCP и перспективы 2026

Рекомендуемые open-source серверы

Пять шагов (включая удалённый Mac)

FAQ

Заключение

Разработка MCP Server с нуля:пошаговое руководство по вызову AI-инструментов

Введение: зачем ИИ нужен MCP?

Что такое MCP? Сначала протокол, потом код

2.1 Происхождение

2.2 Архитектура

2.3 Коммуникация

2.4 Сравнение

Подготовка среды разработки

3.1 Выбор языка

3.2 Структура проекта

3.3 Инструменты отладки

Первый MCP Server: Hello World

Cursor / Claude Desktop

Tools: функции, вызываемые ИИ

5.1 Базовая структура

5.2 Сложные параметры (Pydantic)

5.3 Пять полезных инструментов

5.4 Async-инструменты

5.5 Обработка ошибок

Resources: динамический контент для ИИ

Prompts: переиспользуемые шаблоны

Продвинутый уровень: HTTP-транспорт (удалённый MCP)

Отладка и тесты

9.1 MCP Inspector

9.2 Unit-тесты (pytest + ClientSession)

9.3 Частые ошибки

Production-деплой

10.1 Docker

10.2 Облачные варианты

10.3 Observability

Практика: MCP Server базы знаний

Стек

Ключевые Tools

Экосистема MCP и перспективы 2026

Рекомендуемые open-source серверы

Пять шагов (включая удалённый Mac)

FAQ

Заключение

Разработка MCP Server с нуля:
пошаговое руководство по вызову AI-инструментов