Подключение 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 — длительный вызов инструмента не является патологией запуска.

Автоматическое согласование stdio

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

{
  "mcpServers": {
    "modern-server": {
      "command": "node",
      "args": ["./server.js"],
      "versionNegotiation": "auto",
    },
  },
}

Автоматическое согласование запускает временную копию настроенного сервера перед запуском процесса сессии и может использовать до пяти секунд из бюджета обнаружения. Оставляйте политику legacy по умолчанию для серверов с не-идемпотентными побочными эффектами при запуске, эксклюзивными блокировками или PID-файлами, или с медленными рукопожатиями инициализации.

Откат прогрессивного MCP

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

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

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

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

Воспроизведение при потере соединения

Qwen Code повторно подключается и воспроизводит текущий вызов MCP-инструмента только в том случае, если у сервера указано trust: true, рабочее пространство является доверенным, а инструмент явно объявляет либо idempotentHint: true, либо аннотацию только для чтения. Аннотации только для чтения конфликтуют с destructiveHint: true или idempotentHint: false и не воспроизводятся.

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

Аннотации — это поведенческие подсказки, предоставляемые сервером, а не разрешения или граница авторизации. Настраивайте 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, затем направьте reverse-proxy с этого пути на http://127.0.0.1:7777/oauth/callback на машине, где запущен Qwen Code. Qwen Code не завершает TLS; это должен делать прокси.

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

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

Например, reverse proxy может перенаправлять только этот путь callback на локальный слушатель:

location = /oauth/callback {
  proxy_pass http://127.0.0.1:7777;
}

Ручная настройка через 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>