Подключение 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 или 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-сервер (удаленный streamable 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"
# positional form also works:
/my_prompt "value" "value"
# show the prompt's arguments:
/my_prompt help

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

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

Ресурсы

Ресурсы, которые сервер анонсирует через resources/list, обнаруживаются для каждого сервера. Откройте диалог управления с помощью /mcp и выберите сервер, чтобы увидеть количество его Resources наряду с инструментами и промптами. Выберите View resources, чтобы просмотреть 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-серверы в фоновом режиме после того, как пользовательский интерфейс уже становится интерактивным. Вы видите первый промпт CLI через несколько сотен миллисекунд, даже если одному из ваших MCP-серверов требуется несколько секунд (или он вообще не отвечает), а список инструментов модели обновляется примерно в течение одного кадра (~16 мс) после завершения каждым сервером рукопожатия обнаружения.

• Интерактивный режим: пользовательский интерфейс появляется мгновенно; индикатор статуса 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 или веб-терминалах перенаправление по умолчанию на localhost НЕ будет работать. Вы ДОЛЖНЫ настроить --oauth-redirect-uri так, чтобы он указывал на общедоступный URL, который может принимать OAuth-callback.

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

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 использует хранилище на основе связки ключей (keychain), где это доступно, или ~/.qwen/mcp-oauth-tokens-v2.json с шифрованием AES-256-GCM.
• Обновляются по истечении срока действия (если доступны токены обновления)
• Проверяются перед каждой попыткой подключения

[!WARNING] By default, OAuth tokens are stored unencrypted on disk. On shared or multi-user machines, set QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true to protect credentials.

Используйте диалог /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-серверов

Оба списка поддерживают glob-шаблоны: * соответствует любой последовательности символов, а ? — одному символу (например, "*puppeteer*" соответствует каждому серверу, имя которого содержит puppeteer). Записи без glob-символов сопоставляются точно. Если сервер соответствует обоим спискам, mcp.excluded имеет приоритет.

Пример:

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

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

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

Справочник

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

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

Добавьте объект 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
    }
  }
}

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

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

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

Управление 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>