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
Очищает и проверяет схемы инструментов на совместимость с API Qwen
Регистрирует инструменты в глобальном реестре инструментов с разрешением конфликтов

Уровень выполнения (`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 (строка): Глобальная команда для запуска MCP-сервера.
mcp.allowed (массив строк): Список имён MCP-серверов, которые разрешены. Если этот параметр задан, будут подключены только серверы из этого списка (соответствующие ключам в объекте mcpServers).
mcp.excluded (массив строк): Список имён MCP-серверов, которые следует исключить. Серверы из этого списка не будут подключаться.

Пример:


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

Конфигурация отдельных серверов (`mcpServers`)

Объект mcpServers предназначен для определения каждого отдельного MCP-сервера, к которому CLI должен подключаться.

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

Добавьте объект 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 (строка): Путь к исполняемому файлу для Stdio транспорта
url (строка): URL конечной точки SSE (например, "http://localhost:8080/sse")
httpUrl (строка): URL конечной точки HTTP-стриминга

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

args (массив строк): Аргументы командной строки для Stdio транспорта
headers (объект): Пользовательские HTTP-заголовки при использовании url или httpUrl
env (объект): Переменные окружения для процесса сервера. Значения могут ссылаться на переменные окружения с помощью синтаксиса $VAR_NAME или ${VAR_NAME}
cwd (строка): Рабочая директория для Stdio транспорта
timeout (число): Тайм-аут запроса в миллисекундах (по умолчанию: 600 000 мс = 10 минут)
trust (логическое): Если true, все подтверждения вызовов инструментов для этого сервера отключаются (по умолчанию: false)
includeTools (массив строк): Список имён инструментов, которые следует включить из этого MCP-сервера. Если указан, только перечисленные здесь инструменты будут доступны с этого сервера (режим белого списка). Если не указан, все инструменты с сервера включены по умолчанию.
excludeTools (массив строк): Список имён инструментов, которые следует исключить из этого MCP-сервера. Инструменты из этого списка не будут доступны модели, даже если они предоставлены сервером. Примечание: excludeTools имеет приоритет над includeTools — если инструмент есть в обоих списках, он будет исключён.
targetAudience (строка): Идентификатор клиента OAuth, внесённый в белый список, для приложения, защищённого IAP. Используется с authProviderType: 'service_account_impersonation'.
targetServiceAccount (строка): Адрес электронной почты сервисного аккаунта Google Cloud, который нужно олицетворять. Используется с 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 требует, чтобы URI перенаправления был доступен:

Поведение по умолчанию: Перенаправление на http://localhost:7777/oauth/callback (работает для локальных конфигураций)
Пользовательский URI перенаправления: Используйте --oauth-redirect-uri или настройте redirectUri в settings.json, чтобы указать другой URL

Для удалённых/облачных развёртываний сервера (например, веб-терминалы, SSH-сессии, облачные IDE):

Перенаправление на localhost по умолчанию не будет работать
Вы должны настроить пользовательский redirectUri, указывающий на общедоступный URL
Браузер пользователя должен иметь возможность достичь этого URL и перенаправить обратно на сервер

Пример для удалённых серверов:


qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback

OAuth не будет работать в:

Средах без графического интерфейса и без доступа к браузеру
Средах, где настроенный redirectUri недоступен из браузера пользователя

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

Используйте диалог /mcp внутри интерактивной сессии Qwen Code, чтобы просматривать MCP-серверы и управлять аутентификацией OAuth.

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

enabled (логическое): Включить OAuth для этого сервера
clientId (строка): Идентификатор клиента OAuth (необязателен при динамической регистрации)
clientSecret (строка): Секрет клиента OAuth (необязателен для публичных клиентов)
authorizationUrl (строка): Конечная точка авторизации OAuth (обнаруживается автоматически, если опущен)
tokenUrl (строка): Конечная точка получения токена OAuth (обнаруживается автоматически, если опущен)
scopes (массив строк): Требуемые области OAuth
redirectUri (строка): Пользовательский URI перенаправления. Критически важно для удалённых развёртываний: По умолчанию http://localhost:7777/oauth/callback. При запуске Qwen Code на удалённых/облачных серверах укажите общедоступный URL (например, https://your-server.com/oauth/callback). Можно настроить через qwen mcp add --oauth-redirect-uri или напрямую в settings.json.
tokenParamName (строка): Имя параметра запроса для токенов в URL SSE
audiences (массив строк): Аудитории, для которых действителен токен

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

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

Сохраняются в ~/.qwen/mcp-oauth-tokens.json (в открытом виде, режим 0600) по умолчанию. Если задано QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true, Qwen Code использует хранилище, привязанное к связке ключей (keychain), где это возможно, или ~/.qwen/mcp-oauth-tokens-v2.json с шифрованием AES-256-GCM.
Обновляются при истечении срока действия (если доступны токены обновления)
Проверяются перед каждой попыткой подключения
Очищаются при недействительности или истечении срока

[!WARNING] По умолчанию токены OAuth хранятся на диске в незашифрованном виде. На общих или многопользовательских машинах установите QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true, чтобы защитить учётные данные.

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

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

authProviderType (строка): Определяет провайдера аутентификации. Может быть одним из следующих:
- dynamic_discovery (по умолчанию): CLI автоматически обнаружит конфигурацию OAuth с сервера.
- google_credentials: CLI будет использовать учётные данные по умолчанию для приложений Google (ADC) для аутентификации на сервере. При использовании этого провайдера необходимо указать требуемые области.
- service_account_impersonation: CLI будет олицетворять сервисный аккаунт 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"]
      }
    }
  }
}

Олицетворение сервисного аккаунта

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

targetAudience (строка): Идентификатор клиента OAuth, внесённый в белый список, для приложения, защищённого IAP.
targetServiceAccount (строка): Адрес электронной почты сервисного аккаунта Google Cloud, который нужно олицетворять.

CLI будет использовать ваши локальные учётные данные по умолчанию для приложений (ADC) для создания OIDC ID токена для указанного сервисного аккаунта и аудитории. Затем этот токен будет использоваться для аутентификации на MCP-сервере.

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

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

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

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"
      }
    }
  }
}

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


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

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


{
  "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
    }
  }
}

MCP-сервер SSE с олицетворением сервисного аккаунта


{
  "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
Очистка имён: Имена инструментов очищаются для соответствия требованиям API Qwen:
- Недопустимые символы (не буквы, цифры, символы подчёркивания, точки, дефисы) заменяются на символ подчёркивания
- Имена длиннее 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; // Подтверждение не требуется
}

Динамический белый список

Система ведёт внутренние белые списки для:

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

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

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

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

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

После подтверждения (или пропуска по доверию):

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

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


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

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

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

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

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

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

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

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


/mcp

Она отображает:

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

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


Текущее состояние MCP-серверов:

📡 pythonTools (CONNECTED)
  Команда: python -m my_mcp_server --port 8080
  Рабочая директория: ./mcp-servers/python
  Тайм-аут: 15000 мс
  Инструменты: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Команда: node dist/server.js --verbose
  Ошибка: Соединение отклонено

🐳 dockerizedServer (CONNECTED)
  Команда: docker run -i --rm -e API_KEY my-mcp-server:latest
  Инструменты: docker__deploy, docker__status

Состояние обнаружения: ЗАВЕРШЕНО

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

После обнаружения инструменты 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: "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": "Вот запрошенный вами логотип."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "Логотип был создан в 2025 году."
    }
  ]
}

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

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

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

Подсказки MCP как слэш-команды

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

Определение подсказок на сервере

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


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: 'Поэт',
    description: 'Написать красивое хайку',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Напиши хайку${mood ? ` с настроением ${mood}` : ''} под названием ${title}. Обрати внимание, что хайку состоит из 5 слогов, затем 7 слогов, затем 5 слогов.`,
        },
      },
    ],
  }),
);
 
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="благоговейный"

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


/poem-writer "Qwen Code" благоговейный

Когда вы выполняете эту команду, 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: Список инструментов для исключения, разделённый запятыми.
--oauth-client-id: Идентификатор клиента OAuth для аутентификации сервера MCP.
--oauth-client-secret: Секрет клиента OAuth для аутентификации сервера MCP.
--oauth-redirect-uri: URI перенаправления OAuth (например, https://your-server.com/oauth/callback). По умолчанию http://localhost:7777/oauth/callback для локальных настроек. Важно для удалённых развёртываний: При запуске Qwen Code на удалённых/облачных серверах установите это значение на общедоступный URL.
--oauth-authorization-url: URL авторизации OAuth.
--oauth-token-url: URL токена OAuth.
--oauth-scopes: Области OAuth (разделённые запятыми).

Добавление 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"
 
# Пример: Добавление SSE-сервера с поддержкой OAuth
qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
  --oauth-client-id your-client-id \
  --oauth-redirect-uri https://your-server.com/oauth/callback \
  --oauth-authorization-url https://provider.example.com/authorize \
  --oauth-token-url https://provider.example.com/token

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

Чтобы просмотреть все настроенные серверы MCP и управлять ими, откройте диалог /mcp внутри интерактивной сессии Qwen Code. Этот диалог позволяет:

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

Команда:


qwen

Затем введите:


/mcp

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

Удаление сервера (`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

Олицетворение сервисного аккаунта

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

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

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

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

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

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

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

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

MCP-сервер SSE с олицетворением сервисного аккаунта

Детальное описание процесса обнаружения

1. Перебор серверов и установка соединения

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

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

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

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

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

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

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

Пропуск на основе доверия

Динамический белый список

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

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

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

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

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

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

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

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

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

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

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

Частые проблемы и их решения

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

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

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

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

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

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

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

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

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

Возврат расширенного содержимого из инструментов

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

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

Подсказки MCP как слэш-команды

Определение подсказок на сервере

Вызов подсказок

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

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

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

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

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

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

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

Уровень обнаружения (`mcp-client.ts`)

Уровень выполнения (`mcp-tool.ts`)

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

Конфигурация отдельных серверов (`mcpServers`)

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

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

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

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

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

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

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

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