MCP Course, юнит 1 (часть 2): SDK, клиенты, сервер Hugging Face и Gradio

Это перевод второй половины юнита 1 курса MCP Course. Начало юнита — понятия, архитектура и протокол, продолжение курса — юнит 2: приложение на MCP от начала до конца. Путеводитель по курсу — здесь.

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

Здесь начинается практика: первый MCP-сервер на официальном SDK, отладчик, настройка клиентов. В уроке 8.3.2 тот же сервер сначала написан руками, без SDK, а потом на SDK 2.x — сравните. Курс использует Python SDK 1.x (класс FastMCP); в SDK 2.x главный класс называется MCPServer. Где это важно, мы добавили примечания. Раздел о Gradio пригодится и для урока 8.4.3: Gradio — самый быстрый способ дать модели веб-интерфейс.

1.6. MCP SDK

У Model Context Protocol есть официальные SDK для JavaScript, Python и других языков. С ними легко реализовать MCP-клиенты и серверы в своих приложениях. SDK берут на себя низкоуровневые детали протокола, и вы можете сосредоточиться на возможностях своего приложения.

Обзор SDK

Оба SDK дают похожую базовую функциональность и следуют спецификации протокола MCP, которую мы обсуждали раньше. Они берут на себя:

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

Как реализовать базовые примитивы

Посмотрим, как реализовать каждый из базовых примитивов (инструменты, ресурсы и промпты) в обоих SDK.

Python

В оригинале здесь встроено видео (YouTube, id exzrb5QNUis).

from mcp.server.fastmcp import FastMCP

# Создаём MCP-сервер
mcp = FastMCP("Weather Service")

# Реализация инструмента
@mcp.tool()
def get_weather(location: str) -> str:
    """Get the current weather for a specified location."""
    return f"Weather in {location}: Sunny, 72°F"

# Реализация ресурса
@mcp.resource("weather://{location}")
def weather_resource(location: str) -> str:
    """Provide weather data as a resource."""
    return f"Weather data for {location}: Sunny, 72°F"

# Реализация промпта
@mcp.prompt()
def weather_report(location: str) -> str:
    """Create a weather report prompt."""
    return f"""You are a weather reporter. Weather report for {location}?"""


# Запускаем сервер
if __name__ == "__main__":
    mcp.run()

Реализовав сервер, вы можете запустить его скриптом сервера.

mcp dev server.py

JavaScript

index.mjs

import {
  McpServer,
  ResourceTemplate,
} from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Создаём MCP-сервер
const server = new McpServer({
  name: "Weather Service",
  version: "1.0.0",
});

// Реализация инструмента
server.tool("get_weather", { location: z.string() }, async ({ location }) => ({
  content: [
    {
      type: "text",
      text: `Weather in ${location}: Sunny, 72°F`,
    },
  ],
}));

// Реализация ресурса
server.resource(
  "weather",
  new ResourceTemplate("weather://{location}", { list: undefined }),
  async (uri, { location }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Weather data for ${location}: Sunny, 72°F`,
      },
    ],
  })
);

// Реализация промпта
server.prompt(
  "weather_report",
  { location: z.string() },
  async ({ location }) => ({
    messages: [
      {
        role: "assistant",
        content: {
          type: "text",
          text: "You are a weather reporter.",
        },
      },
      {
        role: "user",
        content: {
          type: "text",
          text: `Weather report for ${location}?`,
        },
      },
    ],
  })
);

// Запускаем сервер
const transport = new StdioServerTransport();
await server.connect(transport);

Реализовав сервер, вы можете запустить его скриптом сервера.

npx @modelcontextprotocol/inspector node ./index.mjs

Эта команда запустит сервер для разработки с файлом server.py и выведет в лог:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
Spawned stdio transport
Connected MCP client to backing server transport
Created web app transport
Set up MCP proxy
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Теперь можно открыть MCP Inspector по адресу http://127.0.0.1:6274, посмотреть возможности сервера и поработать с ними.

Вы увидите возможности сервера и сможете вызывать их через интерфейс.

(В оригинале — скриншот MCP Inspector: слева настройки подключения, сверху вкладки Resources, Prompts, Tools, в центре список инструментов и форма вызова. Ссылка на рисунок.)

Примечание переводчика: как это запустить сегодня

• Команда mcp появляется после pip install "mcp[cli]". mcp dev запускает отладчик MCP Inspector, а он написан на JavaScript, поэтому нужен ещё Node.js (с ним ставятся npm и npx).
• Код выше — для Python SDK 1.x. В SDK 2.x импорт другой: from mcp.server import MCPServer и mcp = MCPServer("Weather Service"), остальное почти не меняется. Если видите ModuleNotFoundError: No module named 'mcp.server.fastmcp', у вас SDK 2.x: поменяйте импорт или поставьте pip install "mcp<2". Подробно — в уроке 8.3.2.
• Докстринги функций оставлены на английском: SDK берёт их как описания инструмента, ресурса и промпта для модели. Пишите их понятно — модель выбирает инструмент именно по описанию.
• В новых версиях JavaScript SDK появились методы registerTool, registerResource и registerPrompt — их и рекомендует документация SDK вместо server.tool, server.resource и server.prompt из примера.

Какие есть MCP SDK

MCP не зависит от языка программирования, и для нескольких популярных языков есть официальные SDK:

Язык	Репозиторий	Кто поддерживает	Статус
TypeScript	github.com/modelcontextprotocol/typescript-sdk	Anthropic	активен
Python	github.com/modelcontextprotocol/python-sdk	Anthropic	активен
Java	github.com/modelcontextprotocol/java-sdk	Spring AI (VMware)	активен
Kotlin	github.com/modelcontextprotocol/kotlin-sdk	JetBrains	активен
C#	github.com/modelcontextprotocol/csharp-sdk	Microsoft	активен (предварительная версия)
Swift	github.com/modelcontextprotocol/swift-sdk	loopwork-ai	активен
Rust	github.com/modelcontextprotocol/rust-sdk	Anthropic и сообщество	активен
Dart	github.com/leehack/mcp_dart	сообщество Flutter	активен

(Примечание переводчика: таблица — на момент написания курса. Список официальных SDK с тех пор пополнился, актуальный — в организации modelcontextprotocol на GitHub.)

Эти SDK дают удобные для каждого языка абстракции и упрощают работу с протоколом MCP: вы занимаетесь основной логикой своих серверов и клиентов, а не низкоуровневыми деталями протокола.

Что дальше

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

В следующем разделе мы посмотрим, как подключиться к серверу из LLM.

Тест 2: MCP SDK

Проверьте, как вы поняли MCP SDK и их возможности.

Тест 2: MCP SDK5 вопросов·

1 Какова главная задача MCP SDK?

Определять спецификацию протокола MCPУпрощать реализацию MCP-клиентов и серверовДавать визуальный интерфейс для взаимодействий через MCPЗаменить необходимость в языках программирования

2 Что из перечисленного обычно берут на себя MCP SDK?

Оптимизацию MCP-серверовСоздание новых алгоритмов ИИСериализацию и десериализацию сообщенийХостинг больших языковых моделей

3 Какая компания, согласно тексту курса, поддерживает официальный Python SDK для MCP?

GoogleAnthropicMicrosoftJetBrains

4 Какой командой запускают MCP-сервер для разработки из файла server.py?

python server.py runmcp start server.pymcp dev server.pyserve mcp server.py

5 Какую роль в MCP играет JSON-RPC 2.0?

Основной транспорт для удалённого обменаФормат всех сообщений между клиентами и серверамиИнструмент для отладки моделей ИИСпособ описывать возможности вроде инструментов и ресурсов

Проверить ответы

Поздравляем с прохождением теста 🥳! Если нужно что-то повторить, вернитесь к разделам выше.

1.7. MCP-клиенты

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

В этой части юнита 1 вы:

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

Совет

На этой странице мы покажем, как настраивать MCP-клиенты разными способами в нотации JSON. Пока мы будем использовать примеры вроде path/to/server.py вместо пути к MCP-серверу. В следующем юните мы подставим настоящие MCP-серверы.

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

Что такое MCP-клиенты

MCP-клиенты — важнейшие компоненты, которые служат мостом между приложениями ИИ (хостами) и внешними возможностями, которые предоставляют MCP-серверы. Представьте хост как основное приложение (например, ИИ-ассистент или IDE), а клиент — как специальный модуль внутри хоста, который отвечает за обмен данными по MCP.

Клиенты с пользовательским интерфейсом

Начнём с клиентов с пользовательским интерфейсом, которые уже поддерживают MCP.

Чат-клиенты

• Claude Desktop (Anthropic)

Клиенты для разработки

• расширения VS Code с поддержкой MCP (например, Continue);
• Cursor IDE (встроенный MCP-клиент);
• редактор Zed.

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

Быстрое подключение к MCP-серверу Hugging Face

Hugging Face предоставляет размещённый у себя MCP-сервер со встроенными инструментами для поиска моделей, датасетов, Spaces и статей.

1. Войдите в аккаунт и откройте https://huggingface.co/settings/mcp.
2. Выберите свой MCP-совместимый клиент (например, VS Code, Cursor, Zed, Claude Desktop).
3. Скопируйте сгенерированный фрагмент конфигурации в настройки MCP своего клиента.
4. Перезапустите или перезагрузите клиент. Вы должны увидеть, что «Hugging Face» подключён.

Совет: используйте сгенерированный фрагмент, а не пишите конфигурацию руками — он подогнан под конкретный клиент.

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

Разобравшись с ядром протокола MCP, посмотрим, как настраивать MCP-серверы и клиенты.

Чтобы MCP-серверы и клиенты хорошо работали, их нужно правильно настроить.

Совет

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

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

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

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

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

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

Такую структуру mcp.json можно передать приложениям вроде Claude Desktop, Cursor или VS Code.

{
  "servers": [
    {
      "name": "Server Name",
      "transport": {
        "type": "stdio|sse",
        // Настройки, специфичные для транспорта
      }
    }
  ]
}

В этом примере один сервер с именем и типом транспорта. Тип транспорта — stdio или sse.

Примечание переводчика: настоящие клиенты ждут другой формат

Структура выше — условная схема курса; в таком виде её не примет ни один распространённый клиент. Реальные форматы различаются, но устроены похоже: серверы перечислены объектом, где ключ — имя сервера.

• Claude Desktop (файл claude_desktop_config.json) и Cursor (.cursor/mcp.json) — ключ mcpServers:

  {
    "mcpServers": {
      "file-explorer": {
        "command": "python",
        "args": ["/path/to/file_explorer_server.py"],
        "env": { "GITHUB_TOKEN": "..." }
      }
    }
  }

• VS Code (.vscode/mcp.json) — ключ servers, у каждого сервера поле type ("stdio" или "http"), для удалённых серверов — url.

Кроме того, комментарии // в настоящем JSON запрещены: в курсе они стоят только для пояснения. Поэтому совет курса из раздела выше — брать готовый фрагмент со страницы настроек — самый надёжный.

Настройка для транспорта stdio

Для локальных серверов с транспортом stdio в конфигурации указывают команду и аргументы для запуска процесса сервера:

{
  "servers": [
    {
      "name": "File Explorer",
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/file_explorer_server.py"] // Это пример, настоящий сервер будет в следующем юните
      }
    }
  ]
}

Здесь сервер с именем «File Explorer» («Проводник») — это локальный скрипт.

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

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

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

Переменные окружения в конфигурации

Переменные окружения можно передать процессу сервера через поле env. Вот как прочитать их в коде сервера:

Python

В Python переменные окружения читают через модуль os:

import os

# Читаем переменные окружения
github_token = os.environ.get("GITHUB_TOKEN")
if not github_token:
    raise ValueError("GITHUB_TOKEN environment variable is required")

# Используем токен в коде сервера
def make_github_request():
    headers = {"Authorization": f"Bearer {github_token}"}
    # ... остальной код

JavaScript

В JavaScript переменные окружения читают через объект process.env:

// Читаем переменные окружения
const githubToken = process.env.GITHUB_TOKEN;
if (!githubToken) {
    throw new Error("GITHUB_TOKEN environment variable is required");
}

// Используем токен в коде сервера
function makeGithubRequest() {
    const headers = { "Authorization": `Bearer ${githubToken}` };
    // ... остальной код
}

(Сообщение об ошибке: «нужна переменная окружения GITHUB_TOKEN».)

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

{
  "servers": [
    {
      "name": "GitHub API",
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/github_server.py"], // Это пример, настоящий сервер будет в следующем юните
        "env": {
          "GITHUB_TOKEN": "your_github_token"
        }
      }
    }
  ]
}

(Примечание переводчика: не публикуйте конфигурацию с настоящим токеном — например, не коммитьте её в git. your_github_token — заглушка.)

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

Посмотрим на несколько реальных сценариев настройки.

Сценарий 1: локальный сервер

В этом сценарии у нас локальный сервер — скрипт на Python, например проводник по файлам или редактор кода.

{
  "servers": [
    {
      "name": "File Explorer",
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/file_explorer_server.py"] // Это пример, настоящий сервер будет в следующем юните
      }
    }
  ]
}

Сценарий 2: удалённый сервер

В этом сценарии у нас удалённый сервер — API погоды.

{
  "servers": [
    {
      "name": "Weather API",
      "transport": {
        "type": "sse",
        "url": "https://example.com/mcp-server" // Это пример, настоящий сервер будет в следующем юните
      }
    }
  ]
}

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

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

Клиенты tiny agents

Теперь посмотрим, как использовать MCP-клиенты из кода.

В роли MCP-клиентов можно использовать и tiny agents («крошечные агенты»), чтобы подключаться к MCP-серверам прямо из своего кода. Tiny agents — простой способ создать агента ИИ, который пользуется инструментами MCP-серверов.

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

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

Установка

Сначала установим npx, если его ещё нет. Это можно сделать такой командой:

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

(Примечание переводчика: обычно этот шаг не нужен — npx входит в состав npm, начиная с версии 5.2, и устанавливается вместе с Node.js. Проверьте командой npx --version.)

Затем установим пакет huggingface_hub с поддержкой MCP. Это позволит запускать MCP-серверы и клиенты.

pip install "huggingface_hub[mcp]>=0.32.0"

Затем нужно войти в Hugging Face Hub, чтобы получить доступ к MCP-серверам. Это делается через командную строку Hugging Face. Понадобится токен для входа.

# Входим через новую командную строку
hf auth login

Примечание. Команда huggingface-cli устарела, её заменила hf. Если видите ошибку «command not found», убедитесь, что у вас свежая версия huggingface_hub.

Настройка прав токена доступа

Создав токен доступа Hugging Face и войдя в аккаунт, нужно убедиться, что у токена есть права на работу с провайдерами инференса (inference providers).

Осторожно

Важно: если пропустить этот шаг, при запуске tiny agents с размещёнными в облаке моделями возможны ошибки аутентификации.

1. Откройте страницу токенов доступа Hugging Face.
2. Найдите свой токен для MCP и нажмите три точки (⋮) рядом с ним.
3. Выберите «Edit permissions» («Изменить права»).
4. В разделе Inference отметьте пункт «Make calls to Inference Providers» («Делать вызовы к провайдерам инференса»).
5. Сохраните изменения.

Это право нужно, потому что tiny agents вызывают через API размещённые модели вроде Qwen/Qwen2.5-72B-Instruct через провайдеров вроде Novita.

Python

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

Теперь создадим файл конфигурации агента agent.json.

{
    "name": "playwright-agent",
    "description": "Agent with Playwright MCP server",
    "model": "Qwen/Qwen2.5-72B-Instruct",
    "provider": "novita",
    "servers": [
        {
            "type": "stdio",
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    ]
}

В этой конфигурации используется MCP-сервер @playwright/mcp. Это MCP-сервер, который управляет браузером через Playwright.

Теперь можно запустить агента:

tiny-agents run agent.json

JavaScript

Сначала установите пакет tiny agents через npm.

npm install @huggingface/tiny-agents

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

Создайте папку проекта агента и файл agent.json.

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

Создайте файл конфигурации агента my-agent/agent.json:

{
    "model": "Qwen/Qwen2.5-72B-Instruct",
    "provider": "novita",
    "servers": [
        {
            "type": "stdio",
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    ]
}

Теперь можно запустить агента:

npx @huggingface/tiny-agents run ./my-agent

В видео ниже мы запускаем агента и просим его открыть новую вкладку в браузере.

Пример ниже — агент для веб-браузинга: он использует модель Qwen/Qwen2.5-72B-Instruct через провайдера инференса Novita и подключён к MCP-серверу Playwright, который позволяет ему пользоваться веб-браузером! Конфигурация агента загружается по пути в датасете tiny-agents/tiny-agents на Hugging Face.

(В оригинале — видео: агент запускается, печатает список найденных инструментов Playwright и по запросу управляет браузером. Ссылка на видео.)

Когда вы запускаете агента, он загружается и выводит список инструментов, найденных у подключённых MCP-серверов. После этого он готов к вашим запросам!

Промпт из этой демонстрации:

do a Web Search for HF inference providers on Brave Search and open the first result and then give me the list of the inference providers supported on Hugging Face

(Перевод: «поищи в Brave Search провайдеров инференса HF, открой первый результат и дай мне список провайдеров инференса, которых поддерживает Hugging Face».)

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

Вместо облачного провайдера tiny agents можно направить на локальную модель: в agent.json вместо model и provider укажите "endpointUrl" вашего OpenAI-совместимого сервера (например, vLLM из урока 7.1.2) и имя модели. Модель должна хорошо поддерживать вызов инструментов — подойдут instruct-модели семейства Qwen.

Что дальше

Теперь, когда вы понимаете MCP-клиенты, вы готовы:

• изучить конкретные реализации MCP-серверов;
• научиться создавать свои MCP-клиенты;
• погрузиться в продвинутые схемы интеграции через MCP.

Продолжим путешествие в мир Model Context Protocol!

1.8. MCP-сервер Hugging Face

MCP-сервер Hugging Face подключает ваш MCP-совместимый ИИ-ассистент (например, VS Code, Cursor, Zed или Claude Desktop) прямо к Hugging Face Hub. После подключения ассистент может искать и изучать ресурсы Hub и пользоваться инструментами сообщества — прямо из редактора, чата или командной строки.

Совет

Главное преимущество MCP-сервера Hugging Face — встроенные инструменты для Hub и инструменты сообщества на основе Gradio Spaces. Когда мы начнём строить свои MCP-серверы, увидим, что сервер Hugging Face можно брать за образец.

Что можно делать

• Искать и изучать ресурсы Hub: модели, датасеты, Spaces и статьи.
• Запускать инструменты сообщества через MCP-совместимые приложения Gradio, размещённые в Spaces.
• Возвращать результаты в ассистента вместе с метаданными, ссылками и контекстом.

Встроенные инструменты

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

• поиск и изучение моделей (фильтры по задаче, библиотеке, числу скачиваний, лайкам);
• поиск и изучение датасетов (фильтры по тегам, размеру, модальности);
• семантический поиск по Spaces (поиск приложений по возможностям, например TTS, ASR, OCR);
• семантический поиск по статьям (поиск релевантных исследований на Hub).

(TTS — синтез речи, ASR — распознавание речи, OCR — распознавание текста на изображениях.)

Начало работы

1. Откройте настройки MCP: войдите в аккаунт и зайдите на https://huggingface.co/settings/mcp.

2. Выберите клиент: укажите свой MCP-совместимый клиент (например, VS Code, Cursor, Zed, Claude Desktop). На странице появятся инструкции для этого клиента и готовый к копированию фрагмент конфигурации.

3. Вставьте и перезапустите: скопируйте фрагмент в конфигурацию MCP своего клиента, сохраните и перезапустите или перезагрузите клиент. Вы должны увидеть «Hugging Face» (или похожее название) в списке подключённых MCP-серверов.

Совет

Страница настроек генерирует ровно ту конфигурацию, которую ждёт ваш клиент. Пользуйтесь ей, а не пишите конфигурацию руками.

(В оригинале — скриншот страницы настроек MCP на Hugging Face. Ссылка на рисунок.)

Как пользоваться сервером

После подключения просите ассистента воспользоваться инструментами Hugging Face. Примеры запросов:

• «Найди на Hugging Face квантованные версии Qwen 3».
• «Найди Space, который умеет расшифровывать аудиофайлы».
• «Покажи датасеты с временными рядами погоды».
• «Создай изображение кота в стиле Ghibli размером 1024 × 1024».

Ассистент вызовет MCP-инструменты, которые предоставляет MCP-сервер Hugging Face (включая Spaces), и вернёт результаты (названия, авторов, число скачиваний, ссылки и так далее). Дальше можно открыть ресурс на Hub или продолжить работу в том же чате.

(В оригинале — скриншот VS Code, где ассистент вызывает инструменты сервера Hugging Face и Spaces. Ссылка на рисунок.)

Добавьте инструменты сообщества (Spaces)

Свою конфигурацию можно расширить MCP-совместимыми Gradio Spaces, созданными сообществом:

• Найдите Spaces с поддержкой MCP здесь.
• Добавьте нужный Space в настройках MCP на Hugging Face здесь.

MCP-приложения Gradio предоставляют свои функции как инструменты (с аргументами и описаниями), и ассистент может вызывать их напрямую. Перезапустите или обновите клиент, чтобы он подхватил новые инструменты.

Подробнее

• Настройки и подключение клиентов: https://huggingface.co/settings/mcp
• Анонс в журнале изменений: https://huggingface.co/changelog/hf-mcp-server
• Документация MCP-сервера HF: https://huggingface.co/docs/hub/en/hf-mcp-server
• Как построить свой MCP-сервер на Gradio и инструментах Hub: https://huggingface.co/docs/hub/main/agents

1.9. Интеграция Gradio с MCP

Мы разобрали основные понятия протокола MCP и то, как реализовать MCP-серверы и клиенты. В этом разделе мы немного упростим себе жизнь и создадим MCP-сервер с помощью Gradio!

Совет

Gradio — популярная библиотека Python для быстрого создания настраиваемых веб-интерфейсов к моделям машинного обучения.

Знакомство с Gradio

Gradio позволяет сделать интерфейс к модели несколькими строками кода на Python. Особенно удобно это для:

• демонстраций и прототипов;
• показа моделей людям без технической подготовки;
• проверки и отладки поведения модели.

С появлением поддержки MCP Gradio даёт простой способ открыть возможности модели ИИ через стандартный протокол MCP.

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

Что нужно

Чтобы пользоваться Gradio с поддержкой MCP, установите Gradio с дополнением MCP:

uv pip install "gradio[mcp]"

Ещё понадобится приложение с LLM, которое поддерживает вызов инструментов по протоколу MCP, например Cursor (такие приложения называют «MCP-хостами»).

(Примечание переводчика: uv pip — команда быстрого менеджера пакетов uv; с обычным pip пишите pip install "gradio[mcp]".)

Создаём MCP-сервер на Gradio

Разберём простой пример MCP-сервера на Gradio:

import gradio as gr

def letter_counter(word: str, letter: str) -> int:
    """
    Count the number of occurrences of a letter in a word or text.

    Args:
        word (str): The input text to search through
        letter (str): The letter to search for

    Returns:
        int: The number of times the letter appears in the text
    """
    word = word.lower()      # приводим текст к нижнему регистру
    letter = letter.lower()  # и букву тоже, чтобы «А» и «а» считались одинаково
    count = word.count(letter)
    return count

# Создаём обычный интерфейс Gradio
demo = gr.Interface(
    fn=letter_counter,
    inputs=["textbox", "textbox"],
    outputs="number",
    title="Letter Counter",
    description="Enter text and a letter to count how many times the letter appears in the text."
)

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

(Докстринг оставлен на английском — из него Gradio делает описание инструмента для модели. Перевод: «Посчитать, сколько раз буква встречается в слове или тексте. Аргументы: word — текст, в котором ищем; letter — искомая буква. Возвращает: сколько раз буква встречается в тексте». Описание интерфейса: «Введите текст и букву, чтобы узнать, сколько раз буква встречается в тексте».)

После этого функция подсчёта букв доступна:

1. через обычный веб-интерфейс Gradio — для людей;
2. через MCP-сервер, к которому могут подключиться совместимые клиенты.

MCP-сервер будет доступен по адресу:

http://your-server:port/gradio_api/mcp/sse

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

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

Что происходит внутри

Когда вы ставите mcp_server=True в launch(), происходит следующее:

1. Функции Gradio автоматически превращаются в инструменты MCP.
2. Компоненты ввода отображаются в схему аргументов инструмента.
3. Компоненты вывода определяют формат ответа.
4. Сервер Gradio начинает слушать и сообщения протокола MCP.
5. Для обмена между клиентом и сервером настраивается JSON-RPC поверх HTTP+SSE.

Главные особенности интеграции Gradio и MCP

1. Превращение в инструменты. Каждый эндпоинт API вашего приложения Gradio автоматически превращается в инструмент MCP с соответствующим именем, описанием и схемой входа. Чтобы посмотреть инструменты и схемы, откройте http://your-server:port/gradio_api/mcp/schema или нажмите ссылку «View API» внизу приложения Gradio, а затем «MCP».

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

   • параметром mcp_server в launch():

     demo.launch(mcp_server=True)

   • переменной окружения:

     export GRADIO_MCP_SERVER=True

3. Работа с файлами. Сервер сам преобразует файловые данные:

   • превращает строки в base64 в файлы;
   • обрабатывает изображения и возвращает их в правильном формате;
   • управляет временным хранилищем файлов.

   Настоятельно рекомендуется передавать изображения и файлы на вход полными URL («http://…» или «https://…»): MCP-клиенты не всегда правильно работают с локальными файлами.

4. MCP-серверы на 🤗 Spaces. Приложение Gradio можно бесплатно опубликовать в Hugging Face Spaces — и получить бесплатный размещённый MCP-сервер. Пример такого Space: https://huggingface.co/spaces/abidlabs/mcp-tools

Подключайте MCP-совместимые Spaces к своему клиенту

Любой MCP-совместимый Space можно подключить к ассистенту через настройки MCP на Hugging Face:

1. Найдите MCP-совместимые Spaces: https://huggingface.co/spaces?search=mcp
2. Откройте https://huggingface.co/settings/mcp (войдя в аккаунт) и добавьте Space.
3. Перезапустите или обновите MCP-клиент, чтобы он обнаружил новые инструменты.

Эти Spaces предоставляют свои функции как инструменты с аргументами и описаниями, и ассистент может вызывать их напрямую.

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

1. Аннотации типов и докстринги. Обязательно указывайте аннотации типов и правильные докстринги у функций. В докстринге должен быть блок «Args:» с именами параметров с отступом.

2. Строковые входы. Если сомневаетесь, принимайте аргументы как str и преобразуйте в нужный тип внутри функции.

3. Поддержка SSE. Некоторые MCP-хосты не поддерживают MCP-серверы на SSE. Тогда можно использовать mcp-remote:

   {
     "mcpServers": {
       "gradio": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://your-server:port/gradio_api/mcp/sse"
         ]
       }
     }
   }

4. Перезапуск. Если возникают проблемы с подключением, перезапустите и MCP-клиент, и MCP-сервер.

(Примечание переводчика: mcp-remote — небольшая программа-посредник: хост запускает её как обычный локальный stdio-сервер, а она пересылает сообщения удалённому серверу по HTTP. Точный адрес MCP-сервера Gradio печатает в консоли при запуске приложения — сверяйтесь с ним: в новых версиях Gradio есть и адрес для Streamable HTTP.)

Поделитесь своим MCP-сервером

Своим MCP-сервером можно поделиться, опубликовав приложение Gradio в Hugging Face Spaces. В видео ниже показано, как создать Space.

(В оригинале — видео на YouTube, id 3bSVKNKb_PY.)

Теперь вы можете делиться MCP-сервером с другими, просто давая ссылку на свой Space.

Заключение

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

Дальше в курсе мы разберём более сложные реализации MCP, но Gradio — отличная отправная точка, чтобы понять протокол и поэкспериментировать с ним.

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

1.10. Итоги юнита 1

Model Context Protocol (MCP)

MCP — стандартный протокол для подключения моделей ИИ к внешним инструментам, источникам данных и средам. Он снимает ограничения нынешних систем ИИ, обеспечивая совместимость и доступ к информации в реальном времени.

Ключевые понятия

Клиент-серверная архитектура

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

Компоненты

Хост — приложение ИИ, с которым работает пользователь, его интерфейс для конечных пользователей.

Клиент — компонент внутри хост-приложения, который ведёт обмен данными с конкретным MCP-сервером. Клиенты держат соединения один-к-одному с серверами и берут на себя детали протокола.

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

Возможности

Инструменты — исполняемые функции, которые выполняют действия (например, отправляют сообщения, делают запросы к API). Инструментами обычно управляет модель, и из-за возможных побочных эффектов на их вызов нужно согласие пользователя.

Ресурсы — источники данных только для чтения, которые дают контекст без сложных вычислений. Ресурсами управляет приложение; они похожи на GET-эндпоинты в REST API.

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

Сэмплирование — запросы на обработку в LLM, которые инициирует сервер. Оно позволяет серверу вести агентное поведение и, возможно, рекурсивные или многошаговые взаимодействия. Обычно на него нужно согласие пользователя.

Протокол обмена данными

Протокол MCP использует JSON-RPC 2.0 как формат сообщений между клиентами и серверами. Поддерживаются два основных транспортных механизма: stdio (для локального обмена) и HTTP+SSE (для удалённого). Сообщения бывают трёх видов: запросы, ответы и уведомления.

Процесс обнаружения

MCP позволяет клиентам динамически узнавать доступные инструменты, ресурсы и промпты через методы-списки (например, tools/list). Благодаря этому клиенты подстраиваются под возможности каждого сервера без заранее «зашитого» знания о его функциях.

MCP SDK

Официальные SDK есть для многих языков программирования. Они берут на себя обмен данными на уровне протокола, регистрацию возможностей и обработку ошибок, упрощая разработку.

Интеграция с Gradio

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

Что нового в MCP у Hugging Face

• Размещённый MCP-сервер теперь работает с большим числом клиентов (VS Code, Cursor, Zed, Claude Desktop).
• Подобранные встроенные инструменты для поиска моделей, датасетов, Spaces и статей.
• Готовые фрагменты конфигурации в один клик на https://huggingface.co/settings/mcp.
• MCP-совместимые Gradio Spaces можно добавить в настройках и пользоваться ими прямо из ассистента.

1.11. Получите сертификат!

Отлично! Вы прошли первый юнит курса по MCP. Теперь пора сдать экзамен и получить сертификат.

В оригинале здесь встроен тест по юниту — Space mcp-course/unit_1_quiz на Hugging Face Hub. Если найдёте ошибки, сообщите о них во вкладке Community этого Space.

Словарик

English	Русский
SDK (software development kit)	набор средств разработки
MCP Inspector	отладчик MCP-серверов в браузере
configuration file, mcp.json	конфигурационный файл
environment variable	переменная окружения
access token, permissions	токен доступа, права
inference provider	провайдер инференса (облачный сервис, который запускает модель)
tiny agents	«крошечные агенты» Hugging Face — агент из файла конфигурации
hosted server	размещённый (облачный) сервер
Space	Space — приложение, размещённое на Hugging Face
type hints, docstring	аннотации типов, докстринг