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

MCP (Model Context Protocol) — это стандартный способ подключить к агенту внешние инструменты: на нём говорят GitHub, файловые системы, Notion, базы данных и ещё сотни серверов. У Chimera есть полноценный клиент MCP: инструменты любого сервера становятся обычными инструментами Chimera, лежат в том же реестре, что и встроенные, и подчиняются тем же слоям — списку разрешений, ядру и журналу.

Удалённый streamable HTTP

Для конечной точки MCP, работающей по streamable HTTP, укажите url вместо command. CLI принимает chimera mcp add NAME --url https://host.example/mcp; для аутентификации используйте --token-env ENVIRONMENT_VARIABLE — так bearer-токен разрешается во время выполнения, а его значение не сохраняется в mcp.json.

Для локального stdio-сервера команда chimera mcp add NAME --command ... --cwd DIRECTORY задаёт рабочий каталог (относительные пути разрешаются от рабочего каталога Chimera; каталог должен уже существовать). --catalog-timeout SECONDS задаёт отдельное ограничение на получение каталога инструментов; --connect-timeout ограничивает только установление сессии. В аргументах и значениях --env KEY=VALUE можно использовать ссылки {env:NAME} — они разрешаются из окружения процесса Chimera при подключении. Если переменная отсутствует, подключение завершается ошибкой; разрешённые значения не записываются обратно в mcp.json и не возвращаются API. Чтобы приостановить сервер, не удаляя его конфигурацию и утверждённый манифест, используйте chimera mcp disable NAME; команда chimera mcp enable NAME снова включит его. Отключённые серверы остаются видимыми в конфигурации, но не подключаются и не добавляются агенту.

Большинство размещённых MCP-серверов (Notion, Linear, Atlassian, Supabase…) входят через OAuth. Добавьте сервер по URL (chimera mcp add notion --url https://mcp.notion.com/mcp) и войдите командой chimera mcp login notion в терминале или кнопкой Подключить на экране MCP в приложении. Chimera следует спецификации авторизации MCP (редакция 2025-11-25): находит сервер авторизации по метаданным защищённого ресурса сервера (RFC 9728, RFC 8414 / OpenID Discovery), отклоняет издателя, отличного от объявленного сервером, регистрируется динамически (RFC 7591), если oauth_client_id не задан, и выполняет поток кода авторизации с PKCE S256 и индикатором resource (RFC 8707) через loopback-перенаправление на 127.0.0.1 со случайным портом (RFC 8252). Токены обновляются по истечении срока. Отключить (или chimera mcp logout) отзывает их, если сервер это поддерживает. Сервер с заранее зарегистрированным клиентом продолжает работать через oauth_authorization_url, oauth_token_url и oauth_client_id.

Токены и зарегистрированный клиент хранятся в системном хранилище учётных данных (необязательный extra secrets) или, где хранилища нет (контейнер, VPS), в <home>/mcp_oauth/ с режимом 0600. Никогда в mcp.json, в логе или в ответе API; инструменты чтения и оболочка агента к этой папке не допускаются. Браузер открывается только по действию владельца: chimera mcp login отказывается работать без интерактивного терминала, а «Подключить» требует окна самого приложения. Всё, что работает без присмотра (пул, serve, боты, cron, Test на экране), использует сохранённый вход или завершается сообщением подключиться в приложении. Учётные данные отправляются только по https или по обычному http на loopback.

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

Установите дополнение с клиентом

Клиент MCP вынесен в необязательное дополнение, чтобы ядро оставалось лёгким:

uv sync --extra mcp

Большинство серверов — это пакеты Node, поэтому понадобится ещё npx (идёт вместе с Node.js).

Проверка за 60 секунд (без учётных данных)

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

from chimera.integrations import connect_stdio
from chimera.tools import default_registry

connector = connect_stdio(
    "fs",
    "npx", ["-y", "@modelcontextprotocol/server-filesystem", "./sandbox_dir"],
    name_prefix="fs_",   # avoid clashes with built-in tool names
)

registry = default_registry()
for tool in connector.tools():
    registry.register(tool)

print(registry.names())  # built-ins + fs_read_file, fs_write_file, fs_list_directory...

Передайте этот реестр объекту Agent (или посмотрите examples/mcp_github.py с полным циклом) — и модель сможет вызывать инструменты сервера как любые другие.

Настоящий сервер: GitHub

import os
from chimera.integrations import connect_stdio

connector = connect_stdio(
    "github",
    "npx", ["-y", "@modelcontextprotocol/server-github"],
    env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_PERSONAL_ACCESS_TOKEN"]},
    name_prefix="gh_",
)

Это и есть вся интеграция: в реестре появляются около 26 инструментов GitHub (искать репозитории, читать файлы, перечислять задачи, создавать пул-реквесты и так далее). Готовый к запуску вариант: examples/mcp_github.py.

Как это ложится на слои безопасности

Инструменты MCP — это обычные объекты Tool, поэтому всё складывается:

• Список разрешений на сессию — restrict_registry(registry, allow=["gh_search_repositories", ...]) даёт только те инструменты MCP, которые нужны этому запуску; неразрешённые до модели не доходят.
• Ядро управления — govern_registry(...) пропускает вызовы MCP через разрешить / предупредить / разобрать / заблокировать так же, как любую команду оболочки.
• Журнал заражения — оберните через ledger_registry(...), и обращения MCP будут записаны; учтите, что сегодня автоматически классифицируются только инструменты, названные в FETCH_TOOLS, поэтому считайте содержимое MCP недоверенным и предпочитайте режим --taint --guard, когда сервер тянет внешние данные.
• instructions сервера — текст, который сервер возвращает при initialize, отбрасывается, намеренно: это недоверенный текст сервера, и ничто не помечает его как данные, как помечается огороженное чтение. Цена в том, что подсказки сервера по использованию никогда не доходят до модели; но и хосту, который их передаёт, не стоит на них рассчитывать (arXiv 2608.08467: при доступном инструменте поиска 9 из 24 моделей опустились ниже 15% на справках, помещённых в инструкции сервера). Передавать их как огороженные данные под taint — открытый вопрос, не сделано. Отбрасывание — не граница против текста, написанного сервером: имена и описания инструментов того же сервера доходят до модели так, как их написал сервер, без ограждения; подключённый сервер — это сервер, чьи слова читает модель.
• Закрепление манифеста — при первом подключении сервера имена, описания и input schema его инструментов запоминаются в mcp_pins.json рядом с mcp.json. Если при последующем подключении список хоть в чём-то отличается, сервер задерживается: общий пул MCP не подключает его для вызывающих, использующих этот пул, пока вы не одобрите изменение — со старым и новым текстом перед глазами — через chimera mcp approve ИМЯ или экран MCP. Проверка манифеста пула реализована в chimera/integrations/mcp_pool.py. chimera mcp list показывает задержанные серверы. Подключаются именно те инструменты, что прошли проверку, поэтому сервер не может ответить проверке одним текстом, а модели другим. Добавление или удаление сервера через chimera mcp add/remove или в приложении забывает его закрепление (следующее подключение снова считается первым). Закрепление — это доверие при первом использовании: оно ловит описание, которое меняется, а не то, что было враждебным с самого начала. Без этой защиты: Python API выше. connect_stdio подключает всё, что перечислит сервер, и так же поступает autoload_into_registry, если не передать ему mcp_path — файл, чьи закрепления он должен проверять.
• Сигналы выбора — chimera mcp test и экран MCP помечают инструменты фразами, которые пытаются управлять тем, какой инструмент выберет модель («always use this tool», «do not use other tools», «ignore previous instructions», <IMPORTANT>), читая описание и каждое описание параметра. Это только пометка: она ничего не отклоняет, и как часто она срабатывает на честных серверах, не измерялось.

Chimera в роли сервера MCP

Клиент выше позволяет Chimera вызывать чужие инструменты. Обратное тоже работает: запустите Chimera как сервер MCP, и любой клиент — Claude Desktop, среда разработки, другой агент — сможет вызвать весь движок как три инструмента.

uv sync --extra mcp
chimera serve --mcp        # speaks MCP over stdio

Открываются:

Инструмент	Что делает
chimera_solve	Самостоятельно решает задачу с планом и проверкой-или-откатом; возвращает ответ.
chimera_fuse	Отвечает на запрос через движок LLM-Fusion (панель → судья → синтезатор).
chimera_memory_search	Ищет в долговременной памяти Chimera и возвращает лучшие факты.

Направьте на него клиент MCP как на сервер stdio. Для Claude Desktop добавьте в его конфигурацию:

{
  "mcpServers": {
    "chimera": { "command": "chimera", "args": ["serve", "--mcp"] }
  }
}

Режиму --mcp нужен ключ поставщика для chimera_solve и chimera_fuse (поиск по памяти работает и без него). Добавьте --fuse, чтобы направить глубокие ходы решателя через слияние, и --no-memory, чтобы пропустить обращение к памяти. Поскольку проводом служит stdio, все журналы идут в stderr — в stdout только протокол.

Как дать Claude управлять настольным приложением

chimera serve --mcp собирает собственного агента. chimera mcp desktop не собирает ничего: это пульт для настольного приложения, которое у вас уже открыто, поэтому Claude видит те же диалоги, прогоны и одобрения, что и вы, а всё, что он запускает, работает под управлением приложения, на его экранах.

1. В приложении откройте Настройки → Claude и включите Разрешить Claude управлять этим приложением.

2. Зарегистрируйте сервер в Claude Code (или добавьте ту же команду в конфигурацию Claude Desktop):

   claude mcp add chimera-desktop -- chimera mcp desktop
   

С первым переключателем Claude может читать и начинать диалоги (desktop_send), прогоны, пакеты, доски и задания cron, искать и редактировать память, читать файлы и состояние git. Запущенный им прогон несёт настроенный вами режим, а запрос, пытающийся его расширить, — команда verify, выполнение на хосте, другой агент, автоодобрение — отклоняется. Одобрения остаются за вами: desktop_approvals только перечисляет их. Если ход останавливается на одобрении, desktop_send сразу отвечает, что ждёт вас, а ход продолжается в приложении; desktop_job сообщает, чем он закончился.

Второй переключатель, Полный контроль, добавляет desktop_approve (отвечать на одобрения и шаги с контрольной точкой) и desktop_settings (менять настройки и идентичность агента). С ним Claude может одобрять действия без вас — и страница или сообщение с prompt injection, прочитанные агентом, могут его к этому подтолкнуть. Пока он выключен, эти два инструмента вообще не перечисляются, а приложение отклоняет их, даже если их вызвать.

Некоторые решения остаются за вами при любом переключателе. Какая модель отвечает — каждая настройка модели, цепочка запасных моделей, панель, судья и синтезатор слияния, режим расходов, каскад и проверенные ответы — и запускает ли приложение задания по расписанию, Claude может только предложить: ничего не записывается, а приложение показывает вам карточку с текущим и предложенным значением каждой настройки, чтобы вы одобрили или отклонили её там. Claude не может ответить на эту карточку никаким путём; если настройка изменилась до вашего одобрения, ничего не применяется. А разрешение команд в папке, запуск команды в Runner, запуск бота мессенджера и сохранение агента с его правами на инструменты мост отклоняет полностью: это делаете вы в приложении.

И запуск, который начинает Claude, при любом переключателе работает на настроенных вами моделях и не заходит дальше настроенного вами режима. Запрос, называющий модель, план ролей, профиль, панель слияния или другого агента, отклоняется; как и более широкий режим — больший охват, более мягкие одобрения, выполнение на хосте или команда verify там, где вы не разрешили оболочку, или автоматическое одобрение. Попросить запуск делать меньше (только чтение или всегда спрашивать) разрешено.

Чего не позволяет ни один переключатель: читать или записывать ключ API, токен или вебхук. Правки настроек отклоняют имена учётных данных, маршруты с ключами или ссылками общего доступа недоступны, файлы учётных данных (.env, закрытые ключи) нельзя читать, записывать или искать по ним, а каждый результат очищается от значений учётных данных. Нельзя и направить рабочую папку на папку данных приложения или на папку, которая её содержит (например, домашнюю): там хранятся ответы на одобрения, и файл, записанный туда, ответил бы на одно из них.

Как происходит подключение: пока переключатель включён, приложение пишет ~/.chimera/desktop-bridge.json (URL своего API на loopback и случайный токен; в POSIX доступен для чтения только вам, в Windows лежит в вашем профиле). Выключение переключателя или закрытие приложения удаляет файл и отзывает токен. Если приложение закрыто, любой инструмент отвечает «Chimera desktop is not running, or 'Allow Claude to operate this app' is off in Settings.» Claude получает список инструментов при подключении; после включения или выключения Полного контроля переподключите сервер (/mcp в Claude Code), чтобы увидеть новый список.

Разговор на A2A (агент → агент)

MCP соединяет агентов с инструментами; A2A (Agent2Agent, Linux Foundation) соединяет агентов друг с другом — он встроен в LangGraph, CrewAI и AutoGen. Chimera говорит и на нём, поэтому оркестратор на LangGraph или CrewAI может передать задачу Chimera и получить готовый результат.

chimera a2a-card                       # print the Agent Card JSON
chimera serve --a2a                    # HTTP gateway + A2A endpoint

serve --a2a добавляет к HTTP-серверу два маршрута:

Маршрут	Назначение
GET /.well-known/agent.json	Карточка агента — кто он и какие навыки объявляет (solve, fuse).
POST /a2a	Жизненный цикл задачи по JSON-RPC 2.0: message/send, message/stream, tasks/get, tasks/cancel.

Клиент отправляет message/send с текстовой частью; Chimera запускает самостоятельного агента и возвращает задачу в состоянии completed (или failed), несущую ответ как сообщение агента. Либо он отправляет message/stream и получает поток Server-Sent Events: сначала задачу в состоянии working, затем completed или failed, когда запуск завершится, — так оркестратор видит ход дела без опроса. Карточка агента объявляет capabilities.streaming: true.

Честно об охвате: поток сейчас выдаёт два события (working → итог), а не пошаговые приращения токенов, и push-уведомления не реализованы. Это соответствующий стандарту поток без нужды в опросе — достаточно, чтобы быть полноценным потоковым узлом в приложении на LangGraph или CrewAI.

Если что-то не работает

• TimeoutError: MCP server ... did not become ready — команда не запустилась. Выполните ту же строку npx ... вручную в терминале, чтобы увидеть её ошибку (нет токена, нет Node, медленно скачивается пакет при первом запуске — увеличьте connect_timeout).
• ModuleNotFoundError: mcp — установите дополнение: uv sync --extra mcp.
• Столкновения имён инструментов — всегда передавайте name_prefix.
• Сессия держит сервер подпроцессом всё время жизни вашего скрипта; вызовите close() у сессии connector (или просто дайте процессу завершиться), чтобы её свернуть.