Интеграция MCP

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

Инструмент mcp защищён feature-гейтом и требует mcp.enabled = true с определением хотя бы одного сервера. PRX поддерживает как stdio-транспорт (локальная межпроцессная коммуникация), так и HTTP-транспорт (связь с удалённым сервером). Инструменты с MCP-серверов обнаруживаются динамически во время выполнения через метод протокола tools/list и получают пространства имён для избежания конфликтов со встроенными инструментами.

PRX также поддерживает обнаружение локального mcp.json в рабочем пространстве, следуя тому же формату, который используют VS Code и Claude Desktop, что упрощает совместное использование конфигураций MCP-серверов между инструментами.

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

Определения серверов в config.toml

Определите MCP-серверы в секции [mcp.servers]:

[mcp]
enabled = true

# ── Stdio-транспорт (локальный процесс) ──────────────────────────
[mcp.servers.filesystem]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
enabled = true
startup_timeout_ms = 10000
request_timeout_ms = 30000
tool_name_prefix = "fs"

[mcp.servers.github]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxxxxxxxxxxx" }
tool_name_prefix = "gh"

[mcp.servers.sqlite]
transport = "stdio"
command = "uvx"
args = ["mcp-server-sqlite", "--db-path", "/home/user/data.db"]
tool_name_prefix = "sql"

# ── HTTP-транспорт (удалённый сервер) ───────────────────────────
[mcp.servers.remote-api]
transport = "http"
url = "https://mcp.example.com/sse"
request_timeout_ms = 60000
tool_name_prefix = "api"

[mcp.servers.streamable]
transport = "streamable_http"
url = "http://localhost:8090/mcp"
request_timeout_ms = 30000

Конфигурация для каждого сервера

Поле	Тип	По умолчанию	Описание
enabled	bool	true	Включить или отключить этот сервер
transport	string	"stdio"	Тип транспорта: "stdio", "http", "streamable_http"
command	string	--	Команда для stdio-транспорта (напр., "npx", "uvx", "node")
args	string[]	[]	Аргументы для stdio-команды
url	string	--	URL для HTTP-транспорта
env	map	{}	Переменные окружения для stdio-процесса
startup_timeout_ms	u64	10000	Максимальное время ожидания запуска сервера
request_timeout_ms	u64	30000	Таймаут для каждого запроса
tool_name_prefix	string	"mcp"	Префикс для имён инструментов (напр., "fs" даёт "fs_read_file")
allow_tools	string[]	[]	Белый список инструментов (пустой = разрешить все обнаруженные инструменты)
deny_tools	string[]	[]	Чёрный список инструментов (имеет приоритет над белым списком)

Локальный mcp.json рабочего пространства

PRX обнаруживает MCP-серверы из локального файла mcp.json в рабочем пространстве, следуя тому же формату, что и VS Code и Claude Desktop:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./my-mcp-server/index.js"],
      "env": { "API_KEY": "..." }
    },
    "python-tools": {
      "command": "python3",
      "args": ["-m", "my_mcp_module"],
      "env": {}
    }
  }
}

Разместите этот файл в корневом каталоге рабочего пространства. PRX проверяет mcp.json при запуске и при обновлении инструментов.

Белый список безопасных лаунчеров: Команды в mcp.json ограничены белым списком безопасных лаунчеров:

Лаунчер	Язык / Платформа
npx	Node.js (npm)
node	Node.js
python	Python
python3	Python 3
uvx	Python (uv)
uv	Python (uv)
deno	Deno
bun	Bun
docker	Docker
cargo	Rust
go	Go
ruby	Ruby
php	PHP
dotnet	.NET
java	Java

Команды, не входящие в этот белый список, отклоняются для предотвращения выполнения произвольных бинарников через файлы mcp.json.

Использование

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

MCP-инструменты обнаруживаются автоматически при подключении MCP-клиента к серверам. Агент видит их как обычные инструменты в своём реестре:

Доступные MCP-инструменты:
  fs_read_file          - Прочитать содержимое файла
  fs_write_file         - Записать содержимое в файл
  fs_list_directory     - Список содержимого каталога
  gh_create_issue       - Создать issue на GitHub
  gh_search_code        - Поиск кода на GitHub
  sql_query             - Выполнить SQL-запрос
  sql_list_tables       - Список таблиц базы данных

Пространства имён инструментов

Инструменты каждого MCP-сервера получают настроенный tool_name_prefix для избежания конфликтов имён:

• Сервер filesystem с префиксом "fs" предоставляет fs_read_file, fs_write_file и т.д.
• Сервер github с префиксом "gh" предоставляет gh_create_issue, gh_search_code и т.д.
• Сервер sqlite с префиксом "sql" предоставляет sql_query, sql_list_tables и т.д.

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

Обновление инструментов

Инструмент mcp поддерживает хук refresh(), который заново обнаруживает инструменты перед каждым ходом агента. Это означает:

• Новые инструменты, добавленные на MCP-сервер, становятся доступны без перезапуска PRX
• Удалённые инструменты больше не предлагаются LLM
• Изменения схем инструментов отражаются немедленно

Вызов агентом

Агент вызывает MCP-инструменты так же, как встроенные инструменты:

{
  "name": "gh_create_issue",
  "arguments": {
    "owner": "openprx",
    "repo": "prx",
    "title": "Add support for MCP resource subscriptions",
    "body": "PRX should support MCP resource change notifications..."
  }
}

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

Детали транспортов

Stdio-транспорт

Stdio-транспорт порождает MCP-сервер как дочерний процесс и взаимодействует через stdin/stdout с использованием JSON-RPC:

Процесс PRX
    │
    ├── stdin  ──→ Процесс MCP-сервера
    └── stdout ←── Процесс MCP-сервера

• Сервер запускается при первом использовании (ленивая инициализация) или при старте демона
• Жизненный цикл процесса управляется PRX (автоперезапуск при сбое)
• Вывод stderr от сервера захватывается для диагностики

HTTP-транспорт

HTTP-транспорт подключается к удалённому MCP-серверу через HTTP:

PRX  ──HTTP/SSE──→  Удалённый MCP-сервер

• Поддержка Server-Sent Events (SSE) для потоковых ответов
• Соединение устанавливается при первом вызове инструмента
• Поддержка аутентификации через заголовки (настраивается для каждого сервера)

Streamable HTTP-транспорт

Streamable HTTP-транспорт использует более новый протокол MCP streamable HTTP:

PRX  ──HTTP POST──→  MCP-сервер (streamable)
     ←──Стриминг──

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

Параметры

Сам MCP-инструмент не имеет фиксированных параметров. Каждый MCP-сервер предоставляет свои собственные инструменты со своими схемами параметров, обнаруженными через метод протокола tools/list. Параметры определяются конкретными реализациями MCP-серверов.

Мета-инструмент MCP (для управления) поддерживает:

Параметр	Тип	Обязательный	По умолчанию	Описание
action	string	Нет	--	Действие управления: "status", "refresh", "servers"

Безопасность

Очистка переменных окружения

PRX автоматически удаляет опасные переменные окружения из процессов MCP-серверов для предотвращения атак внедрения:

Удаляемая переменная	Риск
LD_PRELOAD	Внедрение библиотек (Linux)
DYLD_INSERT_LIBRARIES	Внедрение библиотек (macOS)
NODE_OPTIONS	Манипуляция средой выполнения Node.js
PYTHONPATH	Перехват путей модулей Python
PYTHONSTARTUP	Внедрение стартового скрипта Python
RUBYOPT	Внедрение опций среды выполнения Ruby
PERL5OPT	Внедрение опций среды выполнения Perl

Дочернему процессу передаются только явно настроенные переменные env плюс безопасные системные переменные.

Белый список команд для mcp.json

Формат файла mcp.json удобен, но потенциально опасен. PRX снижает этот риск, ограничивая команды белым списком известных безопасных лаунчеров. Это предотвращает выполнение произвольных бинарников через вредоносные файлы mcp.json.

Списки разрешённых/запрещённых инструментов

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

[mcp.servers.filesystem]
# Предоставить только эти инструменты
allow_tools = ["read_file", "list_directory"]
# Заблокировать эти инструменты даже при обнаружении
deny_tools = ["write_file", "delete_file"]

Чёрный список имеет приоритет над белым списком. Это обеспечивает подход эшелонированной защиты, при котором можно разрешить все инструменты по умолчанию, но явно заблокировать опасные.

Сетевая изоляция

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

Для серверов с HTTP-транспортом безопасность удалённого сервера находится за пределами контроля PRX. Убедитесь, что URL HTTP-транспорта указывают только на доверенные серверы.

Политика безопасности

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

[security.tool_policy.tools]
mcp = "allow"           # Разрешить все MCP-инструменты глобально
fs_write_file = "deny"  # Заблокировать конкретные MCP-инструменты по имени с префиксом

Журнал аудита

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

• Имя сервера и имя инструмента
• Аргументы (с редактированием конфиденциальных значений)
• Статус ответа
• Время выполнения

Связанные разделы

• Справочник конфигурации -- настройки [mcp] и [mcp.servers]
• Обзор инструментов -- встроенные инструменты и обзор интеграции MCP
• Песочница безопасности -- песочница для процессов MCP-серверов
• Управление секретами -- зашифрованное хранилище учётных данных MCP-серверов
• Выполнение shell -- альтернатива для запуска инструментов через shell-команды