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 или потоковый HTTP)
Получает определения инструментов от каждого сервера по протоколу MCP
Очищает и проверяет схемы инструментов на совместимость с API Qwen
Регистрирует инструменты в глобальном реестре инструментов с разрешением конфликтов

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

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

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

Механизмы транспорта

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

Stdio Transport: Запускает дочерний процесс и взаимодействует через stdin/stdout
SSE Transport: Подключается к конечным точкам Server-Sent Events
Потоковый 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 (строка): Глобальная команда для запуска сервера 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": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

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

Каждая конфигурация сервера поддерживает следующие свойства:

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

command (строка): Путь к исполняемому файлу для транспорта Stdio
url (строка): URL-адрес конечной точки SSE (например, "http://localhost:8080/sse")
httpUrl (строка): 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, добавленный в список разрешенных для приложения, защищенного IAP, к которому вы пытаетесь получить доступ. Используется с authProviderType: 'service_account_impersonation'.
targetServiceAccount (string): Email-адрес сервисного аккаунта 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

Эта функция не будет работать в:

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

Управление аутентификацией 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)
tokenParamName (string): Имя параметра запроса для токенов в URL-адресах SSE
audiences (string[]): Аудитории, для которых действителен токен



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

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

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

#### Тип провайдера аутентификации

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

- **`authProviderType`** (строка): Указывает провайдер аутентификации. Может принимать одно из следующих значений:
  - **`dynamic_discovery`** (по умолчанию): CLI автоматически обнаружит конфигурацию OAuth с сервера.
  - **`google_credentials`**: CLI будет использовать учетные данные приложения Google по умолчанию (ADC) для аутентификации на сервере. При использовании этого провайдера необходимо указать требуемые области доступа (scopes).
  - **`service_account_impersonation`**: CLI будет выступать от имени сервисного аккаунта Google Cloud для аутентификации на сервере. Это полезно при получении доступа к службам, защищенным IAP (в частности, это было разработано для служб Cloud Run).

#### Учетные данные Google

```json
{
  "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, которую нужно олицетворить.

Интерфейс командной строки будет использовать ваши локальные учетные данные приложения по умолчанию (ADC) для генерации токена идентификатора OIDC для указанной учетной записи службы и аудитории. Затем этот токен будет использоваться для аутентификации на сервере MCP.

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

Создайте или используйте существующий идентификатор клиента OAuth 2.0. Чтобы использовать существующий идентификатор клиента OAuth 2.0, выполните шаги из раздела Как делиться клиентами OAuth .
Добавьте OAuth ID в список разрешенных для программного доступа к приложению. Поскольку Cloud Run еще не поддерживается как тип ресурса в gcloud iap, вы должны добавить Client ID в белый список на уровне проекта.
Создайте учетную запись службы. Документация , Ссылка на консоль Cloud
Добавьте учетную запись службы и пользователей в политику IAP на вкладке “Безопасность” самого сервиса Cloud Run или через gcloud.
Предоставьте всем пользователям и группам, которые будут иметь доступ к серверу MCP, необходимые разрешения для имперсонализации учетной записи службы (т.е. roles/iam.serviceAccountTokenCreator).
Включите API учетных данных IAM для вашего проекта.

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

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 сервер с имперсонацией сервисного аккаунта


{
  "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,
  },
];

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

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

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

llmContent: Необработанные части ответа для контекста языковой модели
returnDisplay: Форматированный вывод для отображения пользователю (часто JSON в блоках кода markdown)

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

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

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


/mcp

Отображает:

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

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


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

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

🔌 nodeServer (DISCONNECTED)
  Команда: node dist/server.js --verbose
  Ошибка: В соединении отказано

🐳 dockerizedServer (CONNECTED)
  Команда: docker run -i --rm -e API_KEY my-mcp-server:latest
  Инструменты: docker__deploy, docker__status

Состояние обнаружения: 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 записывается в журнал (информационные сообщения фильтруются)
Изолируйте тестирование: Протестируйте сервер MCP отдельно перед интеграцией
Настройка поэтапно: Начните с простых инструментов, прежде чем добавлять сложный функционал
Часто используйте /mcp: Следите за статусом сервера во время разработки

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

Вопросы безопасности

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

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

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

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

Удаление свойств: Система автоматически удаляет определенные свойства схемы ($schema, additionalProperties) для совместимости с Qwen API
Очистка имен: Имена инструментов автоматически очищаются для соответствия требованиям 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. Это позволяет создавать ярлыки для часто используемых или сложных запросов, которые можно легко вызывать по имени.

Определение подсказок на сервере

Вот небольшой пример 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: Область конфигурации (пользовательская или проектная). [по умолчанию: “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 <name> <command> [args...]
 
# Пример: добавление локального сервера
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 <name> <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 <name> <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 list`)

Чтобы просмотреть все настроенные MCP-серверы, используйте команду `list`. Она отображает имя каждого сервера, сведения о конфигурации и состояние подключения.

**Команда:**

```bash
qwen mcp list

Пример вывода:


✓ stdio-server: command: python3 server.py (stdio) - Подключен
✓ http-server: https://api.example.com/mcp (http) - Подключен
✗ sse-server: https://api.example.com/sse (sse) - Отключен

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

Олицетворение учетной записи службы

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

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

Python MCP сервер (Stdio)

Node.js MCP сервер (Stdio)

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

HTTP-сервер MCP

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

Сервер 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-сервера

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

Пример: Добавление 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`)