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

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

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

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

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

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

Stdio Transport: Создает подпроцесс и взаимодействует через stdin/stdout
SSE Transport: Подключается к конечным точкам Server-Sent Events
Streamable 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 (string): Глобальная команда для запуска сервера MCP.
mcp.allowed (array of strings): Список имен серверов MCP, которым разрешено подключение. Если этот параметр установлен, подключение будет осуществляться только к серверам из этого списка (соответствующим ключам в объекте mcpServers).
mcp.excluded (array of strings): Список имен серверов MCP, которым запрещено подключение. Серверы из этого списка не будут подключаться.

Пример:


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

Серверная конфигурация (`mcpServers`)

Объект mcpServers — это место, где вы определяете каждый отдельный сервер MCP, к которому вы хотите подключить CLI.

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

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


{ ...файл содержит другие объекты конфигурации
  "mcpServers": {
    "имяСервера": {
      "command": "путь/к/серверу",
      "args": ["--арг1", "значение1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./каталог-сервера",
      "timeout": 30000,
      "trust": false
    }
  }
}

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

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

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

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

Управление аутентификацией 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`** (string): Определяет поставщика аутентификации. Может быть одним из следующих:
  - **`dynamic_discovery`** (по умолчанию): CLI автоматически обнаружит конфигурацию OAuth с сервера.
  - **`google_credentials`**: CLI будет использовать учетные данные Google Application Default Credentials (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 Client ID, внесенный в белый список защищенного IAP приложения, к которому вы пытаетесь получить доступ.
targetServiceAccount (строка): Адрес электронной почты сервисной учетной записи Google Cloud, от имени которой будет выполнена имперсонализация.

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

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

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

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

Сервер 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"
      }
    }
  }
}

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 сервер с имперсонализацией SA


{
  "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. Разрешение конфликтов

Когда несколько серверов предоставляют инструменты с одинаковыми именами:

Первая регистрация побеждает: Первый сервер, зарегистрировавший имя инструмента, получает имя без префикса
Автоматическое добавление префикса: Последующие серверы получают имена с префиксом: имяСервера__имяИнструмента
Отслеживание реестра: Реестр инструментов поддерживает сопоставления между именами серверов и их инструментами

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 (ПОДКЛЮЧЕН)
  Команда: 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: Обнаружение завершено (с ошибками или без)

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

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

Симптомы: Сервер показывает статус ОТКЛЮЧЕН

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

Проверьте конфигурацию: Убедитесь, что command, args и cwd указаны правильно
Протестируйте вручную: Запустите команду сервера напрямую, чтобы убедиться, что она работает
Проверьте зависимости: Убедитесь, что все необходимые пакеты установлены
Просмотрите логи: Ищите сообщения об ошибках в выводе CLI
Проверьте разрешения: Убедитесь, что CLI может выполнить команду сервера

Инструменты не обнаружены

Симптомы: Сервер подключается, но инструменты недоступны

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

Проверьте регистрацию инструментов: Убедитесь, что ваш сервер действительно регистрирует инструменты
Проверьте протокол MCP: Убедитесь, что ваш сервер правильно реализует список инструментов MCP
Просмотрите логи сервера: Проверьте вывод stderr на наличие ошибок на стороне сервера
Протестируйте список инструментов: Вручную протестируйте конечную точку обнаружения инструментов вашего сервера

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

Симптомы: Инструменты обнаруживаются, но завершаются с ошибкой во время выполнения

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

Проверка параметров: Убедитесь, что ваш инструмент принимает ожидаемые параметры
Совместимость схем: Проверьте, что ваши входные схемы являются действительными JSON Schema
Обработка ошибок: Проверьте, не выбрасывает ли ваш инструмент необработанные исключения
Проблемы с таймаутом: Рассмотрите возможность увеличения параметра timeout

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

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

Решения:

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

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

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

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

Соображения безопасности

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

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

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

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

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

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

Вот небольшой пример сервера 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

Аутентификация с определённым сервером

Повторная аутентификация при истечении срока действия токенов

Имперсонализация сервисной учетной записи

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

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

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

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

Сервер MCP на основе Docker

HTTP-сервер MCP

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

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

SSE MCP сервер с имперсонализацией SA

Подробное погружение в процесс обнаружения

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`)