Перейти к основному содержимому

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

Как реально пользоваться MCP в повседневных workflow.

Страница фичи объясняет что такое MCP; здесь — как быстро и безопасно получить от него пользу.

Когда использовать MCP?​

Используйте MCP, если:

  • инструмент уже есть как MCP-сервер, и вы не хотите писать native VibeOS tool
  • нужен чистый RPC к локальной или удалённой системе
  • важен per-server контроль поверхности инструментов
  • надо подключить внутренние API / БД / корпоративные системы без правок VibeOS core

Не используйте MCP, если:

  • встроенный инструмент VibeOS уже закрывает задачу
  • сервер отдаёт огромную опасную поверхность, а фильтровать вы не готовы
  • нужна одна узкая интеграция — проще и безопаснее native tool

Ментальная модель​

MCP — слой адаптера:

  • VibeOS остаётся агентом
  • MCP-серверы отдают инструменты
  • VibeOS обнаруживает их при старте или reload
  • модель вызывает их как обычные tools
  • вы решаете, какая часть каждого сервера видна

Важно последнее. Хороший MCP — не «подключить всё», а «подключить нужное с минимальной поверхностью».

Из Cursor? См. Cursor → VibeOS — маппинг rules/skills/hooks/MCP и карантин stub-плагинов.

Шаг 1: установите MCP support​

Если вы установили VibeOS со стандартным сценарием установки, поддержка MCP уже включена (установщик запускается uv pip install -e ".[all]").

Если вы установили без дополнительные функции и необходимо добавить MCP отдельно:

cd ~/.vibeos/vibeos-agent
uv pip install -e ".[mcp]"

Для серверов на базе npm убедитесь, что Node.js и npx доступны.

Для многих серверов Python MCP uvx — хороший вариант по умолчанию.

Шаг 2: сначала добавьте один сервер​

Начните с одного безопасного сервера.

Пример: доступ к файловой системе к одному только каталог проекта.

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

Затем запустите VibeOS:

vibeos chat

Теперь спросите что-нибудь конкретное:

Inspect this project and summarize the repo layout.

Шаг 3: подтвердите MCP loading​

Вы можете подтвердить несколькими способами:

  • VibeOS banner/status должен показывать интеграцию MCP при настройке
  • спросить VibeOS, какие инструменты доступны
  • использовать /reload-mcp после настройки изменения
  • проверьте журналы, если серверу не удалось подключиться

Практическая тестовая подсказка:

Tell me which MCP-backed tools are available right now.

Шаг 4: начните фильтрацию немедленно​

Не ждите, пока сервер предоставит много инструментов.

Пример: внесите в белый список только то, что вы хочу​

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

Обычно это лучший вариант по умолчанию для чувствительных систем.

WSL2: мост VibeOS в WSL к Windows Chrome​

Это практическая настройка, когда:

  • VibeOS работает внутри WSL2
  • браузер, которым вы хотите управлять, является вашим обычный вход в систему Chrome на Windows
  • /browser connect неудобен или ненадежен с WSL

В этой настройке VibeOS не подключается к Chrome напрямую. Вместо этого:

  • VibeOS запускается в WSL
  • VibeOS запускает локальный stdio MCP server
  • что сервер MCP запускается через взаимодействие Windows (cmd.exe или powershell.exe)
  • MCP сервер подключается к вашей прямой трансляции Windows Chrome сеанс

Ментальная модель:

VibeOS (WSL) -> MCP stdio bridge -> Windows Chrome

Почему этот режим полезен​

  • вы сохраняете свой настоящий
  • профиль браузера Windows, файлы cookie и логины
  • VibeOS остается в поддерживаемой среде Unix (WSL2)
  • управление браузером предоставляется как инструменты MCP вместо использования основного транспорта браузера VibeOS

Рекомендуется server​

Используйте chrome-devtools-mcp.

Если на вашем Windows Chrome уже включена удаленная отладка в реальном времени из chrome://inspect/#remote-debugging, добавьте это вот так от WSL:

vibeos mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

После сохранения сервера:

vibeos mcp test chrome-devtools-win

Затем начните новый сеанс VibeOS или запустите:

/reload-mcp

Типичная подсказка​

После загрузки VibeOS может напрямую использовать инструменты браузера с префиксом MCP. Например:

调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。

Когда /browser connect является неправильным инструментом​

Если VibeOS работает в WSL и Chrome работает Windows, /browser connect может выйти из строя, даже если Chrome открыт и допускает отладку.

Распространенные причины:

  • WSL не может достичь той же локальной конечной точки Chrome предоставляет Windows инструменты
  • более новые Chrome потоки оперативной отладки, которые отличаются от классических ws://localhost:9222
  • к браузеру легче подключиться из Windows боковой помощник, например chrome-devtools-mcp

В таких случаях сохраните /browser connect для настроек в той же среде и используйте MCP для WSL-to-Windows Мост браузера.

Известные ловушки​

  • Запустите VibeOS из Windows-смонтированный путь, например /mnt/c/Users/<you> или /mnt/c/workspace/...` при использовании Windows stdio исполняемых файлов через MCP.
  • Если вы запустите VibeOS от /root или /home/..., Windows может выдать предупреждение UNC о текущем каталоге перед запуском сервера MCP.
  • Если chrome-devtools-mcp --autoConnect истекает время при перечислении страниц, уменьшите количество вкладок background/frozen в Chrome и повторите попытку.

Пример: опасный черный список действия​

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Пример: также отключить оболочки утилит​

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

На что фактически влияет фильтрация?​

Существует две категории MCP-экспонируемых функций в VibeOS:

  1. Собственные серверные инструменты MCP
  • фильтруются с помощью:
  • tools.include
  1. VibeOS-добавлены оболочки утилит
  • фильтровано с помощью:
  • tools.resources
  • tools.prompts

Оболочки утилит, которые вы можете увидеть​

Resources:

  • list_resources
  • read_resource

Подсказки:

  • list_prompts
  • get_prompt

Эти оболочки появляются только если:

  • ваша конфигурация их допускает, и
  • сеанс сервера MCP действительно поддерживает их возможности

Так что VibeOS не будет притворяться, что сервер имеет resources/prompts, если это не так.

Общие шаблоны​

Шаблон 1: локальный помощник проекта​

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

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

Хорошие подсказки:

Review the project structure and identify where configuration lives.
Check the local git state and summarize what changed recently.

Шаблон 2: рабочая запись репозитория с помощью Open Scaffold​

Используйте Open Scaffold, если вы хотите, чтобы VibeOS прочитал надежные данные репозитория Протокол работы ИИ: миссия, планы, заметки с доказательствами, пакеты передачи и результаты review/gate. VibeOS остается агентом; Open Scaffold остается локальной записью репозитория.

Добавьте сервер для одного репозитория шаблонов:

vibeos mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /absolute/path/to/repo
vibeos mcp test open_scaffold

Затем держите открытую поверхность ориентированной на чтение. Выберите select в приглашении vibeos mcp add или отредактируйте config.yaml позже:

mcp_servers:
  open_scaffold:
    command: "npx"
    args: ["-y", "open-scaffold@latest", "mcp", "serve", "--repo", "/absolute/path/to/repo"]
    tools:
      include:
        - list_plans
        - get_plan
        - get_mission
        - list_evidence
        - get_evidence
        - get_status
        - search_plans
        - list_amendments
        - get_handoff
        - analyze_loop
        - gate_loop
      prompts: false

Хорошие подсказки:

Use the Open Scaffold MCP tools to compile the current handoff packet and tell me the next legal action.
Inspect the active plans and evidence notes, then say whether this repo is ready for human review or needs another attempt.

Граничные примечания:

  • Open Scaffold MCP по умолчанию является локальным и доступен только для чтения.
  • Для его инструментов записи требуется запуск сервера с --allow-write; не включайте это до тех пор, пока вы явно не захотите, чтобы VibeOS изменял файлы .osc.
  • Открытые записи Scaffold и шлюзы работают; он не разрешает VibeOS объединять, публиковать, развертывать или создавать среды выполнения.
  • Закрепите open-scaffold@<version> вместо @latest`, если вам нужны воспроизводимые схемы инструментов.

Шаблон 3: GitHub помощник по сортировке​

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

Хорошие подсказки:

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

Схема 4: внутренний API помощник​

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

Хорошие подсказки:

Look up customer ACME Corp and summarize recent invoice activity.

Это такое место, где строгий белый список намного лучше, чем список исключений.

Схема 4: серверы документации/информации​

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

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

Хорошие подсказки:

List available MCP resources from the docs server, then read the onboarding guide and summarize it.
List prompts exposed by the docs server and tell me which ones would help with incident response.

Учебное пособие: комплексная настройка с фильтрацией​

Вот практический прогресс.

Этап 1: добавьте GitHub MCP с жестким белым списком​

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

Начните VibeOS и спросите:

Search the codebase for references to MCP and summarize the main integration points.

Этап 2: расширяйте только при необходимости​

Если вам позже также понадобятся обновления проблем:

tools:
  include: [list_issues, create_issue, update_issue, search_code]

Затем перезагрузите:

/reload-mcp

Этап 3: добавьте второй сервер с другой политикой​

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

Теперь VibeOS можно их комбинировать:

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

Вот где MCP становится мощным: мультисистемные рабочие процессы без изменения ядра VibeOS.

Безопасное использование рекомендации​

Предпочитайте списки разрешенных для опасных систем​

Для финансовых, клиентоориентированных или разрушительных действий:

  • используйте tools.include
  • начните с наименьшего набора возможно

Отключите неиспользуемые утилиты​

Если вы не хотите, чтобы модель просматривала сервер resources/prompts, отключите их:

tools:
  resources: false
  prompts: false

Сохраняйте узкую область действия серверов​

Примеры:

  • сервер файловой системы с корнем в одном каталоге проекта, а не весь домашний каталог
  • сервер git указывает на один каталог repo
  • внутренний сервер API с инструментами, ориентированными на чтение, по умолчанию

Перезагрузка после изменения конфигурации​

/reload-mcp

Сделайте это после изменения:

  • include/exclude списки
  • включенных флагов
  • resources/prompts переключает
  • аутентификацию headers / env

Устранение неполадок по признаку​

"Сервер подключается, но ожидаемые инструменты отсутствуют"​

Possible причины:

  • отфильтровано tools.include
  • исключено tools.exclude
  • утилиты-обертки отключены через resources: false или prompts: false
  • сервер на самом деле не поддерживает resources/prompts

"Сервер настроен, но ничего load"​

Проверьте:

  • enabled: false не осталось в конфигурации
  • command/runtime существует (npx, uvx и т. д.)
  • HTTP конечная точка достижима
  • окружение аутентификации или заголовки верны

"Почему я вижу меньше инструментов, чем Сервер MCP рекламирует?"​

Потому что VibeOS теперь уважает вашу политику для каждого сервера и регистрацию с учетом возможностей. Это ожидаемо и обычно желательно.

"Как удалить сервер MCP, не удаляя config?"​

Используйте:

enabled: false

Это сохраняет конфигурацию, но предотвращает подключение и регистрацию.

Рекомендуется в первую очередь MCP setups​

Хорошие первые серверы для большинства пользователи:

  • файловая система
  • git
  • GitHub
  • выборка/документация MCP серверы
  • один узкий внутренний API

Не очень хорошие первые серверы:

  • гигантские бизнес-системы с множеством деструктивных действий и без фильтрации
  • все, что вы не понимаете достаточно хорошо, чтобы constrain

Сопутствующие документы​

  • [
  • [
  • (Модельный контекстный протокол)](/user-guide/features/mcp)
  • FAQ
  • slash-команды