Как создать MCP-сервер с нуля: пошаговый гайд для Cursor, Claude и автоматизации

Python, Node или другой стек — что выбрать новичку

Официальные SDK первого уровня: TypeScript, Python, C#, Go. Для русскоязычного вайбкодинга и гайдов чаще всего выбирают Python + FastMCP: мало boilerplate, декоратор @mcp.tool(), автогенерация JSON Schema из type hints.

Node уместен, если вся ваша инфраструктура на JavaScript. Для первого сервера разумный путь — Python 3.10+, менеджер пакетов uv или pip, виртуальное окружение.

Cursor, Claude Desktop и Claude Code — где потом подключим сервер

• Cursor — .cursor/mcp.json в проекте или глобально в домашней папке.
• Claude Desktop — claude_desktop_config.json (путь зависит от ОС).
• Claude Code — конфигурация MCP для командной работы в терминале.

Важно: тема этой статьи — разработка mcp сервера, а не настройка агентов Cursor. После сборки сервера вы подключите его в эти клиенты одной и той же логикой command/args/env или через URL для HTTP.

Локальный сервер или облако: когда нужен Docker

Для обучения и личных задач достаточно локального mcp сервера на stdio: Cursor сам запускает процесс. Docker и облако нужны, когда:

• сервером пользуется команда без общего ноутбука;
• нужен Streamable HTTP с аутентификацией;
• интеграция с 1С или CRM уже живёт в контейнере.

На старте не усложняйте: сначала stdio + Inspector, потом перенос в Docker.

Актуальная спецификация MCP (ревизия 2025-11-25) стандартизует два транспорта: stdio и Streamable HTTP. Устаревший вариант HTTP+SSE из ранних туториалов заменён; старые статьи могут ссылаться на SSE — ориентируйтесь на Streamable HTTP.

Локальный запуск через stdio для Cursor

При stdio клиент запускает сервер как подпроцесс и обменивается сообщениями через stdin/stdout. Критичное правило: в stdout нельзя писать ничего, кроме валидных MCP-сообщений — отладочные print ломают JSON-RPC. Логи отправляйте в stderr.

fastmcp run main.py

HTTP-транспорт для удалённого доступа и uvicorn

Для команды и удалённого доступа поднимайте Streamable HTTP:

uvicorn main:mcp --port 3000 --reload

Endpoint обычно один — например http://localhost:3000/mcp. POST и GET, опционально SSE внутри streamable-протокола. Для локальной разработки bind на localhost; в продакшене — валидация Origin и аутентификация.

Когда какой вариант выбрать

Decision tree: начните со stdio → убедитесь в Inspector → при необходимости вынесите в HTTP с middleware для API-ключей в заголовках.

Файл mcp.json и путь к серверу

В корне проекта создайте .cursor/mcp.json:

{
  "mcpServers": {
    "business-helper": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "main.py"],
      "env": {
        "WORDSTAT_TOKEN": "${env:WORDSTAT_TOKEN}"
      }
    }
  }
}

Cursor поддерживает stdio, SSE (legacy) и Streamable HTTP. Для удалённого сервера — блок url и headers. Интерполяция: ${env:NAME}, ${workspaceFolder}, ${userHome}. Актуальные поля — в документации Cursor MCP.

Проверка: агент видит tools и вызывает их

После сохранения конфига откройте Output → MCP Logs. В чате попросите: «Покажи топ запросов по фразе X через Wordstat». Модель должна предложить вызов tool (по умолчанию с подтверждением). Если tools не видны — проверьте путь, venv и логи Inspector ещё раз.

Переменные окружения и API-ключи через middleware

Не храните ключи в коде. Для HTTP-сервера используйте middleware FastMCP (on_call_tool): читайте заголовок Authorization или кастомный X-API-Key, кладите токен в context.state, используйте внутри tool. Для stdio — только env в mcp.json или envFile.

Блок закрывает запросы «mcp сервер для 1с», «яндекс mcp сервер», «mcp серверы для вайб кодинга» — без ухода в узкую нишу одного вендора.

MCP для Wordstat и SEO-автоматизации

Для сбора семантики агенту нужен tool уровня «получить топ фраз и частотность», а не низкоуровневый вызов API. Готовые open-source серверы (например, реализации на FastMCP для Yandex Wordstat) можно взять как образец архитектуры или форкнуть под свой OAuth. Свой сервер оправдан, если нужны фильтры, регионы и формат отчёта под ваш контент-завод.

Связка с SEO: MCP KV в пайплайне контент-офиса — тот же принцип: Wordstat → ядро → текст. Научившись писать сервер, вы понимаете, как автоматизировать исследование ключей из Cursor.

Webhook и сценарии Make.com

У Make есть облачный MCP-сервер (Streamable HTTP, OAuth) для запуска сценариев из агента. Это другой уровень, чем свой сервер с tool trigger_webhook: готовый MCP — быстрый старт; свой — полный контроль над payload и валидацией. Для контент-завода часто достаточно пары tools: «отправить черновик в Telegram», «добавить строку в Google Sheets».

Идеи для 1С и Битрикс24 без ухода в узкую нишу

Запрос «mcp сервер для 1с» (~365 показов/мес. в Wordstat) отражает спрос на мост между учёткой и ИИ. Архитектурно: расширение или HTTP-прокси в 1С + Python MCP с 3–5 tools (get_stock, create_order_draft). Для Битрикс24 опыт внедрений показывает: pre-authenticated токены в конфиге надёжнее «чистого» OAuth на всех клиентах; не копируйте REST 1:1 — делайте сценарные tools.

MCP и вайбкодинг: свой стек под контент-завод

Вайбкодинг — когда вы описываете задачу, а Cursor собирает код. Свой MCP замыкает цикл: агент не только пишет текст, но и дергает ваши инструменты — Wordstat, CMS, Make. Это ядро стека Kovcheg: Cursor + MCP + автоматизация без обязательного бэкенд-бэкграунда.

Авторизация, заголовки и секреты

Минимум: ключи в env, не в репозитории; для HTTP — HTTPS, проверка Origin, rate limit. Middleware извлекает токен из заголовка и не передаёт его в ответ tool.

Ограничение прав tools (read-only vs mutating)

Разделяйте tools, которые только читают данные, и те, что меняют систему. Используйте ToolAnnotations и разумный UX: деструктивные действия — с явным описанием в docstring. Помните: аннотации — подсказка, а не гарантия; злонамеренный сервер может врать.

Деплой: Docker и мониторинг

Образ с uvicorn, healthcheck на /mcp, логи в stderr/систему мониторинга. Обновляйте зависимости; в open-source MCP встречались уязвимости в прослойках — относитесь к чужим серверам с осторожностью и не ставьте непроверенные tools с правами на прод.

MCP-сервер создаётся за 30–60 минут на FastMCP с минимумом двух tools с понятными docstring. Проверка в MCP Inspector перед mcp.json экономит часы отладки. Выберите stdio для локальной работы или Streamable HTTP для команды, спроектируйте 3–5 сценарных tools, подключите сервер в Cursor и Claude — и вы получите тот же класс интеграций, что лежит в основе автоматизации контента и вайбкодинга.