Tetiva
Войти
Все разделы

Продвинутое

MCP-сервер

На этой странице

Внутри Tetiva работает MCP-сервер «Tetiva DevTools»: он публикует 33 инструмента, через которые ИИ-агент читает ваши воркспейсы, коллекции, запросы и окружения, создаёт новые и выполняет сохранённый запрос — с теми же окружениями, скриптами и историей, что и при нажатии Send. Ничего копировать в чат не нужно: агент подключается к приложению по адресу 127.0.0.1:9300.

Сервер объявляет только инструменты (tools). Ресурсов и промптов у него нет, и работает он ровно столько, сколько открыто окно приложения.

Включение#

Откройте настройки (Cmd/Ctrl+, или шестерёнка внизу панели слева) и перейдите в раздел «ИИ-агенты (MCP)» (в английском интерфейсе — AI agents (MCP)):

  1. Включите переключатель «MCP-сервер».
  2. Проверьте поле «Адрес» — по умолчанию 127.0.0.1:9300.
  3. Перезапустите приложение: раздел напомнит «Перезапустите Tetiva, чтобы изменения вступили в силу», сервер поднимается на старте.

После перезапуска в строке «MCP-сервер» написано «Работает», а схема вверху раздела показывает адрес, на котором он слушает.

MCP можно задать и переменными окружения: TETIVA_MCP=1 включает сервер, TETIVA_MCP_ADDR задаёт адрес. Старые имена GOPHERCOURIER_MCP и GOPHERCOURIER_MCP_ADDR продолжают работать. Если переменные заданы, поля в настройках блокируются, и там написано «Задано переменными окружения».

Подключение агента#

Сервер требует токен доступа. Кнопка «Скопировать конфиг» в настройках кладёт в буфер готовый фрагмент для выбранного клиента — Claude Code, Cursor или просто URL — уже с токеном. Claude Code и Cursor передают токен в заголовке, так что в адрес он не попадает. Пресет Claude Code — это запись для .mcp.json:

{
  "mcpServers": {
    "tetiva": {
      "type": "sse",
      "url": "http://127.0.0.1:9300/sse",
      "headers": { "Authorization": "Bearer ВАШ_ТОКЕН" }
    }
  }
}

У Cursor та же запись, только без "type": "sse". Пресет «Только URL» отдаёт один адрес, и токен в нём едет в строке запроса: http://127.0.0.1:9300/sse?token=ВАШ_ТОКЕН.

Вместо .mcp.json Claude Code можно подключить одной командой:

claude mcp add --transport sse tetiva http://127.0.0.1:9300/sse \
  --header "Authorization: Bearer ВАШ_ТОКЕН"

Кнопка копирования рядом с токеном в настройках кладёт в буфер само значение — именно оно нужно этой команде; «Скопировать конфиг» отдаёт целый сниппет.

Конфиги, написанные до появления токена, после обновления перестают работать: сервер отвечает 401, пока токен не добавлен. Скопируйте свежий конфиг из настроек и замените им старую запись.

Приложение при этом должно быть запущено — агент разговаривает с живым окном, а не с файлом базы.

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

33 инструмента#

Без workspace_id инструменты работают с Default Workspace — не обязательно с тем, что открыт в приложении. Какой открыт, показывает is_active в ответе list_workspaces.

Воркспейсы (3). list_workspaces, get_workspace, create_workspace. Список отдаёт активный, удалённый и синхронизационный статус каждого воркспейса; создаётся всегда локальный.

Коллекции (6). list_collections, get_collection, create_collection, update_collection, move_collection, delete_collection. Вложенность задаётся через parent_id, перемещение проверяется на циклы, удаление мягкое и каскадное. Обновление использует оптимистичную блокировку: передайте текущую версию. Поле description — это описание коллекции из вкладки Overview, см. Коллекции.

Запросы (7). list_requests, get_request, create_request, update_request, move_request, send_request, delete_request. create_request принимает HTTP, gRPC, GraphQL и WebSocket; update_request протокол не меняет — он остаётся прежним. Оба принимают заголовки, авторизацию, скрипты и поле description — то самое описание, что лежит на вкладке Docs, см. описание запроса. send_request выполняет HTTP-, gRPC- и GraphQL-запросы и бьёт по вашему API по-настоящему: подставляет переменные активного окружения воркспейса, выполняет скрипты, возвращает статус, заголовки и тело, называет в поле environment окружение, с которым ушёл запрос, и дописывает запись в историю.

Окружения (5). list_environments, get_environment, create_environment, delete_environment, set_active_environment. set_active_environment делает окружение активным в его воркспейсе. Приложение переключается вместе с агентом, а send_request дальше подставляет переменные нового окружения.

Переменные (3). list_variables, create_variable, delete_variable. Запись значений не ограничена, чтение — ограничено, см. ниже.

Синхронизация (9). sync_status, sync_push, sync_pull, sync_queue_list, sync_queue_clear, sync_resync, sync_pause, sync_resume, sync_disconnect_stream. Это отладочный набор для Tetiva Cloud: посмотреть состояние движка и очередь, форсировать отправку или приём, поставить воркспейс на паузу и снять с неё, оборвать поток событий один раз, чтобы проверить переподключение с backoff. Кроме ожидающих записей, sync_queue_list показывает в stalled те, что синхронизация придерживает: у каждой статус (failed, parked или deferred), причина и время следующей попытки.

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

Токен

Сервер требует токен. Он генерируется при первом запуске, хранится в базе приложения рядом с остальными настройками MCP и принимается двумя способами — Authorization: Bearer <токен> или ?token=<токен>, потому что не каждый клиент умеет и то и другое. Всё остальное получает 401, в теле которого написано, где взять рабочий конфиг. Проверяются оба эндпоинта — и SSE, и сообщений, так что утёкший идентификатор сессии сам по себе ничего не даёт.

Кнопка «Сменить» в настройках меняет токен сразу, на живом сервере: все конфиги агентов со старым значением придётся обновить. Переключатель «Требовать токен» выключает проверку. Это запасной выход для клиента, который не умеет ни заголовок, ни query, и осознанный шаг: с выключенной проверкой любой процесс на машине — включая вкладку браузера, которая ходит на 127.0.0.1, — читает все коллекции и переменные и выполняет запросы от вашего имени.

Адрес по умолчанию — loopback, адрес без хоста (:9300) приводится к 127.0.0.1:9300 при старте, в том числе в уже сохранённых настройках. Если вы осознанно указываете сетевой адрес, приложение оставляет его, но пишет предупреждение в лог и подсвечивает поле в настройках.

От чего токен не защищает: от того, кто и так читает ~/.tetiva/data.db. В этом файле лежит и сам токен, и всё остальное. Шифрование локальной базы — отдельная история.

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

  • auth_data запросов и коллекций — всегда [redacted], тип авторизации при этом виден.
  • Значения переменных с флагом «секрет» — не возвращаются ни в list_variables, ни в get_environment, ни в ответе на создание переменной.
  • Значения заголовков с учётными данными — и в сохранённых запросах, и в ответе send_request: authorization, proxy-authorization, cookie, set-cookie, x-api-key, api-key, x-auth-token, x-access-token, x-csrf-token, x-session-token.
  • Метаданные gRPC с теми же именами — в gRPC-запросе токен лежит там, а не в заголовке.
  • Параметры запроса в URL: token, access_token, refresh_token, api_key, apikey, key, secret, password, sig, signature.
  • Вывод скриптов в ответе send_request: если упавший тест или console.log цитирует секрет активного окружения, учётные данные авторизации запроса (включая закодированный basic и полученный токен OAuth 2.0) или то, с чем запрос на самом деле ушёл (подписанный JWT, токен из pre-скрипта, cookie), значение маскируется.

Значение, составленное только из ссылок {{variable}}, остаётся как есть, в том числе после схемы авторизации: Bearer {{token}} или {{a}}{{b}}. Это имена переменных, а не сами секреты, и агенту нужно видеть, какая переменная в деле. Значение, где есть хоть немного буквального текста, например session=abc; theme={{ui}}, маскируется целиком: буквальная часть всё ещё секрет.

Осознанно не маскируем: тела запроса и ответа — без них send_request бесполезен для отладки, так что токен, вернувшийся в ответе на логин, придёт целиком, — pre- и post-скрипты и переменные без флага «секрет».

Маскирование ничего не стирает. update_request и update_collection применяют ровно те аргументы, что вы передали, поэтому пропущенное поле сохраняет своё значение — включая name, который передавать больше не обязательно. Некоторые поля пропустить нельзя — чтобы изменить один заголовок, приходится присылать весь массив, — поэтому каждый [redacted], вернувшийся на запись, сопоставляется с тем, что хранится под тем же именем, и подменяется настоящим значением до сохранения. Значит, [redacted] можно вернуть как есть: секрет сохранится, а чтобы сменить его, достаточно передать новое значение. Что именно восстановлено, видно по полю kept_secrets в ответе: auth_data, headers.<имя>, url.query.<параметр>, grpc_metadata.<ключ>. Если восстанавливать было нечего, поля нет.

Маска, за которой ничего нет, не пишется, а отклоняется: create_request и create_collection отвечают ошибкой на [redacted] сразу, а при обновлении маска под именем, которому нечего сопоставить — например, у только что добавленного заголовка, — возвращается ошибкой с просьбой прислать настоящее значение. С синхронизацией отдельная история — она описана на странице Синхронизация.

Каталог данных#

Инструменты работают с той же базой, что и окно приложения, — ~/.tetiva/data.db. Каталог переопределяется переменной TETIVA_DATA_DIR (старое имя GOPHERCOURIER_DATA_DIR продолжает работать как запасное). Это удобно, когда нужен второй экземпляр Tetiva с отдельной базой и своим портом MCP: тогда агент не заденет рабочие коллекции. Подробнее о расположении данных — на странице Настройки.

обновлено