MCP Course, юнит 2: MCP-приложение от начала до конца

Это перевод юнита 2 курса MCP Course. Разделы 2.1–2.6 переведены целиком; раздел 2.7 о запуске на нейропроцессорах AMD (Lemonade Server) кратко пересказан: он нужен только владельцам ноутбуков AMD Ryzen AI. Предыдущий юнит: часть 1 и часть 2. Путеводитель по курсу — здесь.

Как читать вместе с курсом ChinaAI

Юнит собирает из кусочков юнита 1 работающее приложение: сервер-инструмент → клиенты → агент. Это хорошая практика к уроку 8.3.2 после того, как вы написали свой сервер на SDK. Код рассчитан на облачные модели через провайдеров Hugging Face, но почти всё можно запустить на вашей машине с локальной моделью — мы отметили, как. Учтите две вещи. Во-первых, курс подключается к Gradio по транспорту HTTP+SSE, который в спецификации уже объявлен устаревшим (его заменил Streamable HTTP), — для учёбы это не мешает. Во-вторых, инструмент тональности TextBlob понимает только английский текст.

2.1. Строим MCP-приложение от начала до конца

Добро пожаловать в юнит 2 курса по MCP!

В этом юните мы с нуля построим полноценное MCP-приложение: создадим сервер на Gradio и подключим к нему несколько клиентов. Такая практика даст вам опыт работы со всей экосистемой MCP.

Совет

В этом юните мы построим простой MCP-сервер и клиент с помощью Gradio и Hugging Face Hub. В следующем юните мы построим более сложный сервер для реальной задачи.

Чему вы научитесь

В этом юните вы:

• создадите MCP-сервер на встроенной поддержке MCP в Gradio;
• сделаете инструмент анализа тональности, которым смогут пользоваться модели ИИ;
• подключитесь к серверу разными клиентами:
  • клиентом на HuggingFace.js;
  • клиентом на Python на основе smolagents;
• развернёте MCP-сервер в Hugging Face Spaces;
• протестируете и отладите всю систему.

К концу юнита у вас будет работающее MCP-приложение, которое показывает силу и гибкость протокола.

Что нужно заранее

Прежде чем браться за юнит, убедитесь, что вы:

• прошли юнит 1 или в общих чертах понимаете понятия MCP;
• уверенно чувствуете себя и в Python, и в JavaScript/TypeScript;
• в общих чертах понимаете API и клиент-серверную архитектуру;
• подготовили среду разработки:
  • Python 3.10+;
  • Node.js 18+;
  • аккаунт Hugging Face (для развёртывания).

(Примечание переводчика: если JavaScript вы не знаете, ничего страшного — везде, где есть вкладки, берите вариант на Python. Node.js всё равно понадобится: через npx запускаются вспомогательные программы вроде mcp-remote.)

Наш сквозной проект

Мы построим приложение для анализа тональности текста (sentiment analysis). Оно состоит из трёх основных частей: сервер, клиент и развёртывание.

flowchart LR
subgraph S["Сервер: app.py на Gradio"]
  F["sentiment_analysis()<br/>TextBlob"]
  W["Веб-интерфейс"]
  M["MCP-эндпоинт<br/>/gradio_api/mcp/sse"]
  F --- W
  F --- M
end
subgraph C["Клиенты"]
  C1["Cursor / Continue"]
  C2["Gradio + smolagents"]
  C3["tiny agents<br/>(Python или JS)"]
end
C1 --> M
C2 --> M
C3 --> M
S -. "git push" .-> HF["Hugging Face Spaces"]

Сквозной проект юнита 2 (рисунок переводчика; в оригинале — похожая схема)

Сервер

• С помощью gr.Interface Gradio создаёт веб-интерфейс и MCP-сервер.
• Инструмент анализа тональности реализован на библиотеке TextBlob.
• Инструмент доступен и по HTTP, и по протоколу MCP.

Клиент

• Реализуем клиент на HuggingFace.js
• или клиент на Python на smolagents.
• Покажем, как один и тот же сервер работает с разными реализациями клиента.

Развёртывание

• Развернём сервер в Hugging Face Spaces.
• Настроим клиенты на работу с развёрнутым сервером.

Начнём!

Готовы построить своё первое MCP-приложение от начала до конца? Начнём с подготовки среды разработки и создания MCP-сервера на Gradio.

2.2. Строим MCP-сервер на Gradio

В этом разделе мы создадим на Gradio MCP-сервер для анализа тональности. Сервер предоставит инструмент анализа тональности, которым смогут пользоваться и люди через веб-интерфейс, и модели ИИ через протокол MCP.

Как Gradio работает с MCP

Gradio даёт простой способ создавать MCP-серверы: он автоматически превращает ваши функции на Python в инструменты MCP. Когда вы ставите mcp_server=True в launch(), Gradio:

1. автоматически превращает ваши функции в инструменты MCP;
2. отображает компоненты ввода в схемы аргументов инструментов;
3. определяет формат ответа по компонентам вывода;
4. настраивает JSON-RPC поверх HTTP+SSE для обмена между клиентом и сервером;
5. создаёт и веб-интерфейс, и эндпоинт MCP-сервера.

Готовим проект

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

mkdir mcp-sentiment
cd mcp-sentiment
python -m venv venv
source venv/bin/activate  # в Windows: venv\Scripts\activate
pip install "gradio[mcp]" textblob

(Что делают команды: создают папку проекта и переходят в неё, создают виртуальное окружение Python, включают его и ставят Gradio с поддержкой MCP и TextBlob. Подробно о виртуальных окружениях — в уроке 0.1.2.)

Создаём сервер

Hugging Face Spaces для сборки Space нужен файл app.py. Поэтому файл на Python должен называться app.py.

Создайте файл app.py с таким кодом:

import json
import gradio as gr
from textblob import TextBlob

def sentiment_analysis(text: str) -> str:
    """
    Analyze the sentiment of the given text.

    Args:
        text (str): The text to analyze

    Returns:
        str: A JSON string containing polarity, subjectivity, and assessment
    """
    blob = TextBlob(text)
    sentiment = blob.sentiment

    result = {
        "polarity": round(sentiment.polarity, 2),  # от -1 (негатив) до 1 (позитив)
        "subjectivity": round(sentiment.subjectivity, 2),  # от 0 (объективно) до 1 (субъективно)
        "assessment": "positive" if sentiment.polarity > 0 else "negative" if sentiment.polarity < 0 else "neutral"
    }

    return json.dumps(result)

# Создаём интерфейс Gradio
demo = gr.Interface(
    fn=sentiment_analysis,
    inputs=gr.Textbox(placeholder="Enter text to analyze..."),
    outputs=gr.Textbox(),  # заменили gr.JSON() на gr.Textbox()
    title="Text Sentiment Analysis",
    description="Analyze the sentiment of text using TextBlob"
)

# Запускаем интерфейс и MCP-сервер
if __name__ == "__main__":
    demo.launch(mcp_server=True)

(Докстринг оставлен на английском — из него Gradio делает описание инструмента для модели. Перевод: «Определить тональность текста. Аргументы: text — текст для анализа. Возвращает: строку JSON с полярностью, субъективностью и оценкой». Полярность (polarity) — насколько текст позитивен или негативен, субъективность (subjectivity) — насколько это мнение, а не факт.)

Разбираем код

Пройдём по главным частям:

1. Определение функции.

   • Функция sentiment_analysis принимает текст и возвращает строковое представление словаря JSON.
   • Тональность она определяет с помощью TextBlob.
   • Докстринг критически важен: по нему Gradio строит схему инструмента MCP.
   • Аннотации типов (str и dict) помогают задать схему входа и выхода.

2. Интерфейс Gradio.

   • gr.Interface создаёт и веб-интерфейс, и MCP-сервер.
   • Функция автоматически становится инструментом MCP.
   • Компоненты ввода и вывода задают схему инструмента.
   • Компонент вывода JSON обеспечивает правильную сериализацию.

3. MCP-сервер.

   • mcp_server=True включает MCP-сервер.
   • Сервер будет доступен по адресу http://localhost:7860/gradio_api/mcp/sse.
   • Включить его можно и переменной окружения:

     export GRADIO_MCP_SERVER=True

(Примечание переводчика: в разборе остались следы старой версии кода. Функция возвращает str, а не dict, и вывод сделан текстовым полем gr.Textbox, а не gr.JSON — сериализацию в строку выполняет json.dumps.)

Примечание переводчика: TextBlob и русский текст

TextBlob оценивает тональность по словарю английских слов. Для русского текста он почти всегда вернёт полярность 0 («neutral»): «Это прекрасно!» и «Это ужасно!» для него одинаковы. Чтобы инструмент понимал русский, замените TextBlob на классификатор тональности из Hugging Face через transformers.pipeline("text-classification", model=...) — как дообучить такой русский энкодер самому, показано в уроке 4.5.4. Для учебного MCP-сервера достаточно и английских примеров.

Запускаем сервер

Запустите сервер командой:

python app.py

Вы увидите сообщения о том, что запущены и веб-интерфейс, и MCP-сервер. Веб-интерфейс будет доступен по адресу http://localhost:7860, а MCP-сервер — по адресу http://localhost:7860/gradio_api/mcp/sse.

Проверяем сервер

Проверить сервер можно двумя способами.

1. Веб-интерфейс.

   • Откройте в браузере http://localhost:7860.
   • Введите текст и нажмите «Submit».
   • Вы увидите результат анализа тональности.

2. Схема MCP.

   • Откройте http://localhost:7860/gradio_api/mcp/schema.
   • Здесь показана схема инструмента MCP, которой будут пользоваться клиенты.
   • Её также можно найти по ссылке «View API» внизу приложения Gradio.

(Пример от переводчика: на текст «I love this course!» TextBlob вернёт положительную полярность и оценку «positive», на «This is terrible.» — отрицательную и «negative». Точные числа зависят от словаря TextBlob.)

Советы при проблемах

1. Аннотации типов и докстринги.

   • Всегда указывайте аннотации типов у параметров и возвращаемого значения функции.
   • Добавляйте докстринг с блоком «Args:» для каждого параметра.
   • Так Gradio построит точные схемы инструментов MCP.

2. Строковые входы.

   • Если сомневаетесь, принимайте аргументы как str.
   • Преобразуйте их в нужный тип внутри функции.
   • Так совместимость с MCP-клиентами лучше.

3. Поддержка SSE.

   • Некоторые MCP-клиенты не поддерживают MCP-серверы на SSE.
   • В таких случаях используйте mcp-remote:

     {
       "mcpServers": {
         "gradio": {
           "command": "npx",
           "args": [
             "mcp-remote",
             "http://localhost:7860/gradio_api/mcp/sse"
           ]
         }
       }
     }

4. Проблемы с подключением.

   • Если возникают проблемы с подключением, перезапустите и клиент, и сервер.
   • Проверьте, что сервер запущен и доступен.
   • Убедитесь, что схема MCP открывается по ожидаемому адресу.

Разворачиваем в Hugging Face Spaces

Чтобы сервер был доступен другим, его можно развернуть в Hugging Face Spaces.

1. Создайте новый Space на Hugging Face:

   • откройте huggingface.co/spaces;
   • нажмите «New Space»;
   • дайте Space имя (например, «mcp-sentiment»);
   • выберите SDK «Gradio»;
   • нажмите «Create Space».

2. Создайте файл requirements.txt:

   gradio[mcp]
   textblob

3. Отправьте код в Space:

   git init
   git add app.py requirements.txt
   git commit -m "Initial commit"
   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/mcp-sentiment
   git push -u origin main

Теперь ваш MCP-сервер доступен по адресу:

https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse

(Примечание переводчика: YOUR_USERNAME — ваш логин на Hugging Face. При git push в качестве пароля вводится токен доступа с правом записи, а не пароль от аккаунта. Работа с git — в уроке 0.1.1.)

Что дальше

MCP-сервер работает — теперь создадим клиенты для работы с ним. В следующих разделах мы:

1. создадим клиент на HuggingFace.js по мотивам Tiny Agents;
2. реализуем клиент на Python на основе smolagents;
3. проверим оба клиента с развёрнутым сервером.

Переходим к первому клиенту!

2.3. Строим MCP-клиенты

В этом разделе мы создадим клиенты, которые умеют работать с нашим MCP-сервером, на разных языках программирования. Реализуем и клиент на JavaScript с HuggingFace.js, и клиент на Python со smolagents.

Настройка MCP-клиентов

Чтобы MCP-серверы и клиенты хорошо работали, их нужно правильно настроить. Спецификация MCP ещё развивается, поэтому способы настройки могут меняться. Мы сосредоточимся на нынешних лучших практиках.

Конфигурационные файлы MCP

MCP-хосты управляют подключениями к серверам через конфигурационные файлы. В них описано, какие серверы доступны и как к ним подключаться.

Эти файлы очень простые, понятные и единообразные у основных MCP-хостов.

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

Стандартный конфигурационный файл MCP называется mcp.json. Вот его базовая структура:

{
  "servers": [
    {
      "name": "MCP Server",
      "transport": {
        "type": "sse",
        "url": "http://localhost:7860/gradio_api/mcp/sse"
      }
    }
  ]
}

В этом примере один сервер, который использует транспорт SSE и подключается к локальному серверу Gradio на порту 7860.

Совет

Мы подключились к приложению Gradio по транспорту SSE, потому что предполагаем, что оно работает на удалённом сервере. Если же вы хотите подключиться к локальному скрипту, лучше использовать транспорт stdio, а не sse.

(Примечание переводчика: как и в юните 1, это условная схема курса. Настоящие клиенты ждут объект с именами серверов в качестве ключей — mcpServers у Claude Desktop и Cursor, servers у VS Code. Примеры реальных форматов — в переводе юнита 1.)

Настройка для транспорта HTTP+SSE

Для удалённых серверов с транспортом HTTP+SSE в конфигурации указывают URL сервера:

{
  "servers": [
    {
      "name": "Remote MCP Server",
      "transport": {
        "type": "sse",
        "url": "https://example.com/gradio_api/mcp/sse"
      }
    }
  ]
}

Такая конфигурация позволяет вашему клиенту с интерфейсом общаться с MCP-сервером Gradio по протоколу MCP и без швов связывает фронтенд с MCP-сервисом.

Настройка MCP-клиента с интерфейсом

Работая с MCP-серверами Gradio, клиент с интерфейсом можно настроить на подключение к серверу по протоколу MCP. Вот как.

Базовая конфигурация

Создайте файл config.json с такой конфигурацией:

{
  "mcpServers": {
    "mcp": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}

Такая конфигурация позволяет вашему клиенту с интерфейсом общаться с MCP-сервером Gradio по протоколу MCP.

Настройка MCP-клиента в Cursor IDE

В Cursor есть встроенная поддержка MCP: развёрнутые MCP-серверы можно подключить прямо к среде разработки.

Конфигурация

Откройте настройки Cursor (Ctrl + Shift + J / Cmd + Shift + J) → вкладка Tools & Integrations → Add Custom MCP:

macOS:

{
  "mcpServers": {
    "sentiment-analysis": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOURUSENAME-mcp-sentiment.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "sentiment-analysis": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://YOURUSENAME-mcp-sentiment.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}

(В Linux — как в варианте для macOS. YOURUSENAME — опечатка оригинала в слове USERNAME: подставьте свой логин.)

Зачем нужен mcp-remote

Примечание. С середины 2025 года Cursor поддерживает прямые подключения к удалённым MCP-серверам по HTTP+SSE и OAuth. mcp-remote может не понадобиться, если только вы не работаете со старыми настройками или не столкнулись с особыми проблемами совместимости.

Ранние версии MCP-клиентов, включая Cursor, поддерживали только локальные серверы через транспорт stdio и не умели работать с удалёнными серверами с аутентификацией. mcp-remote появился как обходной путь. Он:

• работает локально на вашей машине;
• соединяет Cursor с удалёнными MCP-серверами;
• незаметно берёт на себя транспорт и аутентификацию;
• использует привычный формат конфигурационного файла.

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

{
  "mcpServers": {
    "my-server": {
      "url": "https://your-mcp-server.hf.space/gradio_api/mcp/sse"
    }
  }
}

Актуальные инструкции по настройке — в официальной документации Cursor.

После настройки можно просить Cursor пользоваться вашим инструментом анализа тональности — например, анализировать комментарии в коде, отзывы пользователей или описания pull request.

2.4. MCP в ИИ-ассистенте для кода: локальные и открытые модели

В этом разделе мы подключим MCP к локальным и открытым моделям с помощью Continue — инструмента для создания ИИ-ассистентов программиста, который работает с локальными инструментами вроде Ollama.

Устанавливаем Continue

Continue можно установить из магазина расширений VS Code.

Совет

У Continue есть и расширение для JetBrains.

Расширение для VS Code

1. Нажмите Install на странице расширения Continue в Visual Studio Marketplace.
2. Откроется страница расширения Continue в VS Code — там снова нажмите Install.
3. Логотип Continue появится на левой боковой панели. Удобнее перенести Continue на правую панель.

(В оригинале — анимация переноса панели Continue вправо.)

Настроив Continue, перейдём к Ollama — скачаем локальные модели.

Локальные модели

Есть много способов запустить локальные модели, совместимые с Continue. Три популярных варианта — Ollama, Llama.cpp и LM Studio. Ollama — открытый инструмент, который позволяет легко запускать большие языковые модели (LLM) локально. Llama.cpp — высокопроизводительная библиотека на C++ для запуска LLM, в которую входит и OpenAI-совместимый сервер. LM Studio даёт графический интерфейс для запуска локальных моделей.

С Hugging Face Hub можно получить локальные модели вместе с командами и быстрыми ссылками для всех основных приложений локального инференса.

(В оригинале — скриншот страницы модели на Hub с кнопкой «Use this model» и списком локальных приложений.)

llama.cpp

Llama.cpp предоставляет llama-server — лёгкий HTTP-сервер для LLM, совместимый с OpenAI API. Его можно собрать из исходников по инструкции в репозитории Llama.cpp или взять готовую сборку для вашей системы, если она есть. Подробнее — в документации Llama.cpp.

Получив llama-server, можно запустить модель с Hugging Face такой командой:

llama-server -hf unsloth/Devstral-Small-2505-GGUF:Q4_K_M

LM Studio

LM Studio — приложение для Mac, Windows и Linux, которое позволяет легко запускать открытые модели локально через графический интерфейс. Чтобы начать:

1. Откройте модель unsloth/Devstral-Small-2505-GGUF в LM Studio (в оригинале — ссылка вида lmstudio://open_from_hf?model=…).
2. Когда модель скачается, перейдите на вкладку «Local Server» и нажмите «Start Server».

Ollama

Чтобы пользоваться Ollama, установите его и скачайте нужную модель командой ollama run.

Например, скачать и запустить модель Devstral-Small можно так:

ollama run hf.co/unsloth/Devstral-Small-2505-GGUF:Q4_K_M

Модель весит около 14 ГБ, так что убедитесь, что на машине достаточно свободной оперативной памяти. Иначе можно увидеть ошибку вроде «model requires more system memory than is available» («модели нужно больше системной памяти, чем доступно»).

Совет

Continue поддерживает разных поставщиков локальных моделей. Кроме Ollama, Llama.cpp и LM Studio, можно использовать и других. Полный список поддерживаемых поставщиков и подробные настройки — в документации Continue.

Важно использовать модели со встроенной поддержкой вызова инструментов, например Codestral, Qwen и Llama 3.1.

1. Создайте папку .continue/models в корне рабочей папки проекта.
2. Добавьте в неё файл с настройками поставщика модели, например local-models.yaml.
3. Добавьте в него конфигурацию — в зависимости от того, что вы используете: Ollama, Llama.cpp или LM Studio.

llama.cpp

Эта конфигурация — для модели llama.cpp, которую раздаёт llama-server. Обратите внимание: поле model должно совпадать с моделью, которую вы раздаёте.

name: Llama.cpp model
version: 0.0.1
schema: v1
models:
  - provider: llama.cpp
    model: unsloth/Devstral-Small-2505-GGUF
    apiBase: http://localhost:8080
    defaultCompletionOptions:
      contextLength: 8192 # подберите под модель
    name: Llama.cpp Devstral-Small
    roles:
      - chat
      - edit

LM Studio

Эта конфигурация — для модели, которую раздаёт LM Studio. Идентификатор модели должен совпадать с тем, что загружено в LM Studio.

name: LM Studio Model
version: 0.0.1
schema: v1
models:
  - provider: lmstudio
    model: unsloth/Devstral-Small-2505-GGUF
    name: LM Studio Devstral-Small
    apiBase: http://localhost:1234/v1
    roles:
      - chat
      - edit

Ollama

Эта конфигурация — для модели Ollama.

name: Ollama Devstral model
version: 0.0.1
schema: v1
models:
  - provider: ollama
    model: unsloth/devstral-small-2505-gguf:Q4_K_M
    defaultCompletionOptions:
      contextLength: 8192
    name: Ollama Devstral-Small
    roles:
      - chat
      - edit

По умолчанию у каждой модели есть максимальная длина контекста — в данном случае 128000 токенов. Наша схема активнее расходует это окно контекста, выполняя несколько запросов к MCP, и должна справляться с большим числом токенов.

(Примечание переводчика: в конфигурациях выше contextLength: 8192 — это сколько контекста Continue будет использовать, а 128 000 — предел самой модели Devstral. Если агент «забывает» начало разговора после нескольких вызовов инструментов, увеличьте contextLength, насколько позволяет память. На одной RTX 4080 модель Devstral Small (24B) в 4 битах помещается целиком, и контекст в 32 000 токенов тоже. Как устроены llama.cpp и квантование Q4_K_M — в уроках 7.2.1 и 7.2.2.)

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

Рукопожатие с инструментами

Инструменты — мощный способ дать моделям связь с внешним миром. Модели они передаются как объект JSON с именем и схемой аргументов. Например, инструмент read_file с аргументом filepath даёт модели возможность запросить содержимое конкретного файла.

(В оригинале — схема автономного агента: модель, инструменты, разрешения пользователя и цикл вызовов.)

Вот как агент использует инструменты:

1. В режиме агента доступные инструменты отправляются вместе с чат-запросами user.
2. Модель может включить в свой ответ вызов инструмента.
3. Пользователь даёт разрешение. Этот шаг пропускается, если для инструмента установлена политика Automatic.
4. Continue вызывает инструмент — своими встроенными средствами или через MCP-сервер, который этот инструмент предоставляет.
5. Continue отправляет результат обратно модели.
6. Модель отвечает — возможно, новым вызовом инструмента, и всё начинается снова с шага 2.

(Это тот же цикл «мысль → действие → наблюдение», что и в уроке 8.3.1.)

Continue поддерживает многих поставщиков локальных моделей. Для разных задач можно использовать разные модели или переключаться между ними по мере надобности. Этот раздел посвящён локальным решениям, но Continue работает и с популярными поставщиками вроде OpenAI, Anthropic, Microsoft/Azure, Mistral и другими. Можно подключить и собственного поставщика моделей.

Локальная модель и MCP

Всё настроено — добавим существующий MCP-сервер. Вот быстрый пример подключения нового MCP-сервера к ассистенту:

1. Создайте папку .continue/mcpServers в корне рабочей папки проекта.
2. Добавьте в неё файл playwright-mcp.yaml.
3. Запишите в playwright-mcp.yaml следующее и сохраните.

name: Playwright mcpServer
version: 0.0.1
schema: v1
mcpServers:
  - name: Browser search
    command: npx
    args:
      - "@playwright/mcp@latest"

Теперь проверьте MCP-сервер таким запросом:

1. Using playwright, navigate to https://news.ycombinator.com.

2. Extract the titles and URLs of the top 4 posts on the homepage.

3. Create a file named hn.txt in the root directory of the project.

4. Save this list as plain text in the hn.txt file, with each line containing the title and URL separated by a hyphen.

Do not output code or instructions—just complete the task and confirm when it is done.

(Перевод запроса: «1. С помощью playwright открой https://news.ycombinator.com. 2. Извлеки заголовки и URL четырёх верхних постов на главной. 3. Создай файл hn.txt в корне проекта. 4. Сохрани этот список простым текстом в hn.txt: в каждой строке заголовок и URL через дефис. Не выводи код или инструкции — просто выполни задачу и подтверди, когда закончишь». Запрос можно писать и по-русски, если модель хорошо понимает русский.)

В результате в текущей рабочей папке появится файл hn.txt.

(В оригинале — скриншот: Continue вызывает инструменты Playwright и создаёт файл.)

Заключение

Соединив Continue с локальными моделями вроде Llama 3.1 и MCP-серверами, вы получили мощный рабочий процесс: код и данные остаются у вас, а возможности ИИ — передовые.

Такая схема позволяет настраивать ИИ-ассистента специальными инструментами — от автоматизации браузера до работы с файлами, — и всё это целиком на вашей машине. Готовы поднять свой рабочий процесс на новый уровень? Начните экспериментировать с разными MCP-серверами со страницы MCP в Continue Hub и узнайте, как локальный ИИ может изменить вашу работу с кодом.

2.5. Gradio как MCP-клиент

В прошлом разделе мы создали MCP-сервер на Gradio и подключились к нему MCP-клиентом. В этом разделе мы посмотрим, как использовать Gradio в роли MCP-клиента, который подключается к MCP-серверу.

Совет

Gradio лучше всего подходит для создания клиентов с интерфейсом и MCP-серверов, но его можно использовать и как MCP-клиент, показывая его в виде интерфейса.

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

MCP-клиент в Gradio

Подключаемся к учебному MCP-серверу

Подключимся к учебному MCP-серверу, который уже работает на Hugging Face. Для примера возьмём вот этот — Space с набором инструментов MCP.

from smolagents.mcp_client import MCPClient

with MCPClient(
    {"url": "https://abidlabs-mcp-tool-http.hf.space/gradio_api/mcp/sse", "transport": "sse",}
) as tools:
    # Инструменты удалённого сервера доступны здесь
    print("\n".join(f"{t.name}: {t.description}" for t in tools))

Вывод:

prime_factors: Compute the prime factorization of a positive integer.
generate_cheetah_image: Generate a cheetah image.
image_orientation: Returns whether image is portrait or landscape.
sepia: Apply a sepia filter to the input image.

(Четыре инструмента: разложение положительного целого числа на простые множители, генерация картинки с гепардом, определение ориентации изображения (портретная или альбомная) и фильтр «сепия».)

Подключаемся к MCP-серверу из Gradio

Отлично, вы подключились к учебному MCP-серверу. Теперь воспользуемся им в приложении.

Сначала установим библиотеки smolagents, Gradio и mcp-client, если их ещё нет:

pip install "smolagents[mcp]" "gradio[mcp]" mcp fastmcp

Теперь импортируем нужные библиотеки и создадим простой интерфейс Gradio, который подключается к MCP-серверу через MCP-клиент.

import gradio as gr
import os

from mcp import StdioServerParameters
from smolagents import InferenceClientModel, CodeAgent, ToolCollection, MCPClient

Затем подключимся к MCP-серверу и получим инструменты, с помощью которых будем отвечать на вопросы.

mcp_client = MCPClient(
    {"url": "https://abidlabs-mcp-tool-http.hf.space/gradio_api/mcp/sse", "transport": "sse",} # Это MCP-клиент, который мы создали в прошлом разделе
)
tools = mcp_client.get_tools()

(Примечание переводчика: комментарий в оригинале неточен — по этому адресу работает учебный MCP-сервер, а клиент создаём мы сами в этой строке. Импорты StdioServerParameters и ToolCollection в коде дальше не используются.)

Инструменты есть — создадим простого агента, который отвечает на вопросы с их помощью. Пока возьмём простую InferenceClientModel и модель по умолчанию из smolagents.

Важно передать InferenceClientModel ваш ключ API. Токен можно получить в аккаунте Hugging Face (подробнее здесь) и задать в переменной окружения HF_TOKEN.

model = InferenceClientModel(token=os.getenv("HF_TOKEN"))
agent = CodeAgent(tools=[*tools], model=model)

Теперь создадим простой интерфейс Gradio, в котором агент отвечает на вопросы.

demo = gr.ChatInterface(
    fn=lambda message, history: str(agent.run(message)),
    type="messages",
    examples=["Prime factorization of 68"],
    title="Agent with MCP Tools",
    description="This is a simple agent that uses MCP tools to answer questions."
)

demo.launch()

Вот и всё! Мы создали простой интерфейс Gradio, который через MCP-клиент подключается к MCP-серверу и отвечает на вопросы.

(В оригинале здесь встроено работающее демо — Space mcp-course/unit2-gradio-client. Пример вопроса «Prime factorization of 68» — «Разложи 68 на простые множители»; правильный ответ: 68 = 2 × 2 × 17.)

Полный пример

Вот полный пример использования MCP-клиента в Gradio:

import gradio as gr
import os

from smolagents import InferenceClientModel, CodeAgent, MCPClient


try:
    mcp_client = MCPClient(
        {"url": "https://abidlabs-mcp-tool-http.hf.space/gradio_api/mcp/sse", "transport": "sse",}
    )
    tools = mcp_client.get_tools()

    model = InferenceClientModel(token=os.getenv("HUGGINGFACE_API_TOKEN"))
    agent = CodeAgent(tools=[*tools], model=model, additional_authorized_imports=["json", "ast", "urllib", "base64"])

    demo = gr.ChatInterface(
        fn=lambda message, history: str(agent.run(message)),
        type="messages",
        examples=["Analyze the sentiment of the following text 'This is awesome'"],
        title="Agent with MCP Tools",
        description="This is a simple agent that uses MCP tools to answer questions.",
    )

    demo.launch()
finally:
    mcp_client.disconnect()

Обратите внимание: мы закрываем MCP-клиент в блоке finally. Это важно, потому что MCP-клиент — долгоживущий объект, и его нужно закрыть при выходе из программы.

Примечание переводчика

• В полном примере токен читается из HUGGINGFACE_API_TOKEN, а выше — из HF_TOKEN. Выберите одно имя и задайте именно эту переменную окружения, иначе модель получит None вместо токена.
• additional_authorized_imports — список модулей, которые CodeAgent разрешено импортировать в коде, который пишет модель. Агент кода исполняет сгенерированный Python, поэтому по умолчанию импорты ограничены — это мера безопасности (подробнее — в уроке 8.3.4).
• Чтобы взять локальную модель вместо облачной, замените InferenceClientModel на OpenAIServerModel(model_id=..., api_base="http://localhost:8000/v1", api_key="EMPTY") из smolagents и поднимите модель в vLLM (урок 7.1.2).

Разворачиваем в Hugging Face Spaces

Чтобы приложение было доступно другим, его можно развернуть в Hugging Face Spaces — так же, как в прошлом разделе. Чтобы развернуть MCP-клиент на Gradio в Hugging Face Spaces:

1. Создайте новый Space на Hugging Face:

   • откройте huggingface.co/spaces;
   • нажмите «Create new Space»;
   • выберите SDK «Gradio»;
   • дайте Space имя (например, «mcp-client»).

2. Укажите в коде URL MCP-сервера:

   mcp_client = MCPClient(
       {"url": "https://abidlabs-mcp-tool-http.hf.space/gradio_api/mcp/sse", "transport": "sse"}
   )

3. Создайте файл requirements.txt:

   gradio[mcp]
   smolagents[mcp]

4. Отправьте код в Space:

   git init
   git add app.py requirements.txt
   git commit -m "Initial commit"
   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/mcp-client
   git push -u origin main

Примечание: при добавлении remote origin смотрите password-git-deprecation — как подключаться с токеном доступа вместо пароля.

(Примечание переводчика: токен для модели не кладите в код — в настройках Space есть раздел «Secrets», значения оттуда приложение получает как переменные окружения.)

Заключение

В этом разделе мы разобрали, как использовать Gradio в роли MCP-клиента, который подключается к MCP-серверу, и как развернуть такой клиент в Hugging Face Spaces.

2.6. Tiny Agents: агенты на MCP и Hugging Face Hub

Мы построили MCP-серверы на Gradio и научились создавать MCP-клиенты. Завершим наше сквозное приложение агентом, который без усилий работает с нашим инструментом анализа тональности. Раздел опирается на проект Tiny Agents, который показывает предельно простой способ разворачивать MCP-клиенты, подключающиеся к сервисам вроде нашего сервера тональности на Gradio.

В этом последнем упражнении юнита 2 мы покажем, как реализовать MCP-клиенты на TypeScript (JS) и на Python, которые умеют общаться с любым MCP-сервером, включая наш сервер анализа тональности на Gradio. Так замыкается весь путь нашего MCP-приложения: от MCP-сервера на Gradio с инструментом тональности до гибкого агента, который пользуется этим инструментом наряду с другими возможностями.

(В оригинале — шуточная картинка-мем о tiny agents, автор — https://x.com/adamdotdev.)

Установка

Установим пакеты, нужные для Tiny Agents.

Совет

Некоторые MCP-клиенты, в частности Claude Desktop, пока не поддерживают MCP-серверы на SSE. В таких случаях можно использовать программу вроде mcp-remote. Сначала установите Node.js. Затем добавьте следующее в конфигурацию своего MCP-клиента:

(В оригинале после этой подсказки фрагмент конфигурации пропущен; он такой же, как в разделе 2.2 «Советы при проблемах».)

Tiny Agent может запускать MCP-серверы как программы командной строки. Для этого понадобится установить npm и запускать сервер через npx. Это нужно и для Python, и для JavaScript.

Установим npx через npm. Если npm у вас не установлен, посмотрите документацию npm.

# устанавливаем npx
npm install -g npx

(Как и в юните 1: обычно npx уже есть вместе с npm.)

Затем установим пакет mcp-remote.

npm i mcp-remote

TypeScript

Для JavaScript нужно установить пакет tiny-agents.

npm install @huggingface/tiny-agents

Python

Для Python нужна свежая версия huggingface_hub с дополнением mcp — в ней есть все нужные компоненты.

pip install "huggingface_hub[mcp]>=0.32.0"

MCP-клиент Tiny Agents в командной строке

Повторим пример из юнита 1 и создадим простого Tiny Agent. Tiny Agents создают MCP-клиенты из командной строки по конфигурационным файлам JSON.

TypeScript

Создадим проект с простым Tiny Agent.

mkdir my-agent
touch my-agent/agent.json
cd my-agent

Файл JSON будет выглядеть так:

{
  "model": "Qwen/Qwen2.5-72B-Instruct",
    "provider": "novita",
  "servers": [
    {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/sse"
      ]
    }
  ]
}

Запустим агента командой:

npx @huggingface/tiny-agents run agent.json

Python

Создадим проект с простым Tiny Agent.

mkdir my-agent
touch my-agent/agent.json
cd my-agent

Файл JSON будет выглядеть так:

{
  "model": "Qwen/Qwen2.5-72B-Instruct",
    "provider": "novita",
  "servers": [
    {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/sse"
      ]
    }
  ]
}

Запустим агента командой:

tiny-agents run agent.json

Это простой Tiny Agent, который подключается к нашему MCP-серверу на Gradio. В нём есть модель, провайдер и конфигурация сервера.

Поле	Описание
model	открытая модель, на которой работает агент
provider	провайдер инференса для агента
servers	серверы, которыми пользуется агент. Для нашего MCP-сервера на Gradio используем mcp-remote

Совет

С Tiny Agents можно использовать и открытую модель, запущенную локально. Если запустить локальный сервер инференса, конфигурация будет такой:

{
  "model": "Qwen/Qwen3-32B",
  "endpointUrl": "http://localhost:1234/v1",
  "servers": [
    {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:1234/v1/mcp/sse"
      ]
    }
  ]
}

Здесь Tiny Agent подключается к локальной модели. В конфигурации есть модель, URL эндпоинта (http://localhost:1234/v1) и конфигурация сервера. Эндпоинт должен быть OpenAI-совместимым.

Примечание переводчика: ошибка в адресе сервера

В этом примере перепутаны два адреса. endpointUrl — адрес сервера модели (LM Studio, vLLM, llama.cpp), а в args у mcp-remote должен стоять адрес MCP-сервера — нашего приложения Gradio: http://localhost:7860/gradio_api/mcp/sse. У сервера модели по адресу /v1/mcp/sse никакого MCP нет. На вашей машине Qwen3-32B в bf16 не поместится в одну RTX 4080, но поместится в 4 карты через vLLM с --tensor-parallel-size 4 или в одну карту в 4-битном квантовании (урок 7.2.2).

Свой MCP-клиент на Tiny Agents

Теперь, когда мы понимаем и Tiny Agents, и MCP-серверы на Gradio, посмотрим, как они работают вместе! Красота MCP в том, что он даёт агентам стандартный способ работать с любым MCP-совместимым сервером, включая наш сервер анализа тональности на Gradio из прошлых разделов.

Подключаем сервер Gradio к Tiny Agents

Чтобы подключить Tiny Agent к серверу анализа тональности на Gradio, который мы построили в этом юните, достаточно добавить его в список серверов. Вот как изменить конфигурацию агента:

TypeScript

const agent = new Agent({
    provider: process.env.PROVIDER ?? "novita",
    model: process.env.MODEL_ID ?? "Qwen/Qwen2.5-72B-Instruct",
    apiKey: process.env.HF_TOKEN,
    servers: [
        // ... уже подключённые серверы ...
        {
            command: "npx",
            args: [
                "mcp-remote",
                "http://localhost:7860/gradio_api/mcp/sse"  // ваш MCP-сервер на Gradio
            ]
        }
    ],
});

Python

import os

from huggingface_hub import Agent

agent = Agent(
    model="Qwen/Qwen2.5-72B-Instruct",
    provider="novita",
    servers=[
        {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://localhost:7860/gradio_api/mcp/sse"  # ваш MCP-сервер на Gradio
            ]
        }
    ],
)

Теперь агент может пользоваться инструментом анализа тональности наряду с другими инструментами! Например, он может:

1. прочитать текст из файла с помощью сервера файловой системы;
2. определить его тональность с помощью нашего сервера на Gradio;
3. записать результат обратно в файл.

(Примечание переводчика: создать объект Agent мало — его нужно ещё запустить. В Python-версии huggingface_hub агент асинхронный: сначала await agent.load_tools(), затем ответы читаются из agent.run("ваш вопрос") в цикле async for. Точный порядок вызовов — в документации Tiny Agents и в блог-посте о Python-версии; для первого знакомства хватит команды tiny-agents run agent.json.)

Что учесть при развёртывании

Когда вы развернёте MCP-сервер на Gradio в Hugging Face Spaces, поменяйте URL сервера в конфигурации агента на адрес вашего Space:

{
    command: "npx",
    args: [
        "mcp-remote",
        "https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse"
    ]
}

(В настоящем JSON ключи пишутся в кавычках: "command", "args". В оригинале фрагмент взят из кода на TypeScript.)

Так агент сможет пользоваться инструментом анализа тональности откуда угодно, а не только локально!

Итог: наше MCP-приложение от начала до конца

В этом юните мы прошли путь от основ MCP до полноценного приложения:

1. создали MCP-сервер на Gradio с инструментом анализа тональности;
2. научились подключаться к нему MCP-клиентами;
3. построили tiny agent на TypeScript и Python, который работает с нашим инструментом.

Это показывает силу Model Context Protocol: мы создаём специализированные инструменты в знакомых фреймворках (например, Gradio), открываем их через стандартный интерфейс (MCP), и агенты без усилий пользуются ими наряду с другими возможностями.

Построенная схема позволяет агенту:

• подключаться к нескольким поставщикам инструментов;
• динамически узнавать доступные инструменты;
• пользоваться нашим собственным инструментом анализа тональности;
• сочетать его с другими возможностями — доступом к файловой системе, работой в браузере.

Именно такой модульный подход делает MCP таким мощным для построения гибких приложений ИИ.

Что дальше

• Прочитайте блог-посты о Tiny Agents на Python и TypeScript.
• Посмотрите документацию Tiny Agents.
• Постройте что-нибудь на Tiny Agents!

2.7. Локальные Tiny Agents на NPU и встроенной графике AMD (пересказ)

Этот раздел написан совместно с AMD и рассчитан на компьютеры с процессорами AMD Ryzen AI и видеокартами Radeon, поэтому мы передаём его кратко.

• Lemonade Server — программа для локального запуска моделей на нейропроцессоре (NPU) и встроенной графике AMD. Под Windows ставится установщиком, под Linux — пакетом lemonade-sdk (курс фиксирует версию 8.0.3) и запускается командой lemonade-server-dev serve. Ускорение на GPU идёт через движок llama.cpp с Vulkan, ускорение на NPU — только для Ryzen AI 300 под Windows.
• Lemonade Server даёт OpenAI-совместимый эндпоинт http://localhost:8000/api/, поэтому агент из раздела 2.6 переключается на него одной строкой: "endpointUrl": "http://localhost:8000/api/" и "model": "Qwen3-8B-GGUF"; сервер тональности на Gradio подключается так же, через mcp-remote.
• Вторая часть раздела — ассистент для конфиденциальных данных, который целиком работает на вашем компьютере: агент на маленькой модели Jan-nano (4B, файл GGUF в квантовании Q4_0) получает MCP-сервер Desktop Commander (доступ к файлам, терминалу и редактированию кода) и помогает оценивать резюме кандидатов на вакансию. Вы создаёте описание вакансии job_description.md и папку candidates с резюме, а агент читает их и пишет выводы — данные никуда не уходят с машины.

На вашей машине с NVIDIA то же самое делается без Lemonade: поднимите модель в vLLM или llama.cpp и укажите её адрес в endpointUrl. Помните, что сервер вроде Desktop Commander даёт модели доступ к терминалу и файлам — запускайте такие эксперименты в отдельной папке или контейнере и не давайте агенту права на запись туда, где лежит важное (урок 8.3.4 — о том, почему это опасно).

Словарик

English	Русский
end-to-end application	приложение от начала до конца, сквозной проект
sentiment analysis, polarity, subjectivity	анализ тональности, полярность, субъективность
deploy, Space	развернуть, Space (приложение на Hugging Face)
endpoint	эндпоинт (адрес, по которому отвечает сервер)
bridge (mcp-remote)	посредник, мост
coding assistant	ИИ-ассистент программиста
local model, inference server	локальная модель, сервер инференса
tool policy: Automatic	политика инструмента: вызывать без подтверждения
code agent, authorized imports	агент кода, разрешённые импорты
NPU (neural processing unit)	нейропроцессор