В последние годы разработка с использованием ИИ совершила качественный скачок: от простых чат-ботов, генерирующих изолированные фрагменты кода, мы перешли к полноценным автономным агентам. Одним из главных технологических изменений, закрепивших этот переход, стал Model Context Protocol (MCP) — открытый стандарт, представленный компанией Anthropic в конце 2024 года.
Если говорить метафорически, MCP — это разъем USB-C для систем искусственного интеллекта. Подобно тому как USB-C стандартизировал подключение периферийных устройств к компьютерам, MCP стандартизировал подключение LLM к внешним источникам данных, API, базам данных и инструментам разработки.
В этой статье мы подробно разберем теорию MCP, изучим архитектурные особенности протокола, а затем погрузимся в детальное практическое руководство по интеграции MCP-серверов в Claude Code — агентный CLI-инструмент от Anthropic. Вас ждут реальные примеры конфигурации, разбор архитектуры собственного сервера, неочевидные лайфхаки по оптимизации контекста и обзор самых полезных серверов экосистемы.
Часть 1. Теория Model Context Protocol (MCP)
Проблема интеграции контекста
До появления MCP каждый разработчик AI-приложений (будь то плагины для VS Code, поисковые ассистенты или внутренние корпоративные чат-боты) сталкивался с проблемой «зоопарка интеграций». Чтобы дать модели доступ к Jira, Postgres, Slack и Notion, приходилось писать уникальный код сопряжения для каждого инструмента. При изменении API или переходе на другую модель архитектура ломалась.
MCP решает эту проблему разделением слоев:
- Модель / Клиент общается по единому стандартизированному протоколу.
- Сервер (MCP Server) предоставляет данные и инструменты в строго определенном формате JSON-RPC.
Разработчику инструмента достаточно написать MCP-сервер один раз, чтобы его функции стали доступны в любом совместимом клиенте: Claude Desktop, Cursor, Windsurf или Claude Code.
Архитектура протокола
Архитектурная схема MCP строится на взаимодействии трех ключевых ролей:
┌──────────────────────────────────────────────┐
│ AI Host │
│ (Claude Code, Claude Desktop, Cursor) │
└──────────────────────┬───────────────────────┘
│ (Встраивает клиента)
▼
┌──────────────────────────────────────────────┐
│ MCP Client │
└──────────────────────┬───────────────────────┘
│ (Транспорт: stdio / http / sse)
▼
┌──────────────────────────────────────────────┐
│ MCP Server │
└──────────────────────┬───────────────────────┘
│ (Локальный доступ / API)
▼
┌──────────────────────────────────────────────┐
│ Источники данных & Инструменты │
│ (Базы данных, GitHub, Slack, CLI) │
└──────────────────────────────────────────────┘
- Host (Хост): Приложение, в котором пользователь взаимодействует с ИИ (например, терминал Claude Code). Хост инициализирует MCP-клиент.
- Client (Клиент): Компонент внутри хост-приложения, который устанавливает и поддерживает безопасное соединение с сервером.
- Server (Сервер): Легковесный процесс (локальный или удаленный), который подключается к конечным сервисам и описывает свои возможности клиенту.
Способы передачи данных (Транспорты)
Для взаимодействия клиента и сервера протокол MCP предусматривает разные механизмы транспорта:
- stdio: Клиент запускает сервер как дочерний процесс операционной системы и общается с ним через стандартные потоки ввода-вывода (
stdin/stdout). Это основной и наиболее безопасный вариант для работы с локальными инструментами на машине разработчика. - http / sse (Server-Sent Events): Сервер работает как самостоятельный веб-сервис. Клиент отправляет POST-запросы, а сервер асинхронно передает обновления через SSE-канал. Подходит для облачных инструментов и командных сред.
- WebSocket (ws): Поддерживает постоянное двунаправленное соединение. Применяется для удаленных серверов, которые должны отправлять события (push-уведомления) хосту без явного запроса со стороны клиента.
Три столпа возможностей MCP
Любой MCP-сервер может предоставлять клиенту три типа сущностей:
- Ресурсы (Resources): Доступные только для чтения данные. Это могут быть файлы локальной системы, таблицы БД или ответы API, оформленные в виде стандартизованных URIs (например,
postgres://db/users/schema). - Инструменты (Tools): Исполняемые функции, которые ИИ-модель может вызывать для совершения активных действий (создание PR, отправка сообщения, запуск сборки). Запуск инструментов обычно требует подтверждения пользователя из соображений безопасности.
- Промпты (Prompts): Предопределенные шаблоны системных или пользовательских промптов со встроенным контекстом (например, шаблон для код-ревью или генерации документации).
Часть 2. Claude Code и его интеграция с MCP
Claude Code — это агентный AI-помощник командной строки (CLI), созданный Anthropic. В отличие от обычных чатов, Claude Code работает непосредственно в вашем рабочем окружении: он анализирует структуру каталогов, вносит правки в файлы, запускает сборку проекта и прогоняет тесты.
MCP играет в Claude Code критически важную роль. По умолчанию возможности Claude Code ограничены локальной песочницей проекта. Подключая MCP-серверы, вы расширяете возможности агента, позволяя ему:
- Читать задачи непосредственно из Jira или Linear.
- Изучать актуальную внешнюю документацию без ручного копирования её страниц.
- Выполнять SQL-запросы к рабочей базе данных для диагностики ошибок.
- Управлять пул-реквестами на GitHub.
Области видимости (Scopes) конфигурации
Claude Code поддерживает три уровня конфигурации MCP-серверов, что позволяет гибко разделять личные инструменты и настройки команды:
| Область видимости (Scope) | Файл конфигурации | Описание | Командный доступ (Git) |
|---|---|---|---|
| User (Глобальная) | ~/.claude.json | Серверы доступны для Claude Code во всех проектах на данной машине. Подходит для личных ключей и глобальных утилит. | Нет |
| Project (Проектная) | .mcp.json (в корне проекта) | Серверы запускаются только тогда, когда Claude Code открыт в этой директории. Конфиг можно коммитить в репозиторий. | Да (через систему контроля версий) |
| Local (Локальная) | Внутреннее хранилище или привязка к пути в ~/.claude.json | Личные переопределения параметров для конкретного проекта (например, локальный путь к БД). | Нет |
Часть 3. Практическое руководство: Подключение и управление
Базовые команды CLI для работы с MCP
Управление MCP-серверами в Claude Code осуществляется с помощью семейства команд claude mcp. Основной набор команд выглядит следующим образом:
# Вывести список всех настроенных серверов и их статусы
claude mcp list
# Получить детальную информацию по конкретному серверу
claude mcp get <server-name>
# Удалить сервер из конфигурации
claude mcp remove <server-name>Для проверки состояния серверов непосредственно во время интерактивной сессии общения с Claude Code используется косая черта:
/mcpЭта команда открывает интерактивную панель, где показан список подключенных серверов, количество доступных инструментов и их текущая работоспособность.
Примеры добавления серверов
Вариант 1. Локальный процесс (stdio транспорт)
Для примера подключим официальный GitHub MCP-сервер. В качестве транспорта по умолчанию используется stdio (клиент сам запускает процесс через указанную утилиту):
# Добавление сервера на уровне пользователя (глобально)
claude mcp add github-mcp -s user \
-e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
-- npx -y @modelcontextprotocol/server-githubВажно: Символ двойного дефиса (
--) отделяет параметры конфигурации самого Claude Code от команды запуска целевого сервера. Все, что идет после--, будет выполнено в терминале при старте сервера.
Вариант 2. Удаленный сервер (HTTP/SSE транспорт)
Многие современные SaaS-сервисы хостят свои MCP-серверы удаленно. Для подключения такого сервера используется транспорт http:
claude mcp add sentry --transport http https://mcp.sentry.dev/mcpПосле добавления команда claude mcp list покажет статус ! Needs authentication. Чтобы завершить процесс настройки:
- Запустите сессию:
claude. - Введите
/mcp. - Выберите сервер
sentryи нажмите Authenticate. - Claude Code откроет окно браузера для авторизации через OAuth. После успешного входа статус изменится на
connected.
Тонкая настройка: Редактирование JSON-конфигурации напрямую
Хотя CLI-команды удобны, при сложных конфигурациях со множеством переменных окружения использовать интерактивный мастер может быть затруднительно. Альтернативный путь — редактировать файлы конфигурации вручную.
Создайте или откройте файл конфигурации (например, .mcp.json в корне вашего проекта для командной работы):
{
"mcpServers": {
"sqlite-db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sqlite",
"--db-path",
"./data/production.sqlite"
]
},
"web-search": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-brave-search"
],
"env": {
"BRAVE_API_KEY": "your_api_key_here"
}
}
}
}После сохранения файла запустите Claude Code в этой директории. Утилита автоматически обнаружит изменения, запросит подтверждение на запуск новых проектных серверов и инициализирует их.
Часть 4. Создание собственного MCP-сервера с нуля
Рассмотрим процесс создания кастомного MCP-сервера на языке TypeScript/Node.js. Наш сервер будет предоставлять простой инструмент: calculate_loc (подсчет строк кода в переданном тексте).
Шаг 1. Инициализация проекта
Создайте новую директорию и инициализируйте Node.js проект:
mkdir mcp-metrics-server
cd mcp-metrics-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install typescript @types/node --save-dev
npx tsc --initНастройте tsconfig.json, указав целевой стандарт ES2022 и модули NodeNext:
{
"compilerOptions": {
"target": "es2022",
"module": "nodenext",
"moduleResolution": "nodenext",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true
}
}Добавьте "type": "module" в ваш package.json.
Шаг 2. Написание кода сервера
Создайте файл src/index.ts и импортируйте компоненты SDK:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Инициализируем MCP Сервер
const server = new Server(
{
name: "metrics-analyzer",
version: "1.0.0",
},
{
capabilities: {
tools: {}, // Объявляем поддержку инструментов
},
}
);
// Регистрируем доступные инструменты
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "calculate_loc",
description: "Подсчитывает количество строк кода (Lines of Code) в переданном тексте.",
inputSchema: {
type: "object",
properties: {
code: {
type: "string",
description: "Исходный код для анализа",
},
},
required: ["code"],
},
},
],
};
});
// Обрабатываем вызовы инструментов
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "calculate_loc") {
const code = request.params.arguments?.code as string;
if (!code) {
throw new Error("Параметр 'code' является обязательным.");
}
const lines = code.split("\n");
const totalLines = lines.length;
const emptyLines = lines.filter(line => line.trim() === "").length;
const codeLines = totalLines - emptyLines;
return {
content: [
{
type: "text",
text: JSON.stringify({
totalLines,
emptyLines,
codeLines,
}, null, 2),
},
],
};
}
throw new Error(`Инструмент ${request.params.name} не найден.`);
});
// Запускаем сервер с использованием транспорта STDIO
async function run() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCP Metrics Server успешно запущен через STDIO транспорт!");
}
run().catch((error) => {
console.error("Ошибка при запуске MCP сервера:", error);
process.exit(1);
});Шаг 3. Сборка и интеграция в Claude Code
Скомпилируйте TypeScript код:
npx tscТеперь подключите свежесобранный сервер к вашему Claude Code. Используем глобальный scope и абсолютный путь к скомпилированному файлу:
claude mcp add metrics-analyzer -s user -- node /absolute/path/to/mcp-metrics-server/build/index.jsУбедитесь, что сервер подключился, выполнив claude mcp list. В интерактивной сессии вы можете спросить: «Проанализируй этот файл и посчитай количество строк кода с помощью кастомного анализатора». Claude Code самостоятельно выберет созданный вами инструмент calculate_loc и отобразит результат.
Часть 5. Лайфхаки, оптимизация и безопасность
Опыт использования MCP-серверов в реальных проектах выявил ряд нюансов, о которых важно помнить для поддержания стабильности и контроля расходов.
1. Борьба с «раздуванием контекста» (Token Bloat)
Одна из основных сложностей при работе с MCP в Claude Code — потребление токенов. Каждый подключенный сервер при инициализации сессии передает клиенту схемы всех своих инструментов, ресурсов и промптов.
- Среднестатистический инструмент с подробным описанием параметров расходует от 500 до 1500 токенов в системном промпте.
- Если у вас запущено 5 крупных серверов (например, Playwright, SQLite, GitHub, Sentry, AWS), содержащих суммарно 50–70 инструментов, то еще до того, как вы напишете первый символ вашего запроса, Claude Code израсходует от 40 000 до 75 000 токенов контекста.
Это напрямую влияет на стоимость запросов и может снижать качество работы модели из-за обилия нерелевантных параметров.
Рекомендации:
- Используйте Project Scope (
-s project): Избегайте установки всех серверов глобально. Оставляйте глобально только то, что используете ежедневно (например, веб-поиск). Инструменты для работы со специфичными базами данных или тестированием держите строго внутри конкретных репозиториев в файле.mcp.json. - Применяйте специализированные утилиты управления: Инструменты вроде
McPick(или аналогичные скрипты автоматизации) позволяют быстро включать и выключать нужные MCP-серверы перед началом сессии в зависимости от текущей задачи.
2. Ограничения безопасности
Предоставление агенту прямого доступа к терминалу и внешним ресурсам требует внимания к безопасности. При использовании серверов, извлекающих контент из интернета (веб-скрейперы, поисковики), существует угроза непрямых инъекций промптов (Indirect Prompt Injection). Попадание скрытых инструкций со сторонней веб-страницы в контекст Claude может заставить агента выполнить нежелательную команду на вашем компьютере.
Правила безопасной эксплуатации:
- Используйте Read-Only роли для СУБД: При подключении к Postgres или MySQL через MCP всегда создавайте отдельного пользователя базы данных, ограниченного исключительно правами
SELECTдля целевых схем. - Доверяйте проверенным вендорам: По возможности используйте официальные и поддерживаемые сообществом серверы из официального реестра Anthropic (Anthropic Directory).
3. Особенности логирования в STDIO-транспорте
Поскольку обмен сообщениями между Claude Code и сервером происходит строго в формате JSON-RPC через стандартный вывод (stdout), любая сторонняя строчка, отправленная через обычный console.log() или print(), нарушает структуру протокола. Клиент может аварийно завершить работу с ошибкой парсинга JSON.
Как правильно логировать:
- Направляйте все отладочные сообщения исключительно в поток ошибок
stderr. - В Node.js:
console.error("My debug message"). - В Python:
print("My debug message", file=sys.stderr).
Часть 6. Обзор востребованных MCP-серверов
В экосистеме MCP доступно множество готовых серверов. Ниже представлены наиболее примечательные инструменты:
- GitHub MCP Server: Предоставляет Claude доступ к API репозиториев GitHub. Позволяет искать файлы, просматривать коммиты, создавать ветки, комментировать пул-реквесты и управлять тикетами.
Подключение:claude mcp add github -- npx -y @modelcontextprotocol/server-github. - Brave Search / Fetch: Открывает ассистенту доступ в интернет. Brave Search выполняет поисковые запросы, а Fetch скачивает и очищает от лишнего разметку целевых веб-страниц, превращая их в чистый Markdown.
Подключение:claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search. - PostgreSQL / SQLite Tools: Подключается к указанной СУБД. Модель может запрашивать схему таблиц, генерировать и безопасно выполнять SQL-запросы.
Подключение (SQLite):claude mcp add sqlite-db -- npx -y @modelcontextprotocol/server-sqlite --db-path ./my-db.sqlite. - Playwright (Browser Automation): Позволяет Claude Code управлять безголовым (headless) браузером Chromium, переходить по ссылкам, нажимать кнопки, заполнять формы и делать скриншоты страниц.
- Context7: Специализированный сервер для интеллектуального управления кэшем внешней документации. Он динамически подгружает только нужные фрагменты документации под конкретный промпт, минимизируя трату токенов контекста.
Интеграция Model Context Protocol в Claude Code расширяет возможности инструмента командной строки, помогая объединить текстовый редактор с внешними инструментами вашей рабочей среды.
Для стабильной работы достаточно придерживаться простой гигиены использования протокола:
- Держите проектные настройки в
.mcp.jsonи коммитьте их для всей команды. - Следите за токенами через
/mcpи отключайте неиспользуемые серверы, чтобы избегать раздувания контекста. - Ограничивайте права доступа к базам данных и файловым системам до минимально необходимых.
