MCP серверы с Qwen Code

Этот документ содержит руководство по настройке и использованию Model Context Protocol (MCP) серверов с Qwen Code.

Что такое MCP сервер?

MCP сервер — это приложение, которое предоставляет инструменты и ресурсы для CLI через Model Context Protocol, позволяя ему взаимодействовать с внешними системами и источниками данных. MCP серверы выступают в роли моста между моделью и вашей локальной средой или другими сервисами, например API.

MCP сервер позволяет CLI:

Обнаруживать инструменты: Получать список доступных инструментов, их описания и параметры через стандартизированные схемы.
Выполнять инструменты: Вызывать конкретные инструменты с заданными аргументами и получать структурированные ответы.
Доступ к ресурсам: Читать данные из определённых ресурсов (хотя CLI в основном ориентирован на выполнение инструментов).

С помощью MCP сервера вы можете расширить возможности CLI, чтобы выполнять действия, выходящие за рамки встроенных функций, например взаимодействовать с базами данных, API, пользовательскими скриптами или специализированными рабочими процессами.

Архитектура основной интеграции

Qwen Code интегрируется с MCP-серверами через сложную систему обнаружения и выполнения, встроенную в основной пакет (packages/core/src/tools/):

Слой обнаружения (`mcp-client.ts`)

Процесс обнаружения координируется функцией discoverMcpTools(), которая:

Перебирает настроенные серверы из конфигурации mcpServers в вашем settings.json
Устанавливает соединения с использованием соответствующих транспортных механизмов (Stdio, SSE или Streamable HTTP)
Получает определения инструментов с каждого сервера по протоколу MCP
Очищает и проверяет схемы инструментов на совместимость с Qwen API
Регистрирует инструменты в глобальном реестре инструментов с разрешением конфликтов

Execution Layer (`mcp-tool.ts`)

Каждый обнаруженный MCP tool оборачивается в экземпляр DiscoveredMCPTool, который:

Обрабатывает логику подтверждения на основе настроек доверия сервера и пользовательских предпочтений
Управляет выполнением tool’а путем вызова MCP сервера с правильными параметрами
Обрабатывает ответы как для контекста LLM, так и для отображения пользователю
Сохраняет состояние подключения и обрабатывает таймауты

Transport Mechanisms

CLI поддерживает три типа транспорта MCP:

Stdio Transport: Запускает subprocess и общается через stdin/stdout
SSE Transport: Подключается к endpoint’ам Server-Sent Events
Streamable HTTP Transport: Использует HTTP streaming для коммуникации

Как настроить свой MCP сервер

Qwen Code использует конфигурацию mcpServers в вашем файле settings.json, чтобы находить и подключаться к MCP серверам. Эта конфигурация поддерживает несколько серверов с разными механизмами транспорта.

Настройка MCP-сервера в settings.json

Вы можете настроить MCP-серверы глобально в файле ~/.qwen/settings.json или в корневой директории вашего проекта, создав или открыв файл .qwen/settings.json. Внутри файла добавьте блок конфигурации mcpServers.

Структура конфигурации

Добавьте объект mcpServers в ваш файл settings.json:


{ ...файл содержит другие объекты конфигурации
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Свойства конфигурации

Каждая конфигурация сервера поддерживает следующие свойства:

Обязательно (одно из следующих)

command (string): Путь к исполняемому файлу для транспорта Stdio
url (string): URL endpoint для SSE (например, "http://localhost:8080/sse")
httpUrl (string): URL endpoint для HTTP streaming

Необязательные параметры

args (string[]): Аргументы командной строки для транспорта Stdio
headers (object): Пользовательские HTTP-заголовки при использовании url или httpUrl
env (object): Переменные окружения для процесса сервера. Значения могут ссылаться на переменные окружения с использованием синтаксиса $VAR_NAME или ${VAR_NAME}
cwd (string): Рабочая директория для транспорта Stdio
timeout (number): Таймаут запроса в миллисекундах (по умолчанию: 600,000 мс = 10 минут)
trust (boolean): Если true, отключает все подтверждения вызовов инструментов для этого сервера (по умолчанию: false)
includeTools (string[]): Список названий инструментов, которые нужно подключить с этого MCP-сервера. Если указано, то будут доступны только перечисленные здесь инструменты (whitelist-поведение). Если не указано, по умолчанию активны все инструменты сервера.
excludeTools (string[]): Список названий инструментов, которые нужно исключить с этого MCP-сервера. Указанные здесь инструменты будут недоступны модели, даже если сервер их предоставляет. Примечание: excludeTools имеет приоритет над includeTools — если инструмент присутствует в обоих списках, он будет исключён.

Поддержка OAuth для удаленных MCP серверов

Qwen Code поддерживает аутентификацию OAuth 2.0 для удаленных MCP серверов с использованием транспортов SSE или HTTP. Это позволяет безопасно получать доступ к MCP серверам, которые требуют аутентификации.

Автоматическое обнаружение OAuth

Для серверов, которые поддерживают автоматическое обнаружение OAuth, вы можете опустить конфигурацию OAuth и позволить CLI обнаружить её автоматически:


{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

CLI автоматически:

Определяет, когда сервер требует аутентификацию через OAuth (ответы 401)
Обнаруживает OAuth эндпоинты из метаданных сервера
Выполняет динамическую регистрацию клиента, если это поддерживается
Обрабатывает OAuth flow и управление токенами

Поток аутентификации

При подключении к серверу с поддержкой OAuth:

Первая попытка подключения завершается ошибкой 401 Unauthorized
Обнаружение OAuth находит endpoint’ы авторизации и получения токенов
Открывается браузер для аутентификации пользователя (требуется доступ к локальному браузеру)
Authorization code обменивается на access token’ы
Токены безопасно сохраняются для последующего использования
Повторная попытка подключения проходит успешно с действующими токенами

Требования к перенаправлению браузера

Важно: Для аутентификации через OAuth ваша локальная машина должна:

Открывать веб-браузер для аутентификации
Принимать перенаправления по адресу http://localhost:7777/oauth/callback

Эта функция не будет работать в:

Headless-средах без доступа к браузеру
Удалённых SSH-сессиях без X11 forwarding
Контейнеризованных средах без поддержки браузера

Управление OAuth-аутентификацией

Используйте команду /mcp auth для управления OAuth-аутентификацией:


 
# Показать список серверов, требующих аутентификацию
/mcp auth


# Аутентификация на определенном сервере
/mcp auth serverName
 
# Повторная аутентификация при истечении срока действия токенов
/mcp auth serverName

Свойства конфигурации OAuth

enabled (boolean): Включить OAuth для этого сервера
clientId (string): Идентификатор клиента OAuth (необязательно при динамической регистрации)
clientSecret (string): Секрет клиента OAuth (необязательно для публичных клиентов)
authorizationUrl (string): Конечная точка авторизации OAuth (автоматически определяется, если не указана)
tokenUrl (string): Конечная точка токена OAuth (автоматически определяется, если не указана)
scopes (string[]): Требуемые scope’ы OAuth
redirectUri (string): Пользовательский URI перенаправления (по умолчанию http://localhost:7777/oauth/callback)
tokenParamName (string): Имя параметра запроса для токенов в URL SSE
audiences (string[]): Аудитории, для которых токен действителен



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

OAuth токены автоматически:

- **Безопасно хранятся** в `~/.qwen/mcp-oauth-tokens.json`
- **Обновляются** при истечении срока действия (если доступны refresh токены)
- **Проверяются** перед каждой попыткой подключения
- **Очищаются** при недействительности или истечении срока действия

#### Тип провайдера аутентификации

Вы можете указать тип провайдера аутентификации с помощью свойства `authProviderType`:

- **`authProviderType`** (string): Определяет провайдер аутентификации. Может принимать одно из следующих значений:
  - **`dynamic_discovery`** (по умолчанию): CLI автоматически обнаружит конфигурацию OAuth с сервера.
  - **`google_credentials`**: CLI будет использовать Google Application Default Credentials (ADC) для аутентификации на сервере. При использовании этого провайдера необходимо указать требуемые scopes.

```json
{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

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

Python MCP Server (Stdio)


{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

Node.js MCP Server (Stdio)


{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

Docker-based MCP Server


{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

HTTP-based MCP Server


{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

HTTP-based MCP Server с Custom Headers


{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

MCP Server с фильтрацией инструментов


{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      // "excludeTools": ["dangerous_tool", "file_deleter"],
      "timeout": 30000
    }
  }
}

Подробное описание процесса обнаружения

Когда Qwen Code запускается, он выполняет обнаружение MCP-серверов через следующий детализированный процесс:

1. Итерация по серверам и подключение

Для каждого сконфигурированного сервера в mcpServers:

Начинается отслеживание статуса: Статус сервера устанавливается в CONNECTING
Выбор транспорта: В зависимости от свойств конфигурации:
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
Установка соединения: MCP-клиент пытается установить соединение с заданным таймаутом
Обработка ошибок: Ошибки подключения логируются, а статус сервера устанавливается в DISCONNECTED

2. Обнаружение инструментов

После успешного подключения:

Получение списка инструментов: Клиент вызывает endpoint получения списка инструментов сервера MCP
Валидация схемы: Проверяется объявление функции каждого инструмента
Фильтрация инструментов: Инструменты фильтруются на основе конфигурации includeTools и excludeTools
Очистка имен: Имена инструментов приводятся в соответствие с требованиями Qwen API:
- Недопустимые символы (все, кроме букв, цифр, подчеркивания, точки и дефиса) заменяются на подчеркивание
- Имена длиннее 63 символов обрезаются с заменой средней части (___)

3. Разрешение конфликтов

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

Первый зарегистрированный побеждает: Первый сервер, зарегистрировавший имя инструмента, получает имя без префикса
Автоматическое добавление префикса: Последующие серверы получают имена с префиксом: serverName__toolName
Отслеживание в реестре: Реестр инструментов хранит сопоставления между именами серверов и их инструментами

4. Обработка схем

Схемы параметров инструментов проходят санитизацию для совместимости с API:

Свойства $schema удаляются
additionalProperties вырезаются
anyOf с default теряют значения по умолчанию (совместимость с Vertex AI)
Рекурсивная обработка применяется к вложенным схемам

5. Управление подключениями

После обнаружения:

Постоянные подключения: Серверы, которые успешно зарегистрировали инструменты, сохраняют свои подключения
Очистка: Подключения серверов, не предоставивших рабочих инструментов, закрываются
Обновление статуса: Финальный статус сервера устанавливается как CONNECTED или DISCONNECTED

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

Когда модель решает использовать инструмент MCP, происходит следующий процесс выполнения:

1. Вызов инструмента

Модель генерирует FunctionCall с:

Имя инструмента: Зарегистрированное имя (возможно, с префиксом)
Аргументы: JSON-объект, соответствующий схеме параметров инструмента

2. Процесс подтверждения

Каждый DiscoveredMCPTool реализует сложную логику подтверждения:

Обход на основе доверия


if (this.trust) {
  return false; // Подтверждение не требуется
}

Динамическое разрешение

Система поддерживает внутренние allow-lists для:

На уровне сервера: serverName → Все инструменты с этого сервера считаются доверенными
На уровне инструмента: serverName.toolName → Этот конкретный инструмент считается доверенным

Обработка выбора пользователя

Когда требуется подтверждение, пользователь может выбрать:

Выполнить один раз: Выполнить только в этот раз
Всегда разрешать этот инструмент: Добавить в allow-list на уровне инструмента
Всегда разрешать этот сервер: Добавить в allow-list на уровне сервера
Отмена: Прервать выполнение

3. Выполнение

После подтверждения (или обхода доверия):

Подготовка параметров: Аргументы проверяются на соответствие схеме инструмента

Вызов MCP: Базовый CallableTool вызывает сервер с:


const functionCalls = [
  {
    name: this.serverToolName, // Оригинальное имя инструмента на сервере
    args: params,
  },
];

Обработка ответа: Результаты форматируются как для контекста LLM, так и для отображения пользователю

4. Обработка ответа

Результат выполнения содержит:

llmContent: Необработанные части ответа для контекста языковой модели
returnDisplay: Форматированный вывод для отображения пользователю (часто JSON в markdown code блоках)

Как взаимодействовать с вашим MCP сервером

Использование команды `/mcp`

Команда /mcp предоставляет полную информацию о настройке вашего MCP сервера:


/mcp

Вывод включает:

Список серверов: Все настроенные MCP серверы
Статус подключения: CONNECTED, CONNECTING или DISCONNECTED
Детали сервера: Сводка конфигурации (без чувствительных данных)
Доступные инструменты: Список инструментов с каждого сервера с описаниями
Состояние обнаружения: Общий статус процесса обнаружения

Пример вывода `/mcp`


MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED

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

После обнаружения инструменты MCP становятся доступны модели Qwen как встроенные инструменты. Модель автоматически:

Выбирает подходящие инструменты в зависимости от ваших запросов
Отображает диалоги подтверждения (если только сервер не является доверенным)
Выполняет инструменты с корректными параметрами
Отображает результаты в удобном для пользователя формате

Мониторинг состояния и устранение неполадок

Состояния подключения

Интеграция MCP отслеживает несколько состояний:

Статус сервера (`MCPServerStatus`)

DISCONNECTED: Сервер не подключен или возникли ошибки
CONNECTING: Выполняется попытка подключения
CONNECTED: Сервер подключен и готов к работе

Состояние обнаружения (`MCPDiscoveryState`)

NOT_STARTED: Обнаружение ещё не началось
IN_PROGRESS: В процессе обнаружения серверов
COMPLETED: Обнаружение завершено (с ошибками или без)

Распространённые проблемы и решения

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

Симптомы: Сервер отображает статус DISCONNECTED

Устранение неполадок:

Проверьте конфигурацию: Убедитесь, что command, args и cwd указаны верно
Протестируйте вручную: Запустите команду сервера напрямую, чтобы убедиться, что она работает
Проверьте зависимости: Убедитесь, что все необходимые пакеты установлены
Изучите логи: Найдите сообщения об ошибках в выводе CLI
Проверьте права доступа: Убедитесь, что CLI может выполнить команду сервера

Инструменты не обнаружены

Симптомы: Сервер подключается, но инструменты недоступны

Устранение неполадок:

Проверьте регистрацию инструментов: Убедитесь, что ваш сервер действительно регистрирует инструменты
Проверьте протокол MCP: Подтвердите, что ваш сервер правильно реализует список инструментов MCP
Изучите логи сервера: Проверьте вывод stderr на наличие ошибок на стороне сервера
Протестируйте список инструментов: Вручную протестируйте endpoint обнаружения инструментов вашего сервера

Инструменты не выполняются

Симптомы: Инструменты обнаруживаются, но завершаются с ошибкой во время выполнения

Устранение неполадок:

Валидация параметров: Убедитесь, что ваш инструмент принимает ожидаемые параметры
Совместимость схем: Проверьте, что ваши input схемы являются валидными JSON Schema
Обработка ошибок: Проверьте, не выбрасывает ли ваш инструмент необработанные исключения
Проблемы с таймаутом: Рассмотрите возможность увеличения значения timeout

Совместимость песочницы

Симптомы: MCP серверы завершаются с ошибкой при включенной песочнице

Решения:

Серверы на базе Docker: Используйте Docker контейнеры, которые включают все зависимости
Доступность путей: Убедитесь, что исполняемые файлы сервера доступны в песочнице
Доступ к сети: Настройте песочницу для разрешения необходимых сетевых подключений
Переменные окружения: Проверьте, что необходимые переменные окружения передаются корректно

Советы по отладке

Включите режим отладки: Запустите CLI с флагом --debug, чтобы получить подробный вывод
Проверьте stderr: stderr сервера MCP записывается в лог (информационные сообщения фильтруются)
Изолируйте тестирование: Протестируйте ваш MCP-сервер отдельно перед интеграцией
Инкрементальная настройка: Начните с простых инструментов, прежде чем добавлять сложный функционал
Часто используйте /mcp: Отслеживайте статус сервера во время разработки

Важные замечания

Вопросы безопасности

Настройки доверия: Опция trust отключает все диалоги подтверждения. Используйте с осторожностью и только для серверов, которыми вы полностью управляете
Токены доступа: Будьте внимательны к безопасности при настройке переменных окружения, содержащих API ключи или токены
Совместимость с песочницей: При использовании песочницы убедитесь, что MCP-серверы доступны внутри песочничной среды
Конфиденциальные данные: Использование персональных токенов с широкими правами может привести к утечке информации между репозиториями

Производительность и управление ресурсами

Постоянные соединения: CLI поддерживает постоянные соединения с серверами, которые успешно зарегистрировали инструменты
Автоматическая очистка: Соединения с серверами, не предоставляющими инструментов, автоматически закрываются
Управление таймаутами: Настройте соответствующие таймауты в зависимости от характеристик ответов вашего сервера
Мониторинг ресурсов: MCP-серверы запускаются как отдельные процессы и потребляют системные ресурсы

Совместимость схем

Удаление свойств: Система автоматически удаляет определенные свойства схемы ($schema, additionalProperties) для совместимости с Qwen API
Очистка имен: Имена инструментов автоматически очищаются для соответствия требованиям API
Разрешение конфликтов: Конфликты имен инструментов между серверами разрешаются путем автоматического добавления префиксов

Эта комплексная интеграция делает MCP-серверы мощным способом расширения возможностей CLI с сохранением безопасности, надежности и удобства использования.

Возврат Rich Content из инструментов

Инструменты MCP не ограничены возвратом простого текста. Вы можете возвращать rich, multi-part контент, включая текст, изображения, аудио и другие бинарные данные в одном ответе инструмента. Это позволяет создавать мощные инструменты, которые могут предоставлять модели разнообразную информацию за один ход.

Все данные, возвращаемые из инструмента, обрабатываются и отправляются модели в качестве контекста для следующей генерации, позволяя ей рассуждать или суммировать предоставленную информацию.

Как это работает

Чтобы вернуть rich content, ответ вашего инструмента должен соответствовать спецификации MCP для CallToolResult. Поле content результата должно быть массивом объектов ContentBlock. CLI корректно обработает этот массив, отделяя текст от бинарных данных и упаковывая их для модели.

Вы можете комбинировать различные типы content блоков в массиве content. Поддерживаемые типы блоков включают:

text
image
audio
resource (встроенный контент)
resource_link

Пример: возврат текста и изображения

Вот пример корректного JSON-ответа от инструмента MCP, который возвращает как текстовое описание, так и изображение:


{
  "content": [
    {
      "type": "text",
      "text": "Вот логотип, который вы запрашивали."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "Логотип был создан в 2025 году."
    }
  ]
}

Когда Qwen Code получает этот ответ, он:

Извлекает весь текст и объединяет его в одну часть functionResponse для модели.
Представляет данные изображения как отдельную часть inlineData.
Выводит понятное и дружелюбное резюме в CLI, указывая, что были получены и текст, и изображение.

Это позволяет создавать сложные инструменты, которые могут предоставлять модели Qwen богатый многомодальный контекст.

MCP Prompts как Slash Commands

Помимо инструментов, MCP-серверы могут предоставлять预定义ные prompts, которые можно выполнять как slash commands внутри Qwen Code. Это позволяет создавать shortcuts для часто используемых или сложных запросов, которые можно легко вызывать по имени.

Определение промптов на сервере

Вот небольшой пример stdio MCP сервера, который определяет промпты:


import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
 
const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});
 
server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

Это можно добавить в settings.json в разделе mcpServers следующим образом:


"nodeServer": {
  "command": "node",
  "args": ["filename.ts"],
}

Вызов промптов

После того как промпт будет обнаружен, вы можете вызвать его, используя его имя в качестве slash-команды. CLI автоматически обработает парсинг аргументов.


/poem-writer --title="Qwen Code" --mood="reverent"

или, используя позиционные аргументы:


/poem-writer "Qwen Code" reverent

При выполнении этой команды CLI вызывает метод prompts/get на сервере MCP с переданными аргументами. Сервер отвечает за подстановку аргументов в шаблон промпта и возвращает финальный текст промпта. Затем CLI отправляет этот промпт модели для выполнения. Это удобный способ автоматизировать и делиться общими рабочими процессами.

Управление MCP серверами с помощью `qwen mcp`

Хотя вы всегда можете настроить MCP сервера, отредактировав вручную файл settings.json, CLI предоставляет удобный набор команд для программного управления конфигурациями ваших серверов. Эти команды упрощают процесс добавления, просмотра и удаления MCP серверов без необходимости напрямую редактировать JSON файлы.

Добавление сервера (`qwen mcp add`)

Команда add настраивает новый MCP-сервер в вашем settings.json. В зависимости от области видимости (-s, --scope), сервер будет добавлен либо в пользовательский конфиг ~/.qwen/settings.json, либо в проектный конфиг .qwen/settings.json.

Команда:


qwen mcp add [options] <name> <commandOrUrl> [args...]

<name>: Уникальное имя сервера.
<commandOrUrl>: Команда для выполнения (для stdio) или URL (для http/sse).
[args...]: Опциональные аргументы для команды stdio.

Опции (флаги):

-s, --scope: Область конфигурации (user или project). [по умолчанию: “project”]
-t, --transport: Тип транспорта (stdio, sse, http). [по умолчанию: “stdio”]
-e, --env: Установить переменные окружения (например, -e KEY=value).
-H, --header: Установить HTTP-заголовки для SSE и HTTP транспортов (например, -H “X-Api-Key: abc123” -H “Authorization: Bearer abc123”).
--timeout: Установить таймаут подключения в миллисекундах.
--trust: Доверять серверу (пропустить все подтверждения вызова инструментов).
--description: Задать описание сервера.
--include-tools: Список инструментов для включения, разделённый запятыми.
--exclude-tools: Список инструментов для исключения, разделённый запятыми.

Добавление stdio сервера

Это транспорт по умолчанию для запуска локальных серверов.


 
# Базовый синтаксис
qwen mcp add <name> <command> [args...]
 
# Пример: Добавление локального сервера
qwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
 
# Пример: Добавление локального python сервера
qwen mcp add python-server python server.py --port 8080

Добавление HTTP сервера

Этот транспорт используется для серверов, которые используют потоковую передачу по HTTP.


 
# Базовый синтаксис
qwen mcp add --transport http <name> <url>
 
# Пример: Добавление HTTP сервера
qwen mcp add --transport http http-server https://api.example.com/mcp/
 
# Пример: Добавление HTTP сервера с заголовком аутентификации
qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"

Добавление SSE сервера

Этот транспорт используется для серверов, которые используют Server-Sent Events (SSE).


 
# Базовый синтаксис
qwen mcp add --transport sse <name> <url>


# Пример: Добавление SSE-сервера
qwen mcp add --transport sse sse-server https://api.example.com/sse/
 
# Пример: Добавление SSE-сервера с заголовком авторизации
qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"

Просмотр списка серверов (`qwen mcp list`)

Чтобы посмотреть все настроенные MCP-серверы, используйте команду list. Она отобразит имя каждого сервера, его конфигурацию и статус подключения.

Команда:


qwen mcp list

Пример вывода:


✓ stdio-server: command: python3 server.py (stdio) - Connected
✓ http-server: https://api.example.com/mcp (http) - Connected
✗ sse-server: https://api.example.com/sse (sse) - Disconnected

Удаление сервера (`qwen mcp remove`)

Чтобы удалить сервер из вашей конфигурации, используйте команду remove с указанием имени сервера.

Команда:


qwen mcp remove <name>

Пример:


qwen mcp remove my-server

Эта команда найдет и удалит запись “my-server” из объекта mcpServers в соответствующем файле settings.json, определяемом scope (-s, --scope).

MCP серверы с Qwen Code

Что такое MCP сервер?

Архитектура основной интеграции

Слой обнаружения (mcp-client.ts)

Execution Layer (mcp-tool.ts)

Transport Mechanisms

Как настроить свой MCP сервер

Настройка MCP-сервера в settings.json

Структура конфигурации

Свойства конфигурации

Обязательно (одно из следующих)

Необязательные параметры

Поддержка OAuth для удаленных MCP серверов

Автоматическое обнаружение OAuth

Поток аутентификации

Требования к перенаправлению браузера

Управление OAuth-аутентификацией

Свойства конфигурации OAuth

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

Python MCP Server (Stdio)

Node.js MCP Server (Stdio)

Docker-based MCP Server

HTTP-based MCP Server

HTTP-based MCP Server с Custom Headers

MCP Server с фильтрацией инструментов

Подробное описание процесса обнаружения

1. Итерация по серверам и подключение

2. Обнаружение инструментов

3. Разрешение конфликтов

4. Обработка схем

5. Управление подключениями

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

1. Вызов инструмента

2. Процесс подтверждения

Обход на основе доверия

Динамическое разрешение

Обработка выбора пользователя

3. Выполнение

4. Обработка ответа

Как взаимодействовать с вашим MCP сервером

Использование команды /mcp

Пример вывода /mcp

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

Мониторинг состояния и устранение неполадок

Состояния подключения

Статус сервера (MCPServerStatus)

Состояние обнаружения (MCPDiscoveryState)

Распространённые проблемы и решения

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

Инструменты не обнаружены

Инструменты не выполняются

Совместимость песочницы

Советы по отладке

Важные замечания

Вопросы безопасности

Производительность и управление ресурсами

Совместимость схем

Возврат Rich Content из инструментов

Как это работает

Пример: возврат текста и изображения

MCP Prompts как Slash Commands

Определение промптов на сервере

Вызов промптов

Управление MCP серверами с помощью qwen mcp

Добавление сервера (qwen mcp add)

Добавление stdio сервера

Добавление HTTP сервера

Добавление SSE сервера

Просмотр списка серверов (qwen mcp list)

Удаление сервера (qwen mcp remove)

Слой обнаружения (`mcp-client.ts`)

Execution Layer (`mcp-tool.ts`)

Использование команды `/mcp`

Пример вывода `/mcp`

Статус сервера (`MCPServerStatus`)

Состояние обнаружения (`MCPDiscoveryState`)

Управление MCP серверами с помощью `qwen mcp`

Добавление сервера (`qwen mcp add`)

Просмотр списка серверов (`qwen mcp list`)

Удаление сервера (`qwen mcp remove`)