OIC Monitoring MCP Server

Сервер только для чтения для MCP для Oracle Integration Cloud (OIC). Подключите к нему MCP-клиент (Claude Code и т.п.) и задавайте вопросы об интеграциях, подключениях, экземплярах выполнения, ошибках и логах потоков на обычном языке — сервер преобразует их в вызовы REST API OIC и возвращает чистый, удобный для LLM JSON.

Создан на FastAPI + WebSocket, аутентификация через OAuth2 Client Credentials (IDCS/IAM).

Содержание

• Требования

• Установка: Windows, macOS, Linux

• Конфигурация (.env)

• Подключение MCP-клиента

• Запуск нескольких окружений из одного репозитория

• Поддержание работы сервера

  • Вариант A: только в рамках сеанса (завершается при закрытии терминала)

  • Вариант B: постоянный фоновый сервис (переживает перезагрузку)

• Инструменты

• Формат ответа

• Как это работает

• Защита продакшна

• Устранение неполадок

Требования

Место на диске требуется немного: виртуальное окружение занимает примерно 120 MB, а логи ограничены суммарно примерно 60 MB.

Установка

Процесс одинаков на всех платформах:

1. Установите Python 3.10+

2. Получите код

3. Создайте виртуальное окружение и установите зависимости

4. Создайте и заполните свой .env

5. Запустите сервер и проверьте

В зависимости от ОС отличаются только шаг 1 и команда активации виртуального окружения.

Windows

1. Установка Python

Самый простой способ — через winget в PowerShell:

winget install -e --id Python.Python.3.12

Или скачайте установщик с python.org/downloads/windows. Если используете установщик, отметьте галочкой «Add python.exe to PATH» на первом экране. Именно эта галочка — источник большинства последующих проблем вида «python is not recognized».

Закройте и снова откройте PowerShell, затем проверьте версию:

py -3 --version

Вы должны увидеть Python 3.10.x или новее. Лаунчер py поставляется вместе с официальным установщиком и является самым надёжным способом запуска Python на Windows, поэтому в командах ниже используется именно он.

2. Получите код

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. Создайте виртуальное окружение и установите зависимости

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Если PowerShell блокирует скрипт активации сообщением «running scripts is disabled», разрешите подписанные локальные скрипты для вашего пользователя (одноразово):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Используете cmd.exe вместо PowerShell? Активируйте через .venv\Scripts\activate.bat.

4. Настройка

Copy-Item .env.example .env
notepad .env

Заполните значения, описанные в разделе Конфигурация.

5. Запуск сервера

.\scripts\run-local.ps1

macOS

1. Установка Python

В macOS есть системный Python, на который не стоит завязываться. Установите собственный Python через Homebrew:

brew install python@3.12

Затем проверьте версию:

python3 --version

Нет Homebrew? Либо сначала установите его, либо скачайте установщик для macOS с python.org/downloads/macos.

2. Получите код

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. Создайте виртуальное окружение и установите зависимости

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

4. Настройка

cp .env.example .env
nano .env

5. Запуск сервера

chmod +x scripts/*.sh
./scripts/run-local.sh

Linux

1. Установка Python

Debian / Ubuntu:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git

Пакет python3-venv в дистрибутивах семейства Debian ставится отдельно, и его легко упустить. Без него команда python3 -m venv завершается ошибкой ensurepip is not available.

RHEL / Rocky / Alma / Fedora:

sudo dnf install -y python3.12 python3.12-devel git

Проверьте версию:

python3 --version

Если ваш дистрибутив застрял на версии ниже 3.10 (например RHEL 8, где поставляется Python 3.6), установите более новый интерпретатор рядом с системным (python3.11 или python3.12 из AppStream или deadsnakes) и используйте именно этот явно указанный бинарный файл при создании виртуального окружения, например python3.12 -m venv .venv.

2. Получите код

git clone <your-repo-url> oic-mcp
cd oic-mcp

3. Создайте виртуальное окружение и установите зависимости

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

4. Настройка

cp .env.example .env
nano .env

5. Запуск сервера

chmod +x scripts/*.sh
./scripts/run-local.sh

Проверка установки

По умолчанию сервер слушает интерфейс ws://127.0.0.1:8085/ws. Теперь во втором терминале выполните:

python3 scripts/ws-call.py tools/list

В Windows:

.\.venv\Scripts\python.exe scripts\ws-call.py tools/list

Вы должны получить JSON-список из примерно 40 инструментов. Есть также обычная HTTP-проверка работоспособности, для которой не нужен WebSocket-клиент:

curl http://127.0.0.1:8085/healthz
# {"status": "ok"}

Если возникла ошибка подключения или ответ 401, перейдите к разделу Устранение неполадок.

Изменение хоста и порта

Скрипты run-local.sh и run-local.ps1 оба читают переменную PORT и по умолчанию привязываются только к loopback, если не указано иное:

# Linux / macOS
PORT=8086 ./scripts/run-local.sh
HOST=0.0.0.0 PORT=8086 ./scripts/run-local.sh

# Windows
$env:PORT="8086"; .\scripts\run-local.ps1
$env:MCP_HOST="0.0.0.0"; $env:PORT="8086"; .\scripts\run-local.ps1

Или вызовите uvicorn напрямую — именно это скрипты и делают внутри:

uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets

Привязка к 0.0.0.0 открывает неаутентифицированный WebSocket для вашей сети. Попользуйте такую привязку только за TLS и брандмауэром, см. Защита продакшна.

Конфигурация (.env)

Скопируйте .env.example в .env и заполните:

Клиенту вашего конфиденциального приложения также потребуется роль приложения ServiceUser, назначенная на ресурсное приложение экземпляра OIC в IDCS/IAM (не в самом клиентском приложении) — иначе каждый вызов будет завершаться с ошибкой 401 даже при валидном токене. См. Устранение неполадок.

Файлы .env и все .env.* находятся в .gitignore (в репозитории отслеживается только .env.example), поэтому ваши секреты не попадают в репозиторий.

Подключение MCP-клиента

Claude Code:

claude mcp add-json oic '{"type":"ws","url":"ws://127.0.0.1:8085/ws"}'

Любому другому клиенту с поддержкой конфигурации в виде «сырого» JSON добавьте эту запись в конфигурацию его MCP-сервера (например в .mcp.json либо скопируйте mcp.json.example):

{
  "mcpServers": {
    "oic": {
      "type": "ws",
      "url": "ws://127.0.0.1:8085/ws"
    }
  }
}

Этот сервер поддерживает только транспорт WebSocket — это не stdio-сервер, поэтому конфигурация с "type": "stdio" или запуск через команду здесь не работают. Сначала запустите его как отдельный процесс, затем укажите клиенту на этот URL.

После подключения просто спрашивайте агента, например: "список активированных интеграций" или "покажи последние 20 экземпляров выполнения для INTEGRATION_CODE" — вам не нужно самому вызывать инструменты по имени.

Запуск нескольких окружений из одного репозитория

Не нужна вторая копия репозитория, чтобы мониторить Dev, Test и Prod. Один клон репозитория может запускать столько процессов, сколько нужно: каждый процесс указывает на свой файл окружения через переменную OIC_ENV_FILE и использует свой порт.

mcp_server/settings.py при запуске процесса читает OIC_ENV_FILE и загружает этот файл вместо .env. Всё остальное в процессе идентично: тот же код, те же инструменты.

1. Создайте по одному файлу окружения для каждой среды

cp .env.example .env.dev
cp .env.example .env.test
cp .env.example .env.prod

Заполните в каждом файле собственные OIC_BASE_URL, OIC_INSTANCE_NAME и OAuth-учётные данные этого окружения. Дайте каждому процессу отдельный файл логов, чтобы их журналы не перемешивались:

# in .env.prod
MCP_LOG_FILE=mcp_server.prod.log

2. Запустите по одному процессу на каждое окружение, каждому — на своём порту

Linux / macOS:

OIC_ENV_FILE=.env.dev  PORT=8085 ./scripts/run-local.sh
OIC_ENV_FILE=.env.test PORT=8086 ./scripts/run-local.sh
OIC_ENV_FILE=.env.prod PORT=8087 ./scripts/run-local.sh

Windows PowerShell — по одному процессу на терминал, поскольку каждый задаёт собственные переменные:

$env:OIC_ENV_FILE=".env.prod"; $env:PORT="8087"; .\scripts\run-local.ps1

Или вызовите uvicorn напрямую:

OIC_ENV_FILE=.env.prod uvicorn mcp_server.main:app --host 127.0.0.1 --port 8087 --ws websockets

3. Зарегистрируйте каждый процесс у вашего клиента под отдельным именем

{
  "mcpServers": {
    "oic-dev":  { "type": "ws", "url": "ws://127.0.0.1:8085/ws" },
    "oic-test": { "type": "ws", "url": "ws://127.0.0.1:8086/ws" },
    "oic-prod": { "type": "ws", "url": "ws://127.0.0.1:8087/ws" }
  }
}

Тогда ваш агент увидит три набора инструментов с понятными именами, и вы сможете в одном диалоге попросить его сравнить одну и ту же интеграцию между окружениями.

Возможная схема:

Полезно знать:

• OIC_ENV_FILE читается один раз при запуске процесса. Если изменить его значение или сам файл окружения, потребуется перезапуск этого процесса.

• Настоящие переменные окружения ОС имеют приоритет над любым содержимым файла окружения. Если у вас в профиле оболочки экспортирована OIC_BASE_URL, то каждый процесс получит её независимо от того, какой файл окружения он загрузил. Такие переменные держите вне профиля оболочки.

• Каждый процесс нуждается в собственном порте. Два процесса на одном порту завершатся ошибкой «address already in use».

• В Docker флаг --env-file подставляет настоящие переменные окружения, поэтому OIC_ENV_FILE там не нужен. Просто укажите --env-file на нужный файл.

• Все инструменты здесь читают только данные, но принцип минимальных привилегий всё равно полезен: выдавайте OAuth-приложению каждого окружения только роль ServiceUser.

Поддержание работы сервера

Поддерживаем два варианта. Выберите один осознанно, потому что при завершении сеанса они ведут себя совершенно по-раз ному.

Вариант A: только в рамках сеанса (процесс умирает при закрытии терминала)

Идеально подходит для разработки, разовых сеансов изучения данных и для ситуаций, когда вы не хотите, чтобы забытый процесс всю ночь держал учётные данные в памяти.

Запускайте его в активном (переднем) режиме, в своём отдельном терминале:

# Linux / macOS
./scripts/run-local.sh

# Windows
.\scripts\run-local.ps1

Это и есть весь способ. Процесс является потомком этого терминала:

• Ctrl+C останавливает его мгновенно.

• Закрытие окна терминала, завершение SSH-сессии или выход из системы убивает процесс.

• Он никогда не перезапускается сам и не появляется после перезагрузки.

Логи одновременно идут и в терминал, и в mcp_server.log, что делает этот вариант ещё и самым удобным для отладки.

Если выхотите вернуть командную строку, но при этом хотите чтобы процесс завершился вместе с сеансом, запустите его в фоне как задачу оболочки, а не демонизируйте:

./scripts/run-local.sh > uvicorn.log 2>&1 &
echo "started as PID $!"

# later, from the same shell
kill %1

Не оборачивайте это в nohup, setsid, disown, screen или tmux, если вам нужно поведение, ограниченное сеансом. Все они существуют именно для того, чтобы отсоединить процесс от вашего сеанса, и будут держать его живым после вашего выхода из системы.

Чтобы убедиться, что ничего не осталось после закрытия сеанса:

# Linux / macOS
pgrep -af "mcp_server.main"

# Windows
Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
  Where-Object { $_.CommandLine -like "*mcp_server.main*" } |
  Select-Object ProcessId, CommandLine

Вариант B: постоянный фоновый сервис (переживает перезагрузку)

Лучше всего подходит для общего сервера или рабочей станции, где команда ожидает, что конечная точка MCP всегда доступна. Во всех приведённых ниже случаях сервис запускается при загрузке и автоматически перезапускается при сбое.

Не используйте для этого nohup ... & — он переживает выход из системы, но не перезагрузку, и никто не перезапустит его, если процесс умрёт. Используйте системный менеджер сервисов вашей ОС.

Linux (systemd)

Создайте /etc/systemd/system/oic-mcp.service:

[Unit]
Description=OIC Monitoring MCP Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=oicmcp
Group=oicmcp
WorkingDirectory=/opt/oic-mcp
Environment=OIC_ENV_FILE=/opt/oic-mcp/.env.prod
ExecStart=/opt/oic-mcp/.venv/bin/uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets
Restart=always
RestartSec=5

# Basic hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target

Затем:

sudo useradd --system --home /opt/oic-mcp --shell /usr/sbin/nologin oicmcp
sudo chown -R oicmcp:oicmcp /opt/oic-mcp
sudo chmod 600 /opt/oic-mcp/.env.prod

sudo systemctl daemon-reload
sudo systemctl enable --now oic-mcp
sudo systemctl status oic-mcp

enable — это то, что возвращает сервис после перезагрузки. Restart=always — это то, что возвращает его после сбоя. Нужны оба.

Журналы попадают в системный журнал:

journalctl -u oic-mcp -f

Для второго окружения скопируйте unit-файл в oic-mcp-test.service, измените строку Environment=OIC_ENV_FILE= и --port, затем выполните sudo systemctl enable --now oic-mcp-test.

Предпочитаете запускать его от имени собственного пользователя? Поместите тот же unit-файл в ~/.config/systemd/user/oic-mcp.service, включите его с помощью systemctl --user enable --now oic-mcp и выполните sudo loginctl enable-linger $USER, чтобы он запускался при загрузке, а не при первом входе.

macOS (launchd)

Создайте ~/Library/LaunchAgents/com.oic.mcp.plist, заменив /Users/you/oic-mcp на ваш фактический путь:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.oic.mcp</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/oic-mcp/.venv/bin/uvicorn</string>
    <string>mcp_server.main:app</string>
    <string>--host</string><string>127.0.0.1</string>
    <string>--port</string><string>8085</string>
    <string>--ws</string><string>websockets</string>
  </array>

  <key>WorkingDirectory</key>
  <string>/Users/you/oic-mcp</string>

  <key>EnvironmentVariables</key>
  <dict>
    <key>OIC_ENV_FILE</key>
    <string>/Users/you/oic-mcp/.env.prod</string>
  </dict>

  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>

  <key>StandardOutPath</key>
  <string>/Users/you/oic-mcp/launchd.out.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/oic-mcp/launchd.err.log</string>
</dict>
</plist>

Загрузите его:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.oic.mcp.plist
launchctl print gui/$(id -u)/com.oic.mcp | head -20

RunAtLoad запускает его немедленно и снова при каждом входе в систему. KeepAlive перезапускает его, если он завершается.

Чтобы остановить его или перезагрузить после изменения plist-файла:

launchctl bootout gui/$(id -u)/com.oic.mcp
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.oic.mcp.plist

LaunchAgent в ~/Library/LaunchAgents запускается при входе вашего пользователя. Если машина должна отвечать на запросы до того, как кто-либо войдёт, поместите тот же plist-файл в /Library/LaunchDaemons/ (владелец root:wheel, режим 644), добавьте ключ UserName, чтобы сервис не запускался от имени root, и загрузите его командой sudo launchctl bootstrap system /Library/LaunchDaemons/com.oic.mcp.plist.

Для второго окружения продублируйте plist-файл с новым Label (com.oic.mcp.test), другим портом и другим OIC_ENV_FILE.

Windows (NSSM, рекомендуется)

NSSM оборачивает любой исполняемый файл в полноценную службу Windows. Установите его с помощью winget install nssm или choco install nssm, затем в PowerShell с правами администратора:

$proj = "D:\oic_mcp_git"

nssm install OicMcp "$proj\.venv\Scripts\uvicorn.exe" "mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets"
nssm set OicMcp AppDirectory $proj
nssm set OicMcp AppEnvironmentExtra "OIC_ENV_FILE=$proj\.env.prod"
nssm set OicMcp Start SERVICE_AUTO_START
nssm set OicMcp AppStdout "$proj\service.out.log"
nssm set OicMcp AppStderr "$proj\service.err.log"
nssm set OicMcp AppExit Default Restart
nssm set OicMcp AppRestartDelay 5000

nssm start OicMcp

SERVICE_AUTO_START — это то, что возвращает службу после перезагрузки, а AppExit Default Restart — то, что перезапускает её после сбоя.

Управляйте ей как любой другой службой:

Get-Service OicMcp
nssm restart OicMcp
nssm stop OicMcp
nssm remove OicMcp confirm

Для второго окружения установите другую службу под другим именем (например, OicMcpTest) со своим портом и OIC_ENV_FILE.

Windows (Планировщик задач, без дополнительных инструментов)

Если вы не можете установить NSSM, Планировщик задач может запускать его при загрузке. Сначала создайте start-prod.bat в папке проекта, потому что запланированная задача не может легко задать рабочую директорию напрямую:

@echo off
cd /d D:\oic_mcp_git
set OIC_ENV_FILE=D:\oic_mcp_git\.env.prod
".venv\Scripts\python.exe" -m uvicorn mcp_server.main:app --host 127.0.0.1 --port 8085 --ws websockets

Затем зарегистрируйте её в PowerShell от имени администратора:

schtasks /Create /TN "OIC MCP Server" /TR "D:\oic_mcp_git\start-prod.bat" /SC ONSTART /RU SYSTEM /RL HIGHEST /F
schtasks /Run /TN "OIC MCP Server"
schtasks /Query /TN "OIC MCP Server"

Это запускает процесс при загрузке, но не перезапускает его при сбое по умолчанию. Добавьте это в Планировщике задач на вкладке Параметры: «Если задача не выполнена, перезапускать каждую 1 минуту», до 3 раз. NSSM справляется с этим лучше, поэтому он является рекомендуемым вариантом.

Docker (любая платформа)

Политика перезапуска выполняет ту же работу, что и сервис-менеджер, включая перезагрузки хоста, при условии, что сам демон Docker запускается при загрузке:

docker build -t oic-mcp:latest .

docker run -d \
  --name oic-mcp-prod \
  --restart unless-stopped \
  -p 8085:8080 \
  --env-file .env.prod \
  oic-mcp:latest

Контейнер слушает порт 8080 на локальной стороне, поэтому сопоставьте с нужным вам портом хоста. Для запуска второгного окружения измените имя, порт хоста и файл окружения:

docker run -d --name oic-mcp-test --restart unless-stopped \
  -p 8086:8080 --env-file .env.test oic-mcp:latest

Следите за ним с помощью docker ps и docker logs -f oic-mcp-prod.

Какой вариант следует использовать?

Инструменты

Все инструменты доступны через tools/list и доступны только для чтения. Многие принимают необязательный version; если он опущен, автоматически резолвится последняя версия.

Интеграции

• list_integrations — необязательные onlyActivated, limit, page

• list_activated_integrations

• get_integration — по identifier и version

• get_integration_auto — параметры на этапе проектирования по code или code|version, автоматически разрешает последнюю версию

• search_integration_by_name — поиск по полному каталогу (автомагистраниченная с текущей страницей), точное или частичное совпадение, всегда возвращает список

• list_integrations_search — клиент–поиск по страницам по code/name/description/keywords

• export_integration — загрузка архива интеграции как base64 или параметр listOnly записей + превью

Мониторинг времени выполнения

• list_instances — необязательные integrationId, status, startTime/endTime, timewindow, limit

• get_instance — полная детализация по instanceId

• get_instance_activity_stream — пошаговый журнал потока/выполнения для одного экземпляра

• list_errors — необязательные integrationId, timewindow, limit

• list_metrics — исторические метритеки отслеживания, по часам или дням

• list_schedules / get_schedule — информация о планировщике для каждой интеграции

Подключения, пакеты и строительные блоки

• list_connections / get_connection / get_connection_detail

• list_packages / get_package

• list_lookups / get_lookup

• get_library

• list_adapters / get_adapter

• list_agents / list_agent_groups

• list_endpoints — конечные точки интеграции с ролью и подключением

Анализ на этапе проектирования

• summarize_integration — сведение по триггеру, целям и переменным отслеживания

• summarize_integration_with_steps — то же плюс выбранные сводки ввода/вывода по шагам

• summarize_flow_controls — подсчёт и образцы конструкций Switch/ForEach/Route/Fault/Scope

• summarize_mappings — извлечение шагов маппинга

• deep_flow_outline — компактное текстовое изложение всего потока

• get_integration_step — необработанные JSON-подстроки, сопоставляющие stepName (точное + нечёткое), а также соответствующие конечные точки

• summarize_step_io — предполагаемые SQL/запросные фрагменты и параметры для stepName, если шаг не найден, фолбэк на соответствие конечной точки

Утилиты

• fetch_raw_path — получить любой относительный путь OIC

• search_json — подстрочный поиск по любой JSON-подобной структуре

Инструменты на этапе проектирования принимают необязательный designJsonPath для чтения ранее скачанного JSON-файла дизайна с диска вместо вызова OIC — полезно для оффлайн-анализации или уменьшения повторных вызовов при итерациях.

Формат ответа

Каждый результат tools/call следует загонной спецификации MCP {"content": [{"type":"text","text": "<json-or-plain-text>"}],"isError": false}. Фактическая полезная нагрузка инструмента сериализована JSON внутри text — разберите её один раз, чтобы получить структурированные данные:

python3 scripts/ws-call.py tools/call '{"name":"list_integrations","arguments":{"limit":3}}' \
  | python3 -c "
import json, sys
resp = json.load(sys.stdin)
payload = json.loads(resp['result']['content'][0]['text'])
print(json.dumps(payload, indent=2))
"

Ошибки выполнения инструмента (например, OIC недоступен, неверный идентификатор) возвращаются тем же способом с isError: true — учитывайте этот флаг, а не предполагайте успех. Настоящие ошибки протокола (неизвестный метод, неизвестное имя инструмента) используют настоящий объект error JSON-RPC. Большие нагрузки ограничены 100,000 символов и чётко помечаются [TRUNCATED...] при обрезе — никогда не на а тихо.

Как это работает

• Сервер предоставляет одну конечную точку WebSocket, говорящую на JSON-RPC 2.0 / MCP. Клиенты вызывают tools/list для получения списка инструментов и tools/call для их запуска.

• При каждом вызове он получает инции через REST API OIC посредством аутентифицированного httpx.AsyncClient. Токен OAuth кешируется и автоматически обновляется по истечении срока.

• Рукопожатие WebSocket согласует подоген mcp, когда клиент предлагает его, а initialize возвращает соответствующий protocolVersion и capabilities с типом object — это требуется для строгих клиентов вроде Claude Desktop для принятия соединения.

• Перенаправления обрабатываются вручную, а не через встроенную обработку httpx: шлюз Time-Design от OIC делает 307-переадресацию на другой хост, чем OIC_BASE_URL, и httpx по умолчанию удаляет заголовок Authorization при любом перезанятой между хостами. Ручная обработка сохраняет его для этого известного доверенного перехода.

Логирование

Логи записываются в mcp_server.log (переопределяется через MCP_LOG_FILE), автоматически циклируются по 10 МБ на файл с нулевым резервным копированием (~60 МБ потолоку) — они никогда не растут бесконечно. Не требуется logrotate, cron или sudo ни на какой платформе; приложение само управляет размером логов.

При запуске одного процесса на одно окружение задавайте отдельный MCP_LOG_FILE в каждом env-файле, чтобы логи оставались раздельными.

Производственная защ укрепление

• Запускайте за TLS (обратный прокси типа Nginx/Traefik) и ограничивайте сетевой доступ. Конечная точка WebSocket не имеет собственной аутонтификации, поэтому никогда не подставляйтее её напцрямую в недостоверную сеть.

• Держите адрес привязки на 127.0.0.1, если нет особой прицыны.

• Храните секреты в vault, никогда комить не .env. На LInux выполните chmod 600 на env-файл и сделайте владелемьном пользователем сервиса.

• Выдайте OAuth-клиенту минимальную роль из необходимых (ServiceUser — read-only; избегайте ServiceDeveloper, если не нужны именно инструменты создания/импорта).

• Испольмзуйте менеджер процессов (systemd, launchd, NSSM), чтобы переживать перезагрузки, см. Вариант Б.

• Следите из размерами полезной нагрузки на больших каталогах — предпочитаем list_integrations_search с узкими терминами и страничением, а не вытягивание целых списков.

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

Установка и заупск

• python или py не распознается (Windows — Python установлен без 'Add python.exe to PATH' . Перезапустите установщик, выберите Modify, включите эту опцию или перезапустите через winget install --id Python.Python.3.12. Открой новый терминал.

• running scripts is disabled on this system (Windows)* — Политика выполнения PowerShell блокирует активацию виртуального окружения. Выполните Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy.

• — используйте cmd.exe с .venv\Scripts\activate.bat.* Rollback.

• ensurepip is not available (Debian/Ubuntu) — установите отделный пакет python3-venv:sudo apt install python3-venv.

• TypeError: unsuported operand type(s) for | — у вас Python 3.9 или старше. Поставьте 3.10+ и пересоздайте virtualenv с новым интерпетатором.

• ValidationError при запуске со си упоминанием OIC_BASE_URL или OAUTH_* — укажите env-файл не найден или неполный. Убедитесь, что вы скопировали .env.example в .env, что процесс запуска из директории проекта в том же месте, существует.

• address already in use — процесс держит порт. Найдите его с помощью lsof -i :8085 (Linux/macOS) или netstat -ano | findstr :8085 (Windows), или начегов на другом PORT.

Аутентификация

• 401/403 от token URL — проверьте OAUTH_CLIENT_ID/OAuth_CLIENT_SECRET и что OAURL_REN соответствует вашему IDCS/IAM-доме.

• Запрос токена успешен (200), но каждая вызова OIC возвращает 401 — чаще всего это не хватает ролей в IDCS, а не плохой токен. В OCI Console → Identity & Security → Domains → ваш домейн → найдите ресурсное приложение самого экземпляра OIC (не ваше конфиденциальное клиентское приложение) → Application roles → ServiceUser → назначьте ваше конфиденциальное клиентское приложение как application. Получите свежий ток, поке наблюдая его — сущеествующий токен не получит ролей ретроспективно.

Подключeние

• Отказ в соединении / WebSocket недоступен — убедитесь, что процесс сервера действительно запущен (pgrep -af mcp_server.main, systemctl status oic-mcp или Get-Service OicMcp) и что тот же порт не используется ничем другим. Быстрее всего проверить это командой curl http://127. 0.0.1:8085 /healthz. Claude Code показывает сервер как «всё ещё подключающийся» или его инструменты так и не загружаются — сервер должен быть запущен до начала клиентской сессии; если он ещё не был запущен, автоматическое повторное подключение не происходит. Перезапустите клиент после того, как убедитесь, что сервер исправно работает. Возвращаются данные из неправильного окружения — переменная окружения реальной ОС переопределяет ваш env-файл, и эти переменные имеют приоритет. Проверьте с помощью env | grep OIC_ (Linux/macOS) или Get-ChildItem Env:OIC_* (Windows) и удалите все устаревшие из профиля оболочки.

Использование инструментов

• 404 на определённых путях flow/design — предпочитайте инструменты времени проектирования (get_integration_auto, summarize_*) прямым запросам к путям; они сами обрабатывают разрешение версий и особенности известных конечных точек.

• Большие или медленные ответы — суживайте выборку с помощью list_integrations_search / search_integration_by_name и пагинации (perPage, maxPages) вместо загрузки полных каталогов.

• Проверка состояния здоровья — GET /healthz возвращает {"status": "ok" }, когда сам процесс запущен (отдельную связность с OIC не проверяет).

Лицензия

MIT