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
Регистрирует инструменты в глобальном реестре инструментов с разрешением конфликтов

Слой выполнения (`mcp-tool.ts`)

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

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

Механизмы транспорта

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

Stdio Transport: запускает подпроцесс и взаимодействует через stdin/stdout
SSE Transport: подключается к эндпоинтам Server-Sent Events
Streamable HTTP Transport: использует HTTP-стриминг для взаимодействия

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

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

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

Настроить MCP-серверы в settings.json можно двумя основными способами: через объект верхнего уровня mcpServers для конкретных определений серверов и через объект mcp для глобальных настроек, управляющих обнаружением и выполнением серверов.

Глобальные настройки MCP (`mcp`)

Объект mcp в settings.json позволяет задать глобальные правила для всех MCP-серверов.

mcp.serverCommand (string): глобальная команда для запуска MCP-сервера.
mcp.allowed (массив строк): список разрешённых MCP-серверов. Если задан, подключаться будут только серверы из этого списка (совпадающие с ключами в объекте mcpServers).
mcp.excluded (массив строк): список исключаемых MCP-серверов. Серверы из этого списка не будут подключаться.

Пример:


{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

Конфигурация конкретного сервера (`mcpServers`)

В объекте mcpServers вы определяете каждый отдельный MCP-сервер, к которому должен подключаться CLI.

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

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


{ ...file contains other config objects
  "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 эндпоинта SSE (например, "http://localhost:8080/sse")
httpUrl (string): URL эндпоинта HTTP-стриминга

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

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-сервера. Если указано, доступны будут только перечисленные здесь инструменты (режим allowlist). Если не указано, по умолчанию включены все инструменты сервера.
excludeTools (string[]): список имён инструментов, которые нужно исключить с этого MCP-сервера. Перечисленные здесь инструменты не будут доступны модели, даже если сервер их предоставляет. Примечание: excludeTools имеет приоритет над includeTools — если инструмент есть в обоих списках, он будет исключён.
targetAudience (string): OAuth Client ID, добавленный в allowlist приложения, защищённого IAP, к которому вы пытаетесь получить доступ. Используется с authProviderType: 'service_account_impersonation'.
targetServiceAccount (string): email-адрес сервисного аккаунта Google Cloud, от имени которого выполняется impersonation. Используется с authProviderType: 'service_account_impersonation'.

Поддержка 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-поток и управление токенами

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

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

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

Требования к редиректу браузера

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

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

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

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

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

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


# Список серверов, требующих аутентификации
/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[]): требуемые OAuth-скопы
redirectUri (string): пользовательский URI редиректа (по умолчанию http://localhost:7777/oauth/callback)
tokenParamName (string): имя query-параметра для токенов в SSE-URL
audiences (string[]): аудитории, для которых действителен токен

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

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

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

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

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

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

Учётные данные Google


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

Impersonation сервисного аккаунта

Для аутентификации на сервере с использованием impersonation сервисного аккаунта необходимо установить authProviderType в service_account_impersonation и указать следующие свойства:

targetAudience (string): OAuth Client ID, добавленный в allowlist приложения, защищённого IAP, к которому вы пытаетесь получить доступ.
targetServiceAccount (string): email-адрес сервисного аккаунта Google Cloud, от имени которого выполняется impersonation.

CLI будет использовать ваши локальные Application Default Credentials (ADC) для генерации OIDC ID-токена для указанного сервисного аккаунта и аудитории. Этот токен затем будет использоваться для аутентификации на MCP-сервере.

Инструкции по настройке

Создайте или используйте существующий OAuth 2.0 Client ID. Чтобы использовать существующий OAuth 2.0 Client ID, выполните шаги из How to share OAuth Clients .
Добавьте OAuth ID в allowlist для программного доступа приложения. Поскольку Cloud Run пока не является поддерживаемым типом ресурса в gcloud iap, вы должны добавить Client ID в allowlist на уровне проекта.
Создайте сервисный аккаунт. Документация , Ссылка на Cloud Console
Добавьте сервисный аккаунт и пользователей в IAP Policy на вкладке “Security” самого сервиса Cloud Run или через gcloud.
Предоставьте всем пользователям и группам, которые будут получать доступ к MCP-серверу, необходимые разрешения на impersonation сервисного аккаунта (например, roles/iam.serviceAccountTokenCreator).
Включите IAM Credentials API для вашего проекта.

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

Python MCP-сервер (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-сервер (Stdio)


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

MCP-сервер на базе Docker


{
  "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 MCP-сервер


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

HTTP MCP-сервер с пользовательскими заголовками


{
  "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-сервер с фильтрацией инструментов


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

SSE MCP-сервер с SA Impersonation


{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

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

При запуске Qwen Code выполняет обнаружение MCP-серверов по следующему детальному процессу:

1. Перебор серверов и подключение

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

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

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

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

Список инструментов: клиент вызывает эндпоинт списка инструментов 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; // No confirmation needed
}

Динамический allow-list

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

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

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

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

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

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

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

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

MCP-вызов: базовый CallableTool вызывает сервер с:


const functionCalls = [
  {
    name: this.serverToolName, // Original server tool name
    args: params,
  },
];

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

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

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

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

Как взаимодействовать с вашим 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 на наличие ошибок на стороне сервера
Протестируйте список инструментов: вручную проверьте эндпоинт обнаружения инструментов вашего сервера

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

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

Диагностика:

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

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

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

Решения:

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

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

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

Важные примечания

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

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

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

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

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

Режим соответствия схем: по умолчанию (schemaCompliance: "auto") схемы инструментов передаются как есть. Установите "model": { "generationConfig": { "schemaCompliance": "openapi_30" } } в вашем settings.json, чтобы преобразовать модели в строгий формат OpenAPI 3.0.
Трансформации OpenAPI 3.0: при включённом режиме openapi_30 система обрабатывает:
- Nullable-типы: ["string", "null"] -> type: "string", nullable: true
- Const-значения: const: "foo" -> enum: ["foo"]
- Исключительные ограничения: числовой exclusiveMinimum -> булева форма с minimum
- Удаление ключевых слов: $schema, $id, dependencies, patternProperties
Очистка имён: имена инструментов автоматически очищаются для соответствия требованиям API
Разрешение конфликтов: конфликты имён инструментов между серверами разрешаются путём автоматического добавления префикса

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

Возврат богатого контента из инструментов

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

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

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

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

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

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

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

Ниже приведён пример валидного JSON-ответа от MCP-инструмента, возвращающего как текстовое описание, так и изображение:


{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 2025."
    }
  ]
}

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

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

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

MCP-промпты как слэш-команды

Помимо инструментов, MCP-серверы могут предоставлять предопределённые промпты, которые можно выполнять как слэш-команды внутри Qwen Code. Это позволяет создавать ярлыки для распространённых или сложных запросов, которые можно легко вызывать по имени.

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

Вот небольшой пример 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 следующим образом:


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

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

После обнаружения промпта вы можете вызвать его, используя его имя как слэш-команду. 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-сервера

Этот транспорт предназначен для серверов, использующих streamable 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`)

Для просмотра и управления всеми текущими настроенными MCP-серверами используйте команду manage или просто qwen mcp. Это открывает интерактивный TUI-диалог, где вы можете:

просматривать все MCP-серверы с их статусом подключения
включать/отключать серверы
переподключаться к отключённым серверам
просматривать инструменты и промпты, предоставляемые каждым сервером
просматривать логи серверов

Команда:


qwen mcp
# or
qwen mcp manage

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

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

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

Команда:


qwen mcp remove <name>

Пример:


qwen mcp remove my-server

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

MCP-серверы с Qwen Code

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

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

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

Слой выполнения (mcp-tool.ts)

Механизмы транспорта

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

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

Глобальные настройки MCP (mcp)

Конфигурация конкретного сервера (mcpServers)

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

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

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

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

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

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

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

Требования к редиректу браузера

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

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

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

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

Учётные данные Google

Impersonation сервисного аккаунта

Инструкции по настройке

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

Python MCP-сервер (Stdio)

Node.js MCP-сервер (Stdio)

MCP-сервер на базе Docker

HTTP MCP-сервер

HTTP MCP-сервер с пользовательскими заголовками

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

SSE MCP-сервер с SA Impersonation

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

1. Перебор серверов и подключение

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

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

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

5. Управление соединениями

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

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

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

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

Динамический allow-list

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Важные примечания

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

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

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

Возврат богатого контента из инструментов

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

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

MCP-промпты как слэш-команды

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

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

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

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

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

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

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

Управление серверами (qwen mcp)

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

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

Слой выполнения (`mcp-tool.ts`)

Глобальные настройки MCP (`mcp`)

Конфигурация конкретного сервера (`mcpServers`)

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

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

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

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

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

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

Управление серверами (`qwen mcp`)

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