MCP-серверы с Qwen Code

В этом документе приведено руководство по настройке и использованию серверов протокола контекста моделей (MCP) с Qwen Code.

Что такое сервер MCP?

Сервер MCP — это приложение, которое предоставляет инструменты и ресурсы CLI через протокол Model Context Protocol (MCP), позволяя ему взаимодействовать с внешними системами и источниками данных. Серверы MCP выступают в роли моста между моделью и вашей локальной средой или другими сервисами, например API.

Сервер MCP позволяет CLI:

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

С помощью сервера MCP вы можете расширить возможности CLI для выполнения действий, выходящих за рамки встроенных функций: взаимодействия с базами данных, API, пользовательскими скриптами или специализированными рабочими процессами.

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

Qwen Code интегрируется с серверами MCP через сложную систему обнаружения и выполнения, встроенную в основной пакет (packages/core/src/tools/):

Слой обнаружения (`mcp-client.ts`)

Процесс обнаружения управляется функцией discoverMcpTools(), которая:

Перебирает настроенные серверы, указанные в конфигурации mcpServers вашего файла settings.json
Устанавливает соединения с использованием соответствующих механизмов передачи данных (Stdio, SSE или потоковый HTTP)
Получает определения инструментов с каждого сервера по протоколу MCP
Очищает и проверяет схемы инструментов на совместимость с API Qwen
Регистрирует инструменты в глобальном реестре инструментов с разрешением конфликтов

Слой выполнения (`mcp-tool.ts`)

Каждый обнаруженный инструмент MCP оборачивается в экземпляр DiscoveredMCPTool, который:

Обрабатывает логику подтверждения, основываясь на настройках доверия к серверу и предпочтениях пользователя
Управляет выполнением инструмента, вызывая сервер MCP с правильными параметрами
Обрабатывает ответы как для контекста LLM, так и для отображения пользователю
Поддерживает состояние соединения и обрабатывает таймауты

Механизмы передачи данных

CLI поддерживает три типа транспорта MCP:

Транспорт через stdio: Запускает дочерний процесс и взаимодействует через stdin/stdout
Транспорт через SSE (Server-Sent Events): Подключается к конечным точкам Server-Sent Events
Потоковый HTTP-транспорт: Использует 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": "путь/к/исполняемому-файлу",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./каталог-сервера",
      "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 Client ID, добавленный в «белый список» для приложения, защищённого 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 ваша локальная машина должна:

Поддерживать открытие веб-браузера для аутентификации
Принимать перенаправления по адресу http://localhost:7777/oauth/callback

Эта функция не будет работать в следующих средах:

Безголовых (headless) средах без доступа к браузеру
Удалённых сессиях SSH без проброса X11
Контейнеризированных средах без поддержки браузера

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

Для управления аутентификацией OAuth используйте команду /mcp auth:


 
# Список серверов, требующих аутентификации
/mcp auth
 
# Аутентификация на конкретном сервере
/mcp auth serverName
 
# Повторная аутентификация при истечении срока действия токенов
/mcp auth serverName

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

enabled (логическое значение): включить OAuth для этого сервера
clientId (строка): идентификатор клиента OAuth (необязательно при динамической регистрации)
clientSecret (строка): секрет клиента OAuth (необязательно для публичных клиентов)
authorizationUrl (строка): конечная точка авторизации OAuth (автоматически обнаруживается, если не указана)
tokenUrl (строка): конечная точка выдачи токенов OAuth (автоматически обнаруживается, если не указана)
scopes (массив строк): обязательные области OAuth
redirectUri (строка): пользовательский URI перенаправления (по умолчанию http://localhost:7777/oauth/callback)
tokenParamName (строка): имя параметра запроса для токенов в URL SSE
audiences (массив строк): аудитории, для которых действителен токен

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

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

Безопасно сохраняются в ~/.qwen/mcp-oauth-tokens.json
Обновляются, когда срок их действия истекает (если доступны токены обновления)
Проверяются на валидность, перед каждой попыткой подключения
Удаляются, если они недействительны или срок их действия истёк

Тип поставщика аутентификации

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

authProviderType (строка): указывает поставщика аутентификации. Допустимые значения:
- dynamic_discovery (значение по умолчанию): CLI автоматически обнаружит конфигурацию OAuth на сервере.
- google_credentials: CLI будет использовать учётные данные Google Application Default Credentials (ADC) для аутентификации на сервере. При использовании этого поставщика необходимо явно указать требуемые области доступа (scopes).
- 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 client ID или используйте существующий. Чтобы использовать существующий OAuth 2.0 client ID, выполните шаги из раздела Как делиться клиентами OAuth .
Добавьте OAuth ID в список разрешённых для программного доступа к приложению. Поскольку Cloud Run пока не поддерживается как тип ресурса в gcloud iap, необходимо добавить client ID в список разрешённых на уровне проекта.
Создайте учётную запись службы. Документация , Ссылка на Cloud Console
Добавьте как учётную запись службы, так и пользователей в политику IAP, используя вкладку «Безопасность» в консоли Cloud Run или команду gcloud.
Предоставьте всем пользователям и группам, которые будут получать доступ к серверу MCP, необходимые разрешения для представления учётной записи службы (т. е. роль roles/iam.serviceAccountTokenCreator).
Включите API учётных данных IAM для вашего проекта.

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

Сервер MCP на Python (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
    }
  }
}

Сервер MCP на Node.js (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
    }
  }
}

SSE-сервер MCP с имперсонацией учётной записи службы


{
  "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; // Подтверждение не требуется
}

Динамический список разрешённых элементов

Система поддерживает внутренние списки разрешённых элементов для:

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

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

Если требуется подтверждение, пользователь может выбрать одно из следующих действий:

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

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

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

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

Вызов MCP: Внутренний объект CallableTool выполняет вызов сервера со следующими параметрами:


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

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

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

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

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

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

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

Команда /mcp предоставляет исчерпывающую информацию о вашей настройке сервера MCP:


/mcp

Это отображает:

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

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


Статус серверов MCP:

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

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

🐳 dockerizedServer (ПОДКЛЮЧЕН)
  Команда: 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
Обработка ошибок: Проверьте, не выбрасывает ли ваш инструмент необработанные исключения
Проблемы с таймаутом: Рассмотрите возможность увеличения значения параметра timeout

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

Симптомы: Серверы MCP завершаются с ошибкой при включённом режиме песочницы

Решения:

Серверы на основе Docker: Используйте контейнеры Docker, включающие все необходимые зависимости
Доступность путей: Убедитесь, что исполняемые файлы сервера доступны внутри песочницы
Доступ к сети: Настройте песочницу так, чтобы она разрешала необходимые сетевые подключения
Переменные окружения: Убедитесь, что требуемые переменные окружения передаются в песочницу

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

Включите режим отладки: Запустите CLI с флагом --debug, чтобы получить подробный вывод
Проверьте stderr: Стандартный поток ошибок (stderr) сервера MCP перехватывается и записывается в лог (сообщения уровня INFO фильтруются)
Изолируйте тестирование: Протестируйте свой сервер MCP независимо перед интеграцией
Поэтапная настройка: Начните с простых инструментов, прежде чем добавлять сложную функциональность
Часто используйте /mcp: Отслеживайте состояние сервера в процессе разработки

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

Аспекты безопасности

Настройки доверия: Опция trust отключает все диалоговые окна подтверждения. Используйте её осторожно и только для серверов, полностью находящихся под вашим контролем
Токены доступа: Будьте внимательны к вопросам безопасности при настройке переменных окружения, содержащих ключи API или токены
Совместимость с песочницей: При использовании песочницы убедитесь, что серверы MCP доступны внутри среды песочницы
Конфиденциальные данные: Использование персональных токенов доступа с широкой областью действия может привести к утечке информации между репозиториями

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

Постоянство соединений: CLI поддерживает постоянные соединения с серверами, которые успешно зарегистрировали инструменты.
Автоматическая очистка: Соединения с серверами, не предоставляющими инструментов, автоматически закрываются.
Управление таймаутами: Настройте соответствующие таймауты в зависимости от характеристик ответов вашего сервера.
Мониторинг ресурсов: Серверы MCP запускаются как отдельные процессы и потребляют системные ресурсы.

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

Режим соответствия схемам: По умолчанию (schemaCompliance: "auto") схемы инструментов передаются без изменений. Чтобы преобразовать модели в строгий формат OpenAPI 3.0, задайте параметр "model": { "generationConfig": { "schemaCompliance": "openapi_30" } } в файле settings.json.
Преобразования OpenAPI 3.0: При включённом режиме openapi_30 система обрабатывает:
- Типы, допускающие значение null: ["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="reverent"

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


/poem-writer "Qwen Code" reverent

При выполнении этой команды CLI вызывает метод prompts/get на сервере MCP с указанными аргументами. Сервер отвечает за подстановку аргументов в шаблон подсказки и возврат итогового текста подсказки. Затем CLI отправляет эту подсказку модели для выполнения. Это обеспечивает удобный способ автоматизации и совместного использования типовых рабочих процессов.

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

Хотя вы всегда можете настраивать серверы MCP, вручную редактируя файл settings.json, интерфейс командной строки предоставляет удобный набор команд для программного управления конфигурациями серверов. Эти команды упрощают добавление, вывод списка и удаление серверов MCP без необходимости прямого редактирования JSON-файлов.

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

Команда add настраивает новый сервер MCP в вашем файле settings.json. В зависимости от области видимости (-s, --scope) он будет добавлен либо в пользовательский конфигурационный файл ~/.qwen/settings.json, либо в проектный конфигурационный файл .qwen/settings.json.

Команда:


qwen mcp add [опции] <имя> <команда_или_url> [аргументы...]

<имя>: Уникальное имя сервера.
<команда_или_url>: Команда для выполнения (для транспорта stdio) или URL-адрес (для транспортов http/sse).
[аргументы...]: Необязательные аргументы для команды stdio.

Опции (флаги):

-s, --scope: Область видимости конфигурации (пользовательская или проектная). [по умолчанию: «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: Список инструментов для исключения, разделённый запятыми.

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

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


 
# Базовый синтаксис
qwen mcp add <имя> <команда> [аргументы...]
 
# Пример: добавление локального сервера
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 <имя> <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 <имя> <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"  
 
### Управление серверами (`qwen mcp`)  
 
Чтобы просмотреть и управлять всеми настроенными в данный момент серверами MCP, используйте команду `manage` или просто `qwen mcp`. Это откроет интерактивный TUI-диалог, в котором можно:  
 
- Просматривать все серверы MCP с их статусом подключения  
- Включать и отключать серверы  
- Повторно подключаться к отключённым серверам  
- Просматривать инструменты и подсказки, предоставляемые каждым сервером  
- Просматривать журналы сервера  
 
**Команда:**  
 
```bash  
qwen mcp  
 
# или  
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

Имперсонация учётной записи службы

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

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

Сервер MCP на Python (Stdio)

Сервер MCP на Node.js (Stdio)

Сервер MCP на базе Docker

MCP-сервер на основе HTTP

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

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

SSE-сервер MCP с имперсонацией учётной записи службы

Подробный разбор процесса обнаружения

1. Итерация сервера и установка соединения

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

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

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

5. Управление подключениями

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

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

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

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

Динамический список разрешённых элементов

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

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

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

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

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

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

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

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

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

Состояние сервера (MCPServerStatus)

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

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

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

Не обнаружено ни одного инструмента

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

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

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

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

Аспекты безопасности

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

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

Возврат насыщенного контента из инструментов

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

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

Промпты MCP как команды с косой чертой

Определение промптов на сервере

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

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

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

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

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

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

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

Слой обнаружения (`mcp-client.ts`)

Слой выполнения (`mcp-tool.ts`)

Глобальные параметры MCP (`mcp`)

Конфигурация, специфичная для сервера (`mcpServers`)

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

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

Состояние сервера (`MCPServerStatus`)

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

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

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

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