Подключение Qwen Code к инструментам через MCP

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

Что можно делать с MCP

С подключенными MCP-серверами вы можете попросить Qwen Code:

• Работать с файлами и репозиториями (чтение/поиск/запись, в зависимости от включенных инструментов)
• Выполнять запросы к базам данных (проверка схемы, запросы, отчеты)
• Интегрировать внутренние сервисы (оборачивать ваши API как MCP-инструменты)
• Автоматизировать рабочие процессы (повторяемые задачи, реализованные как инструменты/промпты)

Быстрый старт

Qwen Code загружает MCP-серверы из раздела mcpServers в вашем settings.json. Вы можете настроить серверы либо:

• Напрямую редактируя settings.json
• Используя команды qwen mcp (см. Справочник CLI)

Добавление первого сервера

1. Добавьте сервер (пример: удалённый HTTP MCP-сервер):

qwen mcp add --transport http my-server http://localhost:3000/mcp

2. Запустите Qwen Code и откройте диалог управления MCP, чтобы просмотреть и управлять серверами:

qwen

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

/mcp

3. Если Qwen Code уже был запущен до добавления сервера, перезапустите его в том же проекте. Затем попросите модель использовать инструменты с этого сервера.

Где хранится конфигурация (области действия)

Большинству пользователей нужны только две области:

• Пользовательская область (по умолчанию): ~/.qwen/settings.json действует для всех проектов на вашей машине
• Проектная область: .qwen/settings.json в корне вашего проекта

Запись в пользовательскую область:

qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

Настройка серверов

Выбор транспорта

Настройка через settings.json vs qwen mcp add

Оба подхода создают одинаковые записи mcpServers в вашем settings.json — используйте любой удобный.

Stdio-сервер (локальный процесс)

JSON (.qwen/settings.json):

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

CLI (по умолчанию записывает в пользовательскую область):

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

HTTP-сервер (удалённый потоковый HTTP)

JSON:

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

CLI:

qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-token" --timeout 5000

SSE-сервер (удалённый Server-Sent Events)

JSON:

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

CLI:

qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000

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

Помимо инструментов, Qwen Code обнаруживает и отображает два других примитива MCP.

Промпты (слэш-команды)

Любой промпт, который сервер предоставляет через prompts/list, становится выполняемой слэш-командой. После обнаружения введите /, и вы увидите промпт в списке (с пометкой MCP: <server>); выполните его, как любую другую команду:

/my_prompt --arg1="value" --arg2="value"
# также работает позиционная форма:
/my_prompt "value" "value"
# показать аргументы промпта:
/my_prompt help

Сообщения промпта отправляются модели, которая затем действует на их основе.

Обнаружение нестрого относится к объявленной возможности prompts: некоторые серверы реализуют prompts/list, но опускают prompts в своих возможностях initialize. Qwen Code всё равно пытается выполнить prompts/list, поэтому такие промпты всё равно появляются. Сервер, у которого действительно нет промптов, просто отвечает Method not found, что игнорируется.

Ресурсы

Ресурсы, которые сервер предоставляет через resources/list, обнаруживаются для каждого сервера. Откройте диалог управления с помощью /mcp и выберите сервер, чтобы увидеть количество его Ресурсов рядом с инструментами и промптами. Выберите Просмотреть ресурсы, чтобы просмотреть URI ресурсов сервера; выбор одного из них покажет его описание и MIME-тип вместе с точной ссылкой @server:uri для вставки в сообщение. Как и в случае с промптами, возможность resources не обязательно должна быть объявлена.

Вставьте содержимое ресурса в своё сообщение с помощью синтаксиса @server:uri — введите @, затем имя сервера, двоеточие и URI ресурса:

summarize @myserver:file:///docs/spec.md and list the open questions

При вводе @myserver: появляется автодополняемый список ресурсов этого сервера; продолжайте ввод для фильтрации, сопоставляя (без учёта регистра) либо URI ресурса, либо его дружественное имя/заголовок. Вам не обязательно знать URI наизусть — до того, как вы введёте двоеточие, ввод части имени сервера также предложит подходящие серверы, которые предоставляют ресурсы, так что вы можете выбрать один и сразу перейти к его списку ресурсов. После отправки указанный ресурс считывается, и его содержимое добавляется к вашему сообщению (текст встраивается, бинарные данные — как вложения); ссылка @server:uri сохраняется в промпте, чтобы модель понимала, на что смотрит. Префикс server должен соответствовать настроенному MCP-серверу — в противном случае токен обрабатывается как обычный путь к файлу, поэтому существующие ссылки @path/to/file не затрагиваются. Чтение ресурсов отключено в недоверенных папках.

Постепенная доступность и таймауты обнаружения

Qwen Code обнаруживает MCP-серверы в фоновом режиме после того, как UI уже стал интерактивным. Вы видите первое приглашение CLI уже через несколько сотен миллисекунд, даже если один из ваших MCP-серверов отвечает несколько секунд (или не отвечает вообще), а список инструментов модели обновляется примерно за один кадр (~16 мс) после завершения каждым сервером процедуры обнаружения.

• Интерактивный режим: UI появляется немедленно; в правом нижнем углу отображается индикатор статуса MCP, показывающий N/M MCP servers ready во время обнаружения. Отправка промпта до завершения MCP означает, что модель видит только те инструменты, которые готовы на данный момент; последующие промпты будут видеть больше инструментов по мере подключения серверов.
• Неинтерактивный режим (--prompt, stream-json, ACP): CLI по-прежнему ожидает завершения обнаружения MCP перед отправкой первого промпта, так что вызовы из скриптов/конвейеров видят тот же полный набор инструментов, что и при старом синхронном поведении.

Периодичный discoveryTimeoutMs

Каждый MCP-сервер получает таймаут только для обнаружения, который ограничивает время, выделяемое на начальное рукопожатие (connect + tools/list + prompts/list + resources/list). Значения по умолчанию:

• stdio-серверы: 30 с
• удалённые HTTP/SSE-серверы: 5 с (сетевой риск выше)

При необходимости переопределите для каждого сервера:

{
  "mcpServers": {
    "slow-stdio": {
      "command": "node",
      "args": ["./slow-server.js"],
      "discoveryTimeoutMs": 60000,
    },
    "flaky-remote": {
      "httpUrl": "https://example.com/mcp",
      "discoveryTimeoutMs": 10000,
    },
  },
}

Существующее поле timeout — это таймаут вызова инструмента (используется для каждого запроса tools/call, по умолчанию 10 минут) и не зависит от discoveryTimeoutMs — длительный запуск инструмента не является проблемой запуска.

Откат к старому поведению MCP

Если вам нужно старое синхронное поведение (CLI ожидает каждый MCP-сервер перед показом UI), установите переменную окружения QWEN_CODE_LEGACY_MCP_BLOCKING=1. Этот параметр сохраняется как запасной вариант как минимум на один релиз.

Безопасность и контроль

Доверие (пропуск подтверждений)

• Доверие к серверу (trust: true): отключает запросы подтверждения для этого сервера (используйте с осторожностью).

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

Qwen Code поддерживает аутентификацию OAuth 2.0 для MCP-серверов. Это полезно при доступе к удалённым серверам, требующим аутентификации.

Основное использование

Когда вы добавляете MCP-сервер с учётными данными OAuth, Qwen Code автоматически обрабатывает поток аутентификации:

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

Важно: настройка redirect URI

Поток OAuth требует redirect URI, куда провайдер аутентификации отправляет код авторизации.

• Локальная разработка: По умолчанию Qwen Code использует http://localhost:7777/oauth/callback. Это работает при запуске Qwen Code на локальной машине с локальным браузером.

• Удалённые/облачные развертывания: При запуске Qwen Code на удалённых серверах, облачных IDE или веб-терминалах redirect URI по умолчанию на localhost НЕ будет работать. Вы ДОЛЖНЫ настроить --oauth-redirect-uri на публично доступный URL, который может получить callback OAuth.

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

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

Ручная настройка через settings.json

Вы также можете настроить OAuth, редактируя settings.json напрямую:

{
  "mcpServers": {
    "oauthServer": {
      "url": "https://api.example.com/sse/",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "authorizationUrl": "https://provider.example.com/authorize",
        "tokenUrl": "https://provider.example.com/token",
        "redirectUri": "https://your-server.com/oauth/callback",
        "scopes": ["read", "write"]
      }
    }
  }
}

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

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

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

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

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

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

Фильтрация инструментов (разрешение/запрет инструментов на сервер)

Используйте includeTools / excludeTools, чтобы ограничить инструменты, предоставляемые сервером (с точки зрения Qwen Code).

Пример: включить только несколько инструментов:

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

Глобальные списки разрешения/запрета

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

• mcp.allowed: белый список имён MCP-серверов (ключи в mcpServers)
• mcp.excluded: чёрный список имён MCP-серверов

Пример:

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

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

• Сервер отображается как «Отключён» в qwen mcp list: проверьте правильность URL/команды, затем увеличьте timeout.
• Stdio-сервер не запускается: используйте абсолютный путь к command и дважды проверьте cwd/env.
• Переменные окружения в JSON не разрешаются: убедитесь, что они существуют в окружении, где запущен Qwen Code (окружение оболочки и GUI-приложений может различаться).

Справочник

Структура settings.json

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

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

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

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

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

Опционально:

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

Вы всегда можете настроить MCP-серверы, редактируя settings.json вручную, но CLI обычно быстрее.

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

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

Флаги --oauth-* применяются только к --transport sse и --transport http. Их использование вместе с --transport stdio отклоняется.

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

qwen mcp remove <name>