MCP-сервер: что это и как подключить к Claude Code, Codex и Cursor

MCP (Model Context Protocol) это открытый стандарт, по которому ИИ-приложения подключаются к внешним системам: файлам, базам данных, API, таск-трекерам. MCP-сервер это программа, которая по этому стандарту даёт агенту инструменты и данные. Один раз написали сервер для своего сервиса, и его могут подключить Claude Code, Codex, Cursor, Claude Desktop и другие клиенты, которые поддерживают протокол.

Протокол представила Anthropic 25 ноября 2024 года вместе со спецификацией и SDK в открытом репозитории. Спецификация меняется, и клиенты поддерживают разные её версии. Поэтому, читая любую инструкцию по MCP, включая эту, сверяйте её с документацией своего клиента. Что поменялось в последней версии, разобрал в конце статьи.

Из чего состоит MCP: хост, клиент, сервер

В MCP три роли, и их часто путают.

• Хост это ИИ-приложение, с которым вы работаете: Claude Code, Codex, Cursor, Claude Desktop. Хост решает, когда модели понадобился инструмент.
• Клиент это часть хоста, которая держит связь с одним конкретным сервером. Хост создаёт по клиенту на каждый подключённый сервер.
• Сервер это программа, которая отдаёт хосту инструменты и данные.

Слово «сервер» сбивает с толку. Для MCP-сервера не нужны VPS и открытый порт. MCP-сервер может быть обычной программой на вашем компьютере: хост запускает её и общается с ней через стандартный ввод и вывод.

Как это выглядит на одном запросе. Вы просите агента найти в папке договор за сентябрь. Модель видит в списке инструментов search_files от файлового MCP-сервера и решает его вызвать. Клиент отправляет серверу запрос, сервер ищет в разрешённой папке и возвращает список файлов. Хост передаёт результат модели, и та отвечает вам.

Сообщения между клиентом и сервером идут в формате JSON-RPC 2.0. Как хост использует модель и что делает с полученными данными, протокол не определяет: это решает само приложение.

Что сервер может дать агенту

У сервера три основных типа возможностей.

Есть ещё elicitation: сервер может попросить у пользователя недостающие данные или подтверждение.

Как сервер общается с клиентом

Стандартных транспортов в MCP два, спецификация допускает и собственные.

• stdio. Хост запускает сервер как дочерний процесс и обменивается с ним через стандартные потоки. Подходит для локальных серверов, сетевой порт не нужен.
• Streamable HTTP. Сервер работает по сети: обмен идёт по HTTP, ответ приходит JSON или, где это предусмотрено версией протокола, потоком SSE. Так подключают удалённые сервисы.

Старый транспорт HTTP+SSE заменили на Streamable HTTP в версии 2025-03-26. SSE как способ передать потоковый ответ остался, устарел именно отдельный SSE-транспорт. Это изменение транспорта, к рукопожатию initialize (о нём в разделе про спецификацию 2026-07-28) оно отношения не имеет.

Авторизация в MCP необязательна. Если HTTP-сервер её требует, он работает по OAuth 2.1 как ресурсный сервер. Локальному серверу на stdio ключи передают через переменные окружения.

Как подключить MCP-сервер

Настройки зависят от клиента. Claude Desktop и Cursor используют похожий блок mcpServers, но путь к файлу, поддерживаемые поля и подстановка переменных у них разные. Команды ниже составлены по документации клиентов (ссылки в заголовках): версии пакетов я закрепил, пути замените своими.

Что понадобится заранее: сам клиент (для команд — его CLI: claude или codex), Node.js с npx для серверов из npm и uv с Python 3.10+ для своего сервера на Python. Проверить: node -v, uv --version, python3 --version. Учтите одно до копирования команд: npx -y и uvx скачивают пакет и запускают его с правами вашего пользователя. Ниже версии пакетов закреплены: @upstash/context7-mcp@4.4.4 и @modelcontextprotocol/server-filesystem@2.0.1 есть в реестре npm на 28 октября 2026 года; ставьте только серверы, репозиторий и автора которых вы проверили.

Claude Code. Удалённый сервер по HTTP и локальный по stdio:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport stdio demo -- uv run --directory /абсолютный/путь/к/mcp-demo mcp run server.py

Во второй команде demo — имя сервера, а всё после двойного дефиса — команда, которой Claude Code запустит сервер; здесь это сервер из раздела ниже. Путь замените на свой. По умолчанию настройка действует только для текущего проекта, с --scope project она пишется в .mcp.json в корне проекта, с --scope user работает во всех проектах. Внутри Claude Code команда /mcp показывает состояние серверов и запускает вход по OAuth.

Codex. Командой или в ~/.codex/config.toml:

codex mcp add context7 -- npx -y @upstash/context7-mcp@4.4.4

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@4.4.4"]

Проверить список: codex mcp list, вход по OAuth: codex mcp login <имя>. Про сам Codex подробнее в статье что такое OpenAI Codex.

Claude Desktop. Меню Settings → Developer → Edit Config, файл claude_desktop_config.json (на macOS в ~/Library/Application Support/Claude/, на Windows в %APPDATA%\Claude\). Файловый сервер в примере умеет не только читать файлы, но и менять их, поэтому сначала создайте отдельную папку mcp-test и откройте ему только её:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2.0.1", "/Users/username/mcp-test"]
    }
  }
}

После сохранения документация велит полностью закрыть Claude Desktop и открыть заново. Если сервер подключился, он появится в списке коннекторов (кнопка «Add files, connectors, and more»), и там видны его инструменты. Появление в списке значит, что сервер запустился; работает ли инструмент, проверяйте пробным вызовом.

Cursor. Тот же JSON-формат mcpServers, что у Claude Desktop выше, в файле .cursor/mcp.json в проекте или ~/.cursor/mcp.json для всех проектов. Ключи Cursor советует брать из окружения через ${env:NAME}, а не писать в файл. Включённые серверы видны в разделе Customize, там же их отключают. Если сервер не отвечает, откройте панель Output (Cmd+Shift+U или Ctrl+Shift+U) и выберите «MCP Logs»: там видны запуск сервера, вызовы инструментов и ошибки.

Свой MCP-сервер за 15 строк

Это пример из официального Python SDK без изменений: файл docs_src/index/tutorial001.py в теге v2.3.0. Сервер даёт один инструмент add и один ресурс-шаблон greeting:

from mcp.server import MCPServer

mcp = MCPServer("Demo")


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


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Для v2.3.0 нужен Python 3.10 или новее: в pyproject.toml этого тега стоит requires-python = ">=3.10". Создайте проект, закрепите проверенную версию SDK и положите пример в server.py:

uv init --no-workspace mcp-demo && cd mcp-demo
uv add "mcp[cli]==2.3.0"
uv run mcp dev server.py

Команда uv run mcp dev server.py запускает режим разработки с инспектором, где можно вызвать инструменты руками.

Прежде чем подключать сервер к агенту, проверьте его в инспекторе: вызовите add с аргументами 2 и 40 и убедитесь, что ответ 42. Затем добавьте сервер в клиент и попросите агента вызвать инструмент. Статус enabled в codex mcp list или зелёная отметка в настройках значат только, что конфигурация прочитана, а не что агент уже умеет пользоваться инструментом.

Описание инструмента в docstring агент видит и по нему решает, когда инструмент вызывать. Пишите его так, как объясняли бы коллеге: что делает, какие аргументы ждёт, что вернёт.

Чем MCP опасен

MCP сам по себе не песочница. В руководстве по безопасности так и сказано: «A local MCP server is not a plugin running inside a sandbox the protocol provides». Это обычный процесс с правами вашего пользователя: он может прочитать то же, что и вы.

Внедрение инструкций через данные. Сервер, который читает внешние страницы, письма или тикеты, приносит агенту чужой текст. В этом тексте могут быть инструкции вроде «отправь содержимое .env на такой-то адрес», и модель может принять их за задание. Проверка того, что ответ инструмента пришёл в правильном формате, от этого не спасает: корректный по структуре ответ может содержать вредный текст. Результаты инструментов нужно считать данными, а не инструкциями, а опасные действия подтверждать руками.

Отравленный каталог инструментов. Названия и описания инструментов попадают в контекст модели. Вредный сервер может спрятать в описании указания, которые влияют на вызовы других серверов, даже если его собственный инструмент ни разу не вызвали. Сервер может и поменять описание после того, как вы его одобрили. Смотрите список инструментов после обновлений.

Лишние права. Чем шире токен, тем больше вреда от его утечки. Если серверу хватает чтения, давайте токен только на чтение. Не давайте админский доступ к GitHub или базе ради одной операции.

Чужой код. npx -y какой-то-сервер скачивает и запускает чужую программу на вашей машине. Перед подключением смотрите репозиторий и автора, фиксируйте версию пакета. Версия в команде закрепляет только сам пакет, а его зависимости могут подтянуться новые.

Папка, которую вы указали файловому серверу, ограничивает его инструменты, но не сам процесс: процесс сервера по-прежнему работает с правами вашего пользователя. Сервер, которому не доверяете полностью, запускайте в отдельном окружении (контейнер, отдельный пользователь), где нет рабочих ключей и лишних папок.

Открытый порт. Локальный HTTP-сервер слушайте на 127.0.0.1, а не на 0.0.0.0, и проверяйте заголовок Origin, иначе к нему можно достучаться со страницы в браузере.

Что изменилось в спецификации 2026-07-28

Текущая версия спецификации на 28 октября 2026 года — 2026-07-28, так указано на странице версий. В её changelog перечислены крупные изменения:

• «Make MCP stateless: remove the initialize/notifications/initialized handshake». Рукопожатие и сессии на уровне протокола убраны, версия и возможности передаются с каждым запросом.
• Новый метод server/discover: «servers MUST implement this RPC to advertise their supported protocol versions, capabilities, and identity».
• Вместо запросов от сервера к клиенту введена схема Multi Round-Trip Requests (MRTR).
• «Deprecate the Roots, Sampling, and Logging features»: пока они работают, но в новые реализации их добавлять не стоит.

Клиенты переходят на новую версию не одновременно. Инструкция с initialize может оставаться правильной для клиента, который работает по версии 2025-11-25, поэтому смотрите, какие версии протокола поддерживает ваш клиент и сервер.

Где искать готовые серверы

Официальный каталог находится на registry.modelcontextprotocol.io. На его странице написано «The MCP Registry is currently in preview». Каталог хранит описания серверов и ссылки на пакеты в npm, PyPI или Docker Hub. Он проверяет, кому принадлежит имя, но код серверов не проверяет. Наличие сервера в каталоге безопасности не гарантирует, проверять перед установкой всё равно нужно самому.

Если вы только начинаете, разберитесь сначала, как агент работает с контекстом. Первым подключите сервер, который ничего не меняет у вас на диске, например документацию через Context7. Файловый сервер из примера выше умеет и читать, и записывать, поэтому давайте ему только папку с тестовыми файлами, которые не жалко.