Подключение MCP-серверов к плагину

Текст

---
name: mcp-integration
description: Этот скилл следует использовать, когда пользователь просит «добавить MCP-сервер», «интегрировать MCP», «настроить MCP в плагине», «использовать .mcp.json», «настроить Model Context Protocol», «подключить внешний сервис», упоминает «${CLAUDE_PLUGIN_ROOT} с MCP» или обсуждает типы MCP-серверов (SSE, stdio, HTTP, WebSocket). Даёт исчерпывающие рекомендации по интеграции серверов Model Context Protocol в плагины Claude Code для подключения внешних инструментов и сервисов.
version: 0.1.0
---

Интеграция MCP в плагины Claude Code

Обзор

Model Context Protocol (MCP) позволяет плагинам Claude Code интегрироваться с внешними сервисами и API, предоставляя структурированный доступ к инструментам. Используй интеграцию MCP, чтобы открыть возможности внешних сервисов как инструменты внутри Claude Code.

Основные возможности:

• Подключаться к внешним сервисам (базы данных, API, файловые системы)
• Предоставлять 10+ связанных инструментов от одного сервиса
• Обрабатывать OAuth и сложные потоки аутентификации
• Поставлять MCP-серверы вместе с плагинами для автоматической настройки

Способы настройки MCP-сервера

Плагины могут включать MCP-серверы двумя способами:

Способ 1: отдельный .mcp.json (рекомендуется)

Создай .mcp.json в корне плагина:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Преимущества:

• Чёткое разделение ответственности
• Проще поддерживать
• Лучше подходит для нескольких серверов

Способ 2: прямо в plugin.json

Добавь поле mcpServers в plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Преимущества:

• Один файл конфигурации
• Подходит для простых плагинов с одним сервером

Типы MCP-серверов

stdio (локальный процесс)

Запускает локальные MCP-серверы как дочерние процессы. Лучше всего для локальных инструментов и собственных серверов.

Конфигурация:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

Случаи применения:

• Доступ к файловой системе
• Подключения к локальным базам данных
• Собственные MCP-серверы
• MCP-серверы, упакованные как пакеты NPM

Управление процессом:

• Claude Code запускает процесс и управляет им
• Обмен идёт через stdin/stdout
• Завершается при выходе из Claude Code

SSE (Server-Sent Events)

Подключение к размещённым MCP-серверам с поддержкой OAuth. Лучше всего для облачных сервисов.

Конфигурация:

{
  "hosted-service": {
    "type": "sse",
    "url": "https://mcp.example.com/sse"
  }
}

Случаи применения:

• Официальные размещённые MCP-серверы (Asana, GitHub и др.)
• Облачные сервисы с MCP-конечными точками
• Аутентификация на основе OAuth
• Не нужна локальная установка

Аутентификация:

• Потоки OAuth обрабатываются автоматически
• Пользователю предлагается войти при первом использовании
• Токенами управляет Claude Code

HTTP (REST API)

Подключение к RESTful MCP-серверам с аутентификацией по токену.

Конфигурация:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

Случаи применения:

• MCP-серверы на основе REST API
• Аутентификация по токену
• Собственные серверные части на основе API
• Взаимодействие без сохранения состояния

WebSocket (реальное время)

Подключение к MCP-серверам WebSocket для двусторонней связи в реальном времени.

Конфигурация:

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Случаи применения:

• Потоковая передача данных в реальном времени
• Постоянные соединения
• Push-уведомления от сервера
• Требования к низкой задержке

Подстановка переменных окружения

Все конфигурации MCP поддерживают подстановку переменных окружения:

${CLAUDE_PLUGIN_ROOT} — каталог плагина (всегда используй для переносимости):

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

Пользовательские переменные окружения — из оболочки пользователя:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

Лучшая практика: документируй все необходимые переменные окружения в README плагина.

Именование инструментов MCP

Когда MCP-серверы предоставляют инструменты, к их именам автоматически добавляется префикс:

Формат: mcp__plugin_<plugin-name>_<server-name>__<tool-name>

Пример:

• Плагин: asana
• Сервер: asana
• Инструмент: create_task
• Полное имя: mcp__plugin_asana_asana__asana_create_task

Использование инструментов MCP в командах

Заранее разреши конкретные инструменты MCP в шапке команды:

---
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

Подстановочный знак (используй умеренно):

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

Лучшая практика: ради безопасности разрешай заранее конкретные инструменты, а не подстановочные знаки.

Управление жизненным циклом

Автоматический запуск:

• MCP-серверы запускаются при включении плагина
• Соединение устанавливается до первого использования инструмента
• Для изменения конфигурации требуется перезапуск

Жизненный цикл:

1. Плагин загружается
2. Разбирается конфигурация MCP
3. Запускается процесс сервера (stdio) или устанавливается соединение (SSE/HTTP/WS)
4. Инструменты обнаруживаются и регистрируются
5. Инструменты доступны как mcp__plugin_...__...

Просмотр серверов: Команда /mcp показывает все серверы, включая предоставленные плагинами.

Схемы аутентификации

OAuth (SSE/HTTP)

OAuth автоматически обрабатывается Claude Code:

{
  "type": "sse",
  "url": "https://mcp.example.com/sse"
}

Пользователь входит в браузере при первом использовании. Дополнительная настройка не нужна.

На основе токенов (заголовки)

Статические токены или токены из переменных окружения:

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Документируй необходимые переменные окружения в README.

Переменные окружения (stdio)

Передавай конфигурацию MCP-серверу:

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

Схемы интеграции

Схема 1: простая обёртка инструмента

Команды используют инструменты MCP с участием пользователя:

# Команда: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

Шаги:
1. Собери у пользователя сведения об элементе
2. Используй mcp__plugin_name_server__create_item
3. Подтверди создание

Применяй для: добавления проверки или предварительной обработки перед вызовами MCP.

Схема 2: автономный агент

Агенты используют инструменты MCP самостоятельно:

# Агент: data-analyzer.md

Процесс анализа:
1. Запроси данные через mcp__plugin_db_server__query
2. Обработай и проанализируй результаты
3. Составь отчёт с инсайтами

Применяй для: многошаговых рабочих процессов MCP без участия пользователя.

Схема 3: плагин с несколькими серверами

Интегрируй несколько MCP-серверов:

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "jira": {
    "type": "sse",
    "url": "https://mcp.jira.com/sse"
  }
}

Применяй для: рабочих процессов, охватывающих несколько сервисов.

Лучшие практики безопасности

Используй HTTPS/WSS

Всегда используй защищённые соединения:

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

Управление токенами

ДЕЛАЙ:

• ✅ Используй переменные окружения для токенов
• ✅ Документируй необходимые переменные окружения в README
• ✅ Доверяй аутентификацию потоку OAuth

НЕ ДЕЛАЙ:

• ❌ Не прописывай токены жёстко в конфигурации
• ❌ Не коммить токены в git
• ❌ Не публикуй токены в документации

Ограничение разрешений

Разрешай заранее только необходимые инструменты MCP:

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

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

Сбои соединения

Обрабатывай недоступность MCP-сервера:

• Предусмотри в командах запасное поведение
• Сообщай пользователю о проблемах соединения
• Проверь адрес сервера и конфигурацию

Ошибки вызова инструментов

Обрабатывай неудачные операции MCP:

• Проверяй входные данные перед вызовом инструментов MCP
• Давай понятные сообщения об ошибках
• Проверь ограничения частоты запросов и квоты

Ошибки конфигурации

Проверяй конфигурацию MCP:

• Проверь связь с сервером при разработке
• Проверь синтаксис JSON
• Проверь необходимые переменные окружения

Соображения о производительности

Ленивая загрузка

MCP-серверы подключаются по требованию:

• Не все серверы подключаются при запуске
• Первое использование инструмента запускает соединение
• Пулом соединений управляет система автоматически

Пакетная обработка

По возможности объединяй похожие запросы:

# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)

# Avoid: Many individual queries
for id in task_ids:
    task = get_task(id)

Тестирование интеграции MCP

Локальное тестирование

1. Настрой MCP-сервер в .mcp.json
2. Установи плагин локально (.claude-plugin/)
3. Выполни /mcp, чтобы убедиться, что сервер появился
4. Проверь вызовы инструментов в командах
5. Проверь журналы claude --debug на проблемы с соединением

Чек-лист проверки

• [ ] Конфигурация MCP — корректный JSON
• [ ] Адрес сервера верен и доступен
• [ ] Необходимые переменные окружения задокументированы
• [ ] Инструменты появляются в выводе /mcp
• [ ] Аутентификация работает (OAuth или токены)
• [ ] Вызовы инструментов из команд проходят успешно
• [ ] Случаи ошибок обрабатываются корректно

Отладка

Включи журнал отладки

claude --debug

Ищи:

• Попытки подключения к MCP-серверу
• Журналы обнаружения инструментов
• Потоки аутентификации
• Ошибки вызова инструментов

Типичные проблемы

Сервер не подключается:

• Проверь, что адрес верный
• Убедись, что сервер запущен (stdio)
• Проверь сетевое соединение
• Просмотри конфигурацию аутентификации

Инструменты недоступны:

• Убедись, что сервер успешно подключился
• Проверь, что имена инструментов совпадают точно
• Выполни /mcp, чтобы увидеть доступные инструменты
• Перезапусти Claude Code после изменения конфигурации

Аутентификация не проходит:

• Очисти сохранённые токены авторизации
• Пройди аутентификацию заново
• Проверь области действия и разрешения токена
• Проверь, что переменные окружения заданы

Краткая справка

Типы MCP-серверов

Чек-лист конфигурации

• [ ] Указан тип сервера (stdio/SSE/HTTP/ws)
• [ ] Заполнены поля, специфичные для типа (command или url)
• [ ] Настроена аутентификация
• [ ] Переменные окружения задокументированы
• [ ] Используются HTTPS/WSS (а не HTTP/WS)
• [ ] Для путей используется ${CLAUDE_PLUGIN_ROOT}

Лучшие практики

ДЕЛАЙ:

• ✅ Используй ${CLAUDE_PLUGIN_ROOT} для переносимых путей
• ✅ Документируй необходимые переменные окружения
• ✅ Используй защищённые соединения (HTTPS/WSS)
• ✅ Разрешай заранее конкретные инструменты MCP в командах
• ✅ Проверяй интеграцию MCP перед публикацией
• ✅ Корректно обрабатывай ошибки соединения и инструментов

НЕ ДЕЛАЙ:

• ❌ Не прописывай абсолютные пути жёстко
• ❌ Не коммить учётные данные в git
• ❌ Не используй HTTP вместо HTTPS
• ❌ Не разрешай заранее все инструменты подстановочными знаками
• ❌ Не пропускай обработку ошибок
• ❌ Не забывай документировать настройку

Дополнительные ресурсы

Справочные файлы

Подробную информацию см. в:

• **references/server-types.md** — подробный разбор каждого типа сервера
• **references/authentication.md** — схемы аутентификации и OAuth
• **references/tool-usage.md** — использование инструментов MCP в командах и агентах

Примеры конфигураций

Рабочие примеры в examples/:

• **stdio-server.json** — локальный MCP-сервер stdio
• **sse-server.json** — размещённый сервер SSE с OAuth
• **http-server.json** — REST API с аутентификацией по токену

Внешние ресурсы

• Официальная документация MCP: https://modelcontextprotocol.io/
• Документация MCP для Claude Code: https://docs.claude.com/en/docs/claude-code/mcp
• MCP SDK: @modelcontextprotocol/sdk
• Тестирование: используй claude --debug и команду /mcp

Порядок реализации

Чтобы добавить интеграцию MCP в плагин:

1. Выбери тип MCP-сервера (stdio, SSE, HTTP, ws)
2. Создай .mcp.json в корне плагина с конфигурацией
3. Используй ${CLAUDE_PLUGIN_ROOT} во всех ссылках на файлы
4. Задокументируй необходимые переменные окружения в README
5. Проверь локально командой /mcp
6. Заранее разреши инструменты MCP в нужных командах
7. Настрой аутентификацию (OAuth или токены)
8. Проверь случаи ошибок (сбои соединения, ошибки аутентификации)
9. Задокументируй интеграцию MCP в README плагина

Для собственных/локальных серверов делай ставку на stdio, для размещённых сервисов с OAuth — на SSE.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev/skills/mcp-integration, лицензия Apache-2.0. Изменения: перевод на русский язык.