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 (array of strings): Список имён MCP-серверов, которые разрешены. Если задано, подключаться будут только серверы из этого списка (соответствующие ключам в объекте mcpServers).
mcp.excluded (array of strings): Список имён 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): Адрес электронной почты Google Cloud Service Account, от имени которого выполняется 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 требует, чтобы 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 не будет работать в:

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

Управление аутентификацией 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[]): Требуемые области OAuth
redirectUri (string): Пользовательский URI перенаправления. Критично для удалённых развертываний: По умолчанию http://localhost:7777/oauth/callback. При запуске Qwen Code на удалённых/облачных серверах установите общедоступный URL (например, https://your-server.com/oauth/callback). Можно настроить через qwen mcp add --oauth-redirect-uri или напрямую в settings.json.
tokenParamName (string): Имя параметра запроса для токенов в 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) для аутентификации на сервере. При использовании этого провайдера необходимо указать требуемые scopes.
- service_account_impersonation: CLI будет выполнять impersonation Google Cloud Service Account для аутентификации на сервере. Это полезно для доступа к сервисам, защищённым 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): Адрес электронной почты Google Cloud Service Account, от имени которого выполняется 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-lists для:

Уровня сервера: 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: Разделённый запятыми список инструментов для исключения.
--oauth-client-id: OAuth client ID для аутентификации MCP-сервера.
--oauth-client-secret: OAuth client secret для аутентификации MCP-сервера.
--oauth-redirect-uri: OAuth redirect URI (например, 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-сервера

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


# Basic syntax
qwen mcp add <name> <command> [args...]
 
# Example: Adding a local server
qwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
 
# Example: Adding a local python server
qwen mcp add python-server python server.py --port 8080

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

Этот транспорт предназначен для серверов, использующих streamable HTTP-транспорт.


# Basic syntax
qwen mcp add --transport http <name> <url>
 
# Example: Adding an HTTP server
qwen mcp add --transport http http-server https://api.example.com/mcp/
 
# Example: Adding an HTTP server with an authentication header
qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"

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

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


# Basic syntax
qwen mcp add --transport sse <name> <url>
 
# Example: Adding an SSE server
qwen mcp add --transport sse sse-server https://api.example.com/sse/
 
# Example: Adding an SSE server with an authentication header
qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"
 
# Example: Adding an OAuth-enabled SSE server
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

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