OIC Monitoring MCP Server

Oracle Integration Cloud(OIC)용 읽기 전용 MCP 서버입니다. MCP 클라이언트(Claude Code 등)를 연결하고, 통합, 연결, 런타임 인스턴스, 오류, 플로 로그에 대해 자연어로 질문하면, 서버가 이를 OIC REST API 호출로 변환하여 깔끄한 LLM 친화적인 JSON을 돌려줍니다.

FastAPI + WebSocket으로 구성되었으며, OAuth2 Client Credentials(IDCS/IAM)로 인증합니다.

목차

• 요구 사항

• 설치: Windows, macOS, Linux

• 구성

• MCP 클라이언트 연결

• 단일 코드베이스로 여러 환경 실행

• 서버 계속 실행하기

  • [옵션 A: 세션 전용](#option-a-session-only dies when you close the terminal)

  • 옵션 B: 상주 백그라운드 서비스

• 도구

• 응답 형식

• 동작 원리

• 프로덕션 보안 강화

• 문제 해결

요구 사항

디스크 사용량은 작습니다. 가상 환경은 약 120MB이며, 로그는 총 약 60MB로 제한됩니다.

설치

모든 플랫폼에서 흐름은 동일합니다:

1. Python 3.10 이상 설치

2. 코드 받기

3. 가상 환경 생성 및 의존성 설치

4. .env 생성 및 작성

5. 서버 시작 및 확인

플랫폼별로 다른 것은 1단계와 가상 환경 활성화 명령뿐입니다.

Windows

1. Python 설치

가장 쉬운 방법은 PowerShell에서 winget을 사용하는 것입니다:

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

또는 python.org/downloads/windows에서 설치 관리자를 내려받습니다. 설치 관리자를 사용한다면 첫 화면에서 **"Add python.exe to PATH"**를 체크하세요. 이 체크 하나가 나중에 "python이(가) 인식되지 않습니다" 문제의 대부분의 원인입니다.

PowerShell을 닫고 다시 연 다음 확인합니다:

py -3 --version

Python 3.10.x 이상이 표시되어야 합니다. py 런처는 공식 설치 관리자와 함께 제공되며 Windows에서 Python을 호출하는 가장 안정적인 방법이므로, 아래 명령에서는 py를 사용합니다.

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를 사용하시나요? .venv\Scripts\activate.bat로 활성화하세요.

4. 설정

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

설정에 설명된 값을 입력합니다.

5. 서버 시작

.\scripts\run-local.ps1

macOS

1. Python 설치

macOS에는 시스템 Python이 함께 제공되지만, 이에 맞춰 빌드하지 않는 것이 좋습니다. Homebrew로 직접 설치하세요:

brew install python@3.12

그런 다음 확인합니다:

python3 --version

Homebrew가 없나요? 먼저 설치하거나, python.org/downloads/macos에서 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

Debian 계열 배포판에서는 python3-venv 패키지가 분리되어 있어 놓치기 쉽습니다. 이 패키지가 없으면 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 미만인 경우(예: 3.6을 포함하는 RHEL 8), 시스템 Python과 함께 최신 인터프리터(python3.11 또는 AppStream이나 deadsnakes의 python3.12)를 설치하고, 가상 환경을 만들 때 해당 명시적 바이너리를 사용하세요(예: 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

대략 40개의 도구가 있는 JSON 목록을 받아야 합니다. WebSocket 클라이언트가 필요 없는 일반 HTTP 상태 확인도 있습니다:

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

연결 오류 또는 401이 나타나면 문제 해결로 이동하세요.

호스트주소스 및 포트 변경

run-local.sh과 run-local.ps1은 둘 다 PORT 변수를 읽으며, 다른 지시가 없으면 루프백에만 바인딩합니다:

# 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와 방화벽 뒤에서만 수행하세요. 프로덕션 Security 참조.

설정 (.env)

.env.example을 .env로 복사하고 작성하세요:

기밀 애플리케션의 클라이언트에는 IDCS/IAM의 OIC 인스턴스 리소스 앱에 ServiceUser 애플리케이션 역할이 지정되어 있어야 합니다(클라이언트 엡 자체가 아니에). 그렇지 않으면 .env와 유효한 토큰이 있어도 모든 호출이 401 -만에 -2322 - ...I notice the previous response got cut off and had issues. Let me now provide a complete, careful translation as the final output.

The final response should be the full translation. Let me re-issue complete.# OIC Monitoring MCP Server

Oracle Integration Cloud(OIC)용 읽기 전용 MCP 서버입니다. MCP 클라이언트(Claude Code 등)를 이 서버에 연결하고, 인테그레이션, 연결, 런타임 인스턴스, 오류, 플로우 로그에 대해 자연어로 질문하세요. 서버는 그 질문을 OIC REST API 호출로 변환하고, 깔끄하면서 LLM 친화적인 JSON을 반환합니다.

FastAPI + WebSocket 기반으로, OAuth2 Client Credentials(IDCS/IAM) 방식으로 인증합니다.

목차

• 요구 실행

• 설치: Windows, macOS, Linux

• 환경 설정

• MCP 클라이언트 연결

• 하나의 코드로 여러 환경 운영

• 서버 계속 실행

  • [옵션 A: 세션 유지](#option-a-session-only dies when you close the terminal)

  • [옵션 B: 상ाह주 서비스](#option-b-permanent-back background-service-survives-reboot)

• 도구

• 응답 형식

• 작동 방식

• 운영 보안다

• 문제 해결

요구 사항

디스크 사용량은 작습니다. 가상환경은 약 120MB, 로그는 총 약 60MB로 제한됩니다.

설치

설치 절차는 모든 플랫폼에서 같습니다.

1. Python 3.10+

2. 코드 확보

3. 가상 환경 만들고 의조건성 설치

4. .env 만들고 채우기

5. 서버 시작하고 확인

플랫폼별로 다른 것은 1번 단계28와 가상환경 활성화 명령뿐입니다.

Windows

1. Python 설치

가장 정간단한 방법은 PowerShell에서 winget입니다:

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

또는 다운다운로더더: python.org/downloads/windows. 설치 관리자를 쓰면 첫 화면에서 **"Add python.exe to PATH"**를 선택하세요. 그 한 개 체크박스가 나중에 대부분의 "python이(가) 인식되지 않습니다" 문제의 원인입니다.

PowerShell을을 닫고 다시 열고 확인:

py -3 --version

Python 3.10.x 또는 그 이상 나타나야 합니다. py 론처는 한 정식 설치 관리자 포함되어, Windows에서 Python 실행 때 가장 안정적입니다.

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이 스크립트 사용(script execution)를 차단했으며 - "running scripts is disabled" 오류 - 밀면, 사용자 자격 실행권한 한 번 허:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

PowerShell 대신 cmd.exe를 쓴다면 .venv\Scripts\activate.bat로 진행하세요.

4. 환경 설정

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

Configuration의값을 입력합니다.

5. 서버 시작

.\scripts\run-local.ps1

macOS

1. Python 설치

macOS에는 기본 Python가 내장되어 있지만 그걸로 프로젝트를 구성하지 마세요. Homebrew 설치:

brew install python@3.12

그 다음 확인:

python3 --version

Homebrew를ivities? Homebrew를 먼저 사용하거나 python.org/downloads/macos에서 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. 환경 .env

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

Debian 계열에서는 python3-venv 개가 별도 패키지로 분리되어 있어 놓치기 쉽습니다. 이것이 없으면 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에 포함된 3.6), 시스템 기본 파이썬과는 별도의 새 버전을 설치(python3. 11 or python3.12 AppStream or deadsnakes)한다. 그 binary로 가상환경을 만드세요(예: 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

약 40여 개 도구의 JSON 목록을 받게 됩니다. 별도 WebSocket 클라이언트가 필요 없는 HTTP 상태 확인이 있습니다:

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

연결 오류나 401이 나오면 [Troubleshooring]을 확인하세요.

호스트 및 포트 변경

run-local.sh 그리고 run-local.ps1 실행은 PORT 변수를 사용하며, 다른 지시가 없으면 오로 루프백 주소에만 바인딩합니다:

# 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와 방화벽 뒤에서만 사용하세요. Production hardening 참조.

Configuration (.환경)

환경설정:

.env.example을 .env로 복사하고 채워 넣습니다:

OAuth 기밀 앱에 ServiceUser 역할이 OIC 인스턴스 리소스 앱에 할당되어 있지 않으면(클라이언트 앱 자체가 아니라 리소스 앱에), 토큰이 유효해도 요청이 401에 됩니다.

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 전송만 지원합니다. "type": "stdio" 또는 하위 명령 형태는 사용할 수 없습니다. 먼저 서버를 프로세스로 실행한 다음 URL을 클라이언트에 지정하세요.

연결된 뒤 에이전트에게 "활성화된 통합 목록", "지난 20개 런타임 인스턴스 보기" 등으로 질문하세요.

여러 환경을 한 코드로 운영하기

하나의 소스에서 Dev/Test/Prod 각각 별도의 프로세스를 띄울 수 있습니다. 각 프로세스는 OIC_ENV_FILE 환경변수로 서로 다른 env 파일을 지정합니다.

mcp_server.settings.py 는 시작 시 OIC_ENV_FILE을 읽어 .env를 대신합니다.

1. 환경별 env 파일 만들기

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

2. 환경별 프로세스 시작, 각각 다른 포트

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

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

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

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은 시작 시 한 번만 읽힙니다. 변경 시 재시작 필요.

• OS 환경 변수가 파일보다 우선합니다. OIC_BASE_URL을 셸 프로필에 넣으면 모든 프로세스에 적용됩니다.

• 각 프로세스는 고유 포트를 사용해야 합니다.

• Docker에서는 --env-file로 전달하므로 별도 파일을 사용하지 않아도 됩니다.

• 이 서버의 모든 도구는 읽기 전용입니다. 각 환경에 필요한 최소 권한을 주세요.

서버 유지

로그아웃할 때 동작이 다르므로, 의도에 맞게 두 패턴 중 하나를 사용하세요.

Option 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가 충돌 후 다시 시작되도록 합니다. 둘 다 필요합니다.

로그는 저널(journal)로 전송됩니다:

journalctl -u oic-mcp -f

두 번째 환경의 경우 유닛 파일을 oic-mcp-test.service로 복사하고 Environment=OIC_ENV_FILE= 줄과 --port를 변경한 후 sudo systemctl enable --now oic-mcp-test를 실행하세요.

자신의 사용자로 실행하는 것을 선호하나요? 동일한 유닛 파일을 ~/.config/systemd/user/oic-mcp.service에 두고, systemctl --user enable --now oic-mcp로 활성화한 뒤, 첫 로그인 시가 아니라 부팅 시 시작되도록 sudo loginctl enable-linger $USER를 실행하세요.

macOS (launchd)

/Users/you/oic-mcp를 실제 경로로 바꾸고 ~/Library/LaunchAgents/com.oic.mcp.plist를 생성합니다:

<?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

~/Library/LaunchAgents의 LaunchAgent는 사용자가 로그인할 때 시작됩니다. 머신이 로그인 전에 엔드포인트를 제공해야 한다면 동일한 plist를 /Library/LaunchDaemons/에 두고(root:wheel 소유, 모드 644), root로 실행되지 않도록 UserName 키를 추가한 뒤 sudo launchctl bootstrap system /Library/LaunchDaemons/com.oic.mcp.plist로 로드하세요.

두 번째 환경의 경우 새 Label(com.oic.mcp.test), 다른 포트, 다른 OIC_ENV_FILE을 사용해 plist를 복제하세요.

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"

이 방법은 부팅 시 시작되지만 기본적으로 충돌 시 재시작하지 않습니다. 작업의 설정 탭에 있는 "If the task fails, restart every 1 minute"을 최대 3회로 추가하세요. NSSM이 이 부분을 더 잘 처리하므로 권장되는 옵션입니다.

Docker(모든 플랫폼)

restart 정책은 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 - 통합 zip 파일을 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 - 위 항목과 선택된 단계의 I/O 요약을 포함

• summarize_flow_controls - Switch/ForEach/Route/Fault/Scope 구문의 수와 샘플 반환

• summarize_mappings - mapping 단계 추출

• deep_flow_outline - 전체 흐름의 간결한 텍스트 개요

• get_integration_step - stepName(정확 + 퍼지)과 일치하는 원본 JSON 하위 트리(들) 및 일치하는 엔드포인트

• summarize_step_io - stepName에 대해 의심되는 SQL/쿼리 스니펫 및 매개 변수를 반환하고, 단계가 없을 경우 엔드포인트 일치로 폴백

유틸리티

• fetch_raw_path - 임의 OIC 경로 가져오기

• search_json - 모든 JSON 유사 구조에 대해 부분 문자열 검색

디자인-타임 도구는 선택적으로 designJsonPath를 사용해가전에 다운로드 한 디자인 JSON을 디시스크에서 읽을 수 있습니다. 은 OIC를호출하지 않으므로 온라인 분석이나 반복적 호출을 피할 때 유용합니다.

응답 형식

모든 tools/call 결과는 {"content": [{"type": "text", "text": "<json-or-plain-text>"}], "isError": false}와 같은 MCP스펙 봉투 형태를따라옵니다. 실제 도구 페이로드는 text 내부에 직렬화된 JSON입니다. 구조화된 데이터를 얻으려면 한 번더 파싱하세요:

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 를 사용해 동일한 경로로 오는 것을 볼수 있습니다. 성공으로 가정하지 말고 그 플래그를 확인하세요. 진정한 프로토콜 오류(알 수 없는 메서드, 알 수 없는 도구 이름)는 실제 JSON-RPC error 객체를 반환합니다. 큰 페이로드는 100,000 문자2자에서 잘리며, 잘릴 때는 - truncation 되고 [TRUNCATED ...]로 표시되므로 체분 재리되지 않습니다.

동작 원리

• 서버는 JSON-RPC 2.0 / MCP를 말하는 하나의 WebSocket 엔드포인트를 노출합니다. 클라이언트는 tools/list로 도구를 발견하고 tools/call로 이를 호출합니다.

• 각 호출마다 인증된 httpx.AsyncClient로 OIC의 REST API에서 데이터베이스를 가져옵니다. OAuth 토큰은 캐시되어 유효성이 만료되면 자동으로 갱신됩니다.

• WebSocket 핸드셰이크에서 클라이언트가 요청할 때 mcp이 서브프로토콜로 협상되며, initialize는 사양에 맞는 protocolVersion과 객체 타입의 capabilities를 반환합니다. 이는 테스트한 클라이언트(예: Claude Code)가 연결을 수락하기 위해 필수입니다.

• 리디렉션은 httpx의 내장 처리를 사용하지 않고 수동으로 처리합니다. OIC의 디자인 타임 게이트웨이는 307 리디렉트를 OIC_BASE_URL과 다른 호스트로 반환하며, httpx는 기본적으로 다른 호스트로 리디렉트 시 Authorization 헤더를 제거합니다. 수동 처리하면 이 알려진 신뢰할 수 있는 hop에서 헤더를 보존합니다.

로깅

로그는 mcp_server.log(숨김은 MCP_LOG_FILE로 재정의)에 기록되며, 파일당 10MB마다 자동으로 로테이션되고 5개 백업(약 60MB 한도)을 유지합니다. 따라서 크기가 무한정 커지지 않습니다. 어떤 플랫폼에서든 logrotate, cron, sudo가 필요 없으며, 앱이 매 쓰기 시 자체적으로 로그 크기를 관리합니다.

환경당 하나의 프로세스를 실행할 때, 로그가 분리하여 유지되도록 각 env 파일에 고유한 MCP_LOG_FILE을 설정하세요.

운영 환경 강화

• TLS 후단(예: Nginx/Traefik같은 리버스 프록시)에서 실행하고 네트워크 접근을 제한하세요. WebSocket 엔드포인트에는 자체 인증이 없으므로 신뢰할 수 없는 네트워크에 직접 노출하지 마세요.

• 특별한 이유가 없으면 bind 주소를 127.0.0.1에 고정하세요.

• 비밀 값을 볼트(vault)에 저장하고 .env를 커밋하지 마세요. Linux에서는 env 파일을 chmod 600으로 설정하고 서비스 사용자가 소유하세요.

• OAuth 클라이언트에 최소한의 필요한 역할만 부여하세요(ServiceUser는 읽기 권한 수준이고, create/import 도구를 특별히 필요하지 않다면 ServiceDeveloper는 피하세요).

• 재부팅 후에도 유지되도록 프로세스 관리자(systemd, launchd, NSSM)를 사용하세요. Option B 내용 보기.

• 큰 카탈로그에서는 페이로드 크기에 주의하세요. 전체 목록을 가져오기보다 list_integrations_search를 세밀한 검색어와 페이지네이션으로 사용하세요.

문제 해결

설치 및 시작

• python or py not recognized (Windows) - Python 설치 시 "Add python.exe to PATH" 옵션이 선택되지 않았습니다. 설치 프로그램을 다시 실행하고 Modify(변경)를 선택하여 옵션을 켜거나 winget install -e --id Python.Python.3.12로 재설치하세요. 완료 후 새 터미널을 엽니다.

• running scripts is disabled on this system (Windows) - PowerShell 실행 정책이 가상 환경 활성화를 막고 있습니다. Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned를 실행하거나 cmd.exe에서 .venv\Scripts\activate.bat을 사용하세요.

• ensurepip is not available (Debian/Ubuntu) - 별도 venv 패키지 sudo apt install python3-venv을 설치하세요.

• TypeError: unsupported operand type(s) for | - Python 3.9 이하를 사용하고 있습니다. 3.10 이상을 설치하고 그 인터프리터로 가상 환경을 다시 만드세요.

• ValidationError on startup naming OIC_BASE_URL or OAUTH_* - env 파일이 없거나 불완전합니다. .env.example을 .env로 복사했는지, 프로젝트 디렉터리에서 프로세스를 시작했는지, OIC_ENV_FILE(설정되어 있는 경우)이 존재하는 파일을 가리키는지 확인하세요.

• address already in use - 포트를 사용 중인 프로세스가 있습니다. lsof -i :8085(Linux/macOS) 또는 netstat -ano | findstr :8085(Windows)로 확인하거나 다른 PORT로 시작하세요.

인증

• 토큰 URL에서 401/403 - OAUTH_CLIENT_ID/OAUTH_CLIENT_SECRET 및 OAUTH_TOKEN_URL이 IDCS/IAM 도메인에 맞는지 확인하세요.

• 토큰 요청은 성공(200)하지만 OIC에서 여전히 401 - 이것은 토큰이 잘못된 것이 아니라 거의 항상 IDCS IDCS 역할이 누락된 것입니다. OCI Console → Identity & Security → Domains → 해당 domain에서 OIC 인스턴스 자체의 resource app(본인의 비밀 클라이언트 앱 아님) → Application roles → ServiceUser → 당신의 비밀 클라이언트 앱을 application으로 추가하세요. 추가 후 새 토큰을 얻으세요 - 기존 토큰에는 추가된 역할이 소급 적용되지 않습니다.

연결

• 연결 거부 / WebSocket에 연결할 수 없음 - 서버 프로세스가 실제로 실행 중인지(pgrep -af mcp_server.main, systemctl status oic-mcp, 또는 Get-Service OicMcp)와 같은 포트에 다른 프로세스가 바인딩되어 있지 않은지 확인하세요. curl http://127.0.0.1:8085/healthz가 가장 빠른 확인 방법입니다.

• Claude Code에 서버가 "아직 연결 중"으로 표시되거나 해당 도구가 로드되지 않음 - 서버는 클라이언트 세션을 시작하기 전에 이미 실행 중이어야 하며, 실행 중이 아니면 자동으로 재시도되지 않습니다. 서버 상태를 확인한 후 클라이언트를 다시 시작하세요.

• 잘못된 환경의 데이터가 반환됨 - 실제 OS 환경 변수가 env 파일보다 우선 적용되어 env 파일을 덮어쓰고 있기 때문입니다. env | grep OIC_(Windows) 또는 Get-ChildItem Env:OIC_*(Windows)로 확인하고, 로 프로파일에서 오래된 항목을 제거하세요.

도구 사용

• 특정 플로우/디자인 경로에서 404 발생 - 제품 버전 해석과 알려진 엔드포인트 특이 사항을 직접 처리하지 않아도 되도록, 원시 경로 조회보다는 디자인 타임 도구(get_integration_auto, summarize_*)를 사용하세요.

• 크거나 느린 응답 - 전체 카탈로그를 가져오는 대신 list_integrations_search/search_integration_by_name과 페이지네이션(perPage, maxPages)으로 범위를 좁히세요.

• 상태 확인 - GET /healthz는 프로세스 자체가 실행 중일 때 {"status": "ok"}를 반환합니다(OIC 연결 상태는 확인하지 않습니다).

라이선스

MIT