MCP Server: архитектура, настройка и практическое применение

Как практик, занимающийся интеграцией AI-агентов в продуктовые и инфраструктурные проекты, я часто сталкивался с проблемой: каждый новый инструмент или источник данных требует собственного, уникального способа подключения. REST API, WebSocket, gRPC, файловые системы — всё это приходится оборачивать в костыли, чтобы агент мог с ними работать. MCP Server (Model Context Protocol Server) решает эту боль.

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

Введение в MCP Server: что это и зачем нужно

MCP — это открытый протокол, предложенный Anthropic для стандартизации взаимодействия AI-агентов с внешними данными и инструментами. Если упрощённо: раньше, чтобы агент мог выполнить SQL-запрос или создать задачу в Jira, вы писали отдельный код для каждого вызова. MCP вводит единый интерфейс — сервер, который регистрирует инструменты, ресурсы и промпты, а клиент (агент) просто их вызывает по протоколу JSON-RPC 2.0.

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

Ключевые понятия: MCP, сервер, клиент, инструменты, ресурсы

• MCP (Model Context Protocol) — сам протокол, определяющий, как клиент и сервер обмениваются сообщениями.
• MCP Server — серверная реализация, которая регистрирует и предоставляет инструменты, ресурсы и промпты.
• MCP Client — агент или приложение, которое подключается к серверу и вызывает его возможности.
• Инструменты (Tools) — функции, которые агент может вызвать. Например, query_database или send_email. У каждого инструмента есть имя, описание и схема параметров.
• Ресурсы (Resources) — данные, которые сервер предоставляет в виде URI. Например, file:///logs/app.log или db://users.
• Промпты (Prompts) — шаблоны запросов, которые помогают агенту формулировать корректные вызовы.

Различие между инструментами и ресурсами

Инструменты — это действия (вызвать функцию), ресурсы — это данные (получить файл, строку из БД). На практике агент сначала получает ресурс (контекст), а потом использует инструмент для действия.

Роль промптов в контексте агента

Промпты — это подсказки, которые сервер передаёт клиенту, чтобы агент правильно сформулировал запрос. Например, промпт может содержать описание того, как формировать SQL-запрос для конкретной базы данных.

Сценарии использования MCP Server

• Интеграция с базами данных (SQL, NoSQL) — агент выполняет SELECT-запросы, получает данные для анализа.
• Доступ к внешним API (погода, финансы) — агент получает курсы валют, прогноз погоды, котировки акций.
• Управление файлами и документами — агент читает, записывает, ищет файлы в определённой директории.
• Выполнение команд и скриптов — агент запускает скрипты (с жёсткой валидацией) для автоматизации рутинных задач.

Архитектура MCP Server: компоненты и принципы работы

Архитектура MCP Server строится вокруг транспортного уровня и протокола JSON-RPC. Сервер и клиент обмениваются сообщениями через один из транспортных протоколов: HTTP, SSE или WebSocket. Каждый запрос — это JSON-RPC сообщение с методом, параметрами и идентификатором.

Компонент	Описание
Транспортный уровень	HTTP, SSE, WebSocket — определяет, как передаются сообщения.
Протокол сообщений	JSON-RPC 2.0 — стандартный формат запросов и ответов.
Регистрация инструментов	Сервер сообщает клиенту список доступных инструментов, ресурсов и промптов.
Жизненный цикл запроса	Клиент отправляет запрос → сервер обрабатывает → возвращает результат.

Транспортные протоколы: HTTP, SSE, WebSocket

• HTTP — классический запрос-ответ. Подходит для коротких операций, когда агент вызывает инструмент и ждёт результат.
• SSE (Server-Sent Events) — сервер может отправлять клиенту потоковые данные. Идеально для длительных операций (генерация отчёта, загрузка файла).
• WebSocket — двунаправленная связь. Лучший выбор для интерактивных агентов, которые постоянно обмениваются данными.

Особенности HTTP-транспорта

HTTP — самый простой в настройке. Вы запускаете сервер на порту, клиент шлёт POST-запросы с JSON-RPC. Минус — нет потоковой передачи, только запрос-ответ.

Преимущества SSE для потоковых данных

SSE позволяет серверу отправлять данные по мере готовности. Например, агент запрашивает отчёт, который генерируется 10 секунд — сервер шлёт чанки через SSE.

WebSocket для реального времени

WebSocket — это постоянное соединение. Агент может отправлять запросы в любой момент, сервер — инициировать отправку данных. Подходит для чат-ботов, мониторинга.

Регистрация инструментов, ресурсов и промптов

Разработчик определяет инструменты с помощью SDK. Каждый инструмент имеет имя, описание (для LLM, чтобы агент понимал, когда его вызывать) и схему параметров (JSON Schema). Ресурсы — это URI с MIME-типом. Промпты — шаблоны с переменными.

Создание инструмента: имя, описание, параметры

from mcp.server import Server, Tool
from pydantic import BaseModel

class GetTimeParams(BaseModel):
timezone: str = "UTC"

server = Server("time-server")

@server.tool()
def get_time(params: GetTimeParams) -> str:
from datetime import datetime
return datetime.now().isoformat()


Ресурсы: URI и MIME-типы

Ресурсы регистрируются как resource://. Например, logs://system с MIME-типом text/plain. Клиент может запросить ресурс по URI.

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

Промпты — это строки с заполнителями. Например: "Выполни SQL-запрос: {query}. База данных: {db_name}." Агент подставляет переменные и отправляет запрос.

Обработка ошибок и исключения

JSON-RPC определяет стандартные коды ошибок: -32700 (parse error), -32600 (invalid request), -32601 (method not found). MCP добавляет кастомные коды: -32000 (инструмент не найден), -32001 (неверные параметры).

Стандартные коды ошибок JSON-RPC

Ошибки парсинга, валидации, метода — все они возвращаются в стандартном формате.

Кастомные коды ошибок MCP

MCP расширяет стандарт: ошибки аутентификации, ограничения доступа, таймауты.

Логирование и мониторинг ошибок

Рекомендую использовать структурированное логирование (JSON-логи) и отправлять их в централизованную систему (ELK, Grafana Loki). Это помогает быстро находить проблемы.

Настройка MCP Server: пошаговое руководство

Покажу на практике, как создать простой MCP Server на Python. Мы сделаем инструмент, который возвращает текущее время. Это минимальный, но рабочий пример.

Установка и инициализация проекта

1. Установите Python 3.10+.
2. Создайте виртуальное окружение: python -m venv venv.
3. Установите пакет: pip install mcp.
4. Создайте файл server.py.

Установка Node.js и npm

Если вы предпочитаете TypeScript: npm init -y && npm install @modelcontextprotocol/sdk.

Установка Python и pip

Убедитесь, что у вас Python 3.10+ и pip обновлён: pip install --upgrade pip.

Создание базового проекта

Структура: my-mcp-server/server.py. Всё просто.

Создание первого инструмента

Код сервера на Python:

from mcp.server import Server, Tool
from pydantic import BaseModel
from datetime import datetime

class TimeParams(BaseModel):
timezone: str = "UTC"

server = Server("time-server")

@server.tool()
def get_current_time(params: TimeParams) -> str:
# В реальном проекте используйте pytz для работы с часовыми поясами
return datetime.utcnow().isoformat() + "Z"

if __name__ == "__main__":
server.run()


Импорт SDK и создание сервера

Импортируем Server и Tool из mcp.server. Создаём экземпляр с именем.

Регистрация инструмента с параметрами

Декоратор @server.tool() регистрирует функцию как инструмент. Параметры описываются через Pydantic-модель.

Запуск сервера и тестирование

Запустите: python server.py. Сервер будет слушать на порту 8000 (по умолчанию). Протестируйте через curl:

curl -X POST http://localhost:8000/mcp
-H "Content-Type: application/json"
-d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Europe/Moscow"}}, "id": 1}'


Конфигурация и переменные окружения

Не хардкодьте порт, хост, секреты. Используйте переменные окружения.

Настройка порта и хоста

Пример .env файла:

MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=debug
API_KEY=your-secret-key


Логирование и уровень детализации

Настройте logging.basicConfig(level=os.getenv("LOG_LEVEL", "INFO")).

Аутентификация через токены

Добавьте middleware, которая проверяет заголовок Authorization: Bearer . Если токен невалиден — возвращайте ошибку -32002.

Практическое применение MCP Server: реальные кейсы

Теперь покажу три рабочих кейса. Код можно адаптировать под свои задачи.

Кейс 1: MCP Server для работы с PostgreSQL

Цель: агент выполняет SELECT-запросы к базе данных. Только чтение, только определённые таблицы.

Настройка подключения к БД

Установите psycopg2-binary. Создайте подключение с read-only параметрами.

Создание инструмента query_database

import psycopg2
from pydantic import BaseModel

class QueryParams(BaseModel):
sql: str

@server.tool()
def query_database(params: QueryParams) -> list:
# Валидация: разрешены только SELECT
if not params.sql.strip().upper().startswith("SELECT"):
raise ValueError("Only SELECT queries are allowed")
conn = psycopg2.connect(os.getenv("DATABASE_URL"))
with conn.cursor() as cur:
cur.execute(params.sql)
return cur.fetchall()


Тестирование: агент получает список пользователей

Агент вызывает инструмент с SQL-запросом SELECT * FROM users LIMIT 10 и получает данные.

Кейс 2: MCP Server для управления GitHub Issues

Цель: агент создаёт, читает и комментирует issues в репозитории GitHub.

Регистрация инструментов для GitHub

Используем PyGithub или прямые HTTP-запросы к GitHub API.

Обработка ответов API

Инструмент create_issue принимает title и body, возвращает URL созданного issue.

Пример: агент создаёт issue по описанию

@server.tool()
def create_issue(params: IssueParams) -> dict:
headers = {"Authorization": f"Bearer {os.getenv('GITHUB_TOKEN')}"}
data = {"title": params.title, "body": params.body}
response = requests.post("https://api.github.com/repos/owner/repo/issues", json=data, headers=headers)
return response.json()


Кейс 3: MCP Server для файлового менеджера

Цель: агент читает файлы, записывает (с ограничениями), ищет по маске.

Ограничение доступа к файловой системе

Задайте корневую директорию ALLOWED_DIR = "/var/data". Все пути должны быть внутри неё.

Инструмент read_file с проверкой пути

import os

@server.tool()
def read_file(params: FileParams) -> str:
full_path = os.path.abspath(os.path.join(ALLOWED_DIR, params.path))
if not full_path.startswith(ALLOWED_DIR):
raise PermissionError("Access denied")
with open(full_path, "r") as f:
return f.read()


Инструмент search_files для поиска

Ищет файлы по маске (например, *.log) в разрешённой директории.

Безопасность и лучшие практики MCP Server

Безопасность — это не опция, а обязательное условие для production. MCP Server даёт агенту доступ к данным и действиям, поэтому каждая дыра может привести к утечке или повреждению.

Аспект	Рекомендация
Аутентификация	API-ключи, JWT, OAuth — в зависимости от среды.
Авторизация	Роли: admin, user, readonly. Ограничение инструментов по роли.
Валидация данных	Используйте Pydantic (Python) или Zod (TypeScript).
Защита от инъекций	Параметризованные запросы, белые списки команд.
Rate limiting	Ограничьте количество вызовов в минуту от одного клиента.
Логирование и аудит	Логируйте все вызовы инструментов с IP, временем, параметрами.

Аутентификация и авторизация

Аутентификация через API-ключи

Клиент передаёт ключ в заголовке Authorization. Сервер проверяет его по базе или переменной окружения.

Авторизация на основе ролей

Например, роль readonly может вызывать только инструменты, которые не изменяют данные. Роль admin — все.

Middleware для проверки токенов

На Python это можно сделать через декоратор или ASGI middleware. Пример на FastAPI:

from fastapi import FastAPI, Depends, HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

app = FastAPI()
security = HTTPBearer()

@app.post("/mcp")
async def mcp_endpoint(credentials: HTTPAuthorizationCredentials = Security(security)):
if credentials.credentials != os.getenv("API_KEY"):
raise HTTPException(status_code=401, detail="Invalid API key")
# обработка запроса


Защита от атак и валидация данных

Валидация параметров с помощью Pydantic/Zod

Pydantic автоматически проверяет типы, длину, форматы. Это базовая защита от некорректных данных.

Параметризованные запросы к БД

Никогда не вставляйте SQL-строку напрямую. Используйте cur.execute("SELECT * FROM users WHERE id = %s", (user_id,)).

Белые списки для команд

Если нужно выполнить shell-команду, разрешите только конкретные: ["df", "du", "uptime"] с фиксированными аргументами.

Развертывание в production: Docker и обратный прокси

Dockerfile для MCP Server

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "server.py"]


docker-compose с Nginx и HTTPS

version: '3'
services:
mcp:
build: .
ports:
- "8000:8000"
environment:
- API_KEY=${API_KEY}
nginx:
image: nginx:alpine
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
ports:
- "443:443"


Мониторинг и логирование в production

Используйте Prometheus для сбора метрик (количество вызовов, ошибки, latency) и Grafana для визуализации. Логи отправляйте в Loki или ELK.

Сравнение MCP Server с альтернативами

MCP — не единственный способ интеграции агентов. Сравним его с популярными подходами.

Критерий	MCP Server	LangChain Tools	REST API	gRPC
Простота интеграции	Высокая (единый протокол)	Средняя (привязка к фреймворку)	Средняя (много эндпоинтов)	Низкая (сложный конфиг)
Производительность	Средняя (JSON-RPC)	Средняя	Средняя	Высокая (бинарный протокол)
Безопасность	Высокая (встроенная аутентификация)	Средняя (зависит от реализации)	Высокая (стандартные практики)	Высокая (TLS, mTLS)
Гибкость	Высокая (динамическое обнаружение)	Низкая (только в экосистеме LangChain)	Средняя (статичные эндпоинты)	Средняя (статичные сервисы)

MCP Server vs LangChain Tools

LangChain Tools — это часть фреймворка LangChain. Они привязаны к его экосистеме: если вы используете LangChain, то инструменты работают «из коробки». MCP — независимый протокол, который может использоваться с любым фреймворком (LangChain, AutoGPT, собственный агент).

Независимость от фреймворка

MCP не привязывает вас к LangChain. Вы можете написать клиента на любом языке.

Динамическое обнаружение инструментов

MCP позволяет клиенту запросить список инструментов во время выполнения. В LangChain инструменты обычно статичны.

Сообщество и поддержка

У MCP сообщество растёт, но пока меньше, чем у LangChain. Однако протокол активно развивается Anthropic.

MCP Server vs REST API

REST API требует создания отдельного эндпоинта для каждого действия. MCP предоставляет единый интерфейс: один эндпоинт, разные методы.

Единый интерфейс против множества эндпоинтов

С REST вы добавляете новый эндпоинт для каждой функции. С MCP — просто регистрируете новый инструмент.

Производительность JSON-RPC vs REST

JSON-RPC может быть быстрее за счёт меньшего количества заголовков и компактного тела запроса. Но разница не критична для большинства сценариев.

Безопасность: встроенная аутентификация

MCP изначально поддерживает аутентификацию на уровне протокола (токен в заголовке). В REST вы реализуете это самостоятельно.

MCP Server vs gRPC

gRPC — бинарный протокол, высокопроизводительный, но сложный в настройке. MCP — текстовый (JSON), проще в отладке.

Текстовый vs бинарный протокол

JSON легко читается и отлаживается. gRPC требует инструментов типа grpcurl.

Простота отладки

С MCP вы можете использовать curl для тестирования. С gRPC нужно генерировать клиентский код.

Экосистема и инструменты

gRPC имеет зрелую экосистему (прокси, балансировщики). MCP — молодая, но быстро развивается.

Заключение: будущее MCP Server

MCP Server решает ключевую проблему интеграции AI-агентов — фрагментацию. Вместо того чтобы писать десятки адаптеров, вы создаёте один сервер, который предоставляет агенту все нужные инструменты. Протокол уже поддерживается Anthropic, появляются SDK для Python, TypeScript, Go.

Будущее MCP — в стандартизации. Если протокол станет индустриальным стандартом, разработчики смогут создавать агентов, которые работают с любыми MCP-совместимыми серверами. Это как USB для AI-интеграций.

Ключевые выводы

• MCP Server — это стандарт для взаимодействия AI-агентов с внешними инструментами и данными.
• Простота настройки: вы можете создать рабочий сервер за 15 минут.
• Безопасность встроена в протокол: аутентификация, валидация, логирование.
• Гибкость: MCP не привязывает к фреймворку, работает с любым клиентом.

Дальнейшие шаги и ресурсы

• Официальная документация MCP
• Python SDK на GitHub
• TypeScript SDK на GitHub
• Обзор Cursor: основные функции и возможности — если вы используете Cursor как клиент для MCP.
• Как установить и настроить Cursor на Windows и macOS — для настройки окружения.

Попробуйте создать свой первый MCP Server уже сегодня. Начните с простого инструмента, потом добавляйте интеграции. Это изменит то, как вы строите AI-агентов.

Часто задаваемые вопросы

Что такое MCP Server простыми словами?

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

Чем MCP отличается от REST API?

REST API требует отдельных эндпоинтов для каждого действия. MCP использует один эндпоинт и JSON-RPC для вызова разных инструментов. MCP лучше подходит для агентов, которым нужно динамически обнаруживать возможности.

Какой язык лучше для MCP Server?

Python и TypeScript — наиболее популярные, с официальными SDK. Выбор зависит от вашего стека. Python проще для быстрого прототипирования, TypeScript — для интеграции с веб-экосистемой.

Нужна ли аутентификация для MCP Server?

Да, если сервер доступен по сети. Используйте API-ключи или JWT. Для локального сервера (на одной машине с агентом) можно обойтись без аутентификации, но лучше всегда её добавлять.

Можно ли использовать MCP Server с LangChain?

Да. LangChain поддерживает MCP через интеграцию MCPToolkit. Вы можете подключить MCP Server как набор инструментов для LangChain-агента.

Какие риски безопасности нужно учесть?

Главные риски: SQL-инъекции, command injection, неограниченный доступ к файловой системе. Всегда валидируйте параметры, используйте read-only инструменты по умолчанию, ограничивайте права.