SentinelX Core MCP

실행 중인 SentinelX Core 인스턴스로 도구 호출을 프록시하는 MCP 서버입니다.

이 저장소는 이식 가능한 MCP/OAuth 브리지 계층입니다. 기본 HTTP 에이전트를 제공하는 sentinelx-core와는 별도로 유지되도록 설계되었습니다.

기능

• SentinelX Core가 지원하는 MCP 도구 노출

• OIDC/JWKS를 통한 베어러 토큰 검증

• 업스트림 SentinelX Core API로 도구 호출 전달

• MCP 통합을 위한 별도의 제품 경계 추가

SentinelX Core에 대한 의존성

이 프로젝트는 실행 중인 SentinelX Core 인스턴스가 필요합니다.

일반적인 로컬 개발 페어링:

• SentinelX Core: http://127.0.0.1:8092

• SentinelX Core MCP: http://127.0.0.1:8099

일반적인 설치 페어링 예시:

• SentinelX Core: http://127.0.0.1:8091

• SentinelX Core MCP: http://127.0.0.1:8098

이는 예시 기본값이며, 사용 가능한 포트가 보장되지 않습니다. /etc/sentinelx/sentinelx.env 및 /etc/sentinelx-core-mcp/sentinelx-core-mcp.env에 구성된 실제 값을 항상 확인하십시오.

빠른 시작

git clone git@github.com:pensados/sentinelx-core-mcp.git
cd sentinelx-core-mcp
sudo bash install.sh

그런 다음 편집:

sudo nano /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

최소한 다음을 설정:

MCP_PORT=8098
SENTINELX_URL=http://127.0.0.1:8091
SENTINELX_TOKEN=changeme
OIDC_ISSUER=https://auth.example.com/realms/sentinelx
OIDC_JWKS_URI=https://auth.example.com/realms/sentinelx/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE=
RESOURCE_URL=https://sentinelx.example.com
AUTH_DEBUG=false
LOG_DIR=/var/log/sentinelx-mcp
LOG_FILE=/var/log/sentinelx-mcp/sentinelx-core-mcp.log

재시작 및 확인:

sudo systemctl restart sentinelx-core-mcp
sudo systemctl status sentinelx-core-mcp
sudo journalctl -u sentinelx-core-mcp -n 100 --no-pager

로컬 개발

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./run.sh

로컬 개발 기본값:

• MCP 포트: 8099

• 업스트림 SentinelX Core URL: http://127.0.0.1:8092

수동 MCP 스모크 테스트

MCP 엔드포인트는 일반 REST 엔드포인트가 아닙니다. curl을 사용한 최소한의 수동 테스트 요구 사항:

1. 세션 초기화

2. notifications/initialized 전송

3. tools/list 또는 ping과 같은 공개 도구 호출

1. 세션 초기화

curl -i -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":"init-1",
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{
        "name":"curl",
        "version":"0.1"
      }
    }
  }'

이 작업은 200 OK와 다음과 같은 응답 헤더를 반환해야 합니다:

mcp-session-id: ...

2. 초기화 알림

TU_SESSION_ID를 서버에서 반환된 실제 값으로 바꿉니다:

curl -i -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "method":"notifications/initialized"
  }'

이 작업은 202 Accepted를 반환해야 합니다.

3. 도구 목록 확인

응답이 SSE(event: message + data: ...)로 전달되므로, jq로 파이핑하기 전에 data: 접두사를 제거하십시오:

curl -s -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "id":"tools-1",
    "method":"tools/list",
    "params":{}
  }' | sed -n 's/^data: //p' | jq

4. 공개 ping 도구 호출

curl -s -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "id":"call-1",
    "method":"tools/call",
    "params":{
      "name":"ping",
      "arguments":{}
    }
  }' | sed -n 's/^data: //p' | jq

검증 내용

이 수동 테스트는 다음을 검증합니다:

• MCP 서버가 수신 대기 중인지 여부

• MCP 세션 초기화가 작동하는지 여부

• 프로토콜 프레이밍이 올바른지 여부

• 서버가 도구를 올바르게 노출하는지 여부

• 최소한 하나의 공개 도구 호출이 종단 간 작동하는지 여부

중요한 인증 참고 사항

보호된 MCP 도구는 여전히 MCP 계층에서 허용하는 실제 OAuth/OIDC 액세스 토큰이 필요합니다.

내부 SentinelX Core 토큰은 외부 MCP 액세스 토큰과 동일하지 않습니다.

설치 경로

• 코드: /opt/sentinelx-core-mcp

• 환경 파일: /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

• 로그: /var/log/sentinelx-mcp

• 서비스: sentinelx-core-mcp.service

구성

설치된 환경 파일 예시:

MCP_PORT=8098
MCP_TOKEN=
SENTINELX_URL=http://127.0.0.1:8091
SENTINELX_TOKEN=changeme
OIDC_ISSUER=https://auth.example.com/realms/sentinelx
OIDC_JWKS_URI=https://auth.example.com/realms/sentinelx/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE=
RESOURCE_URL=https://sentinelx.example.com
AUTH_DEBUG=false
LOG_DIR=/var/log/sentinelx-mcp
LOG_FILE=/var/log/sentinelx-mcp/sentinelx-core-mcp.log

인증 관련 참고 사항

• 보호된 도구는 베어러 토큰이 필요합니다.

• 토큰은 구성된 JWKS 엔드포인트에 대해 검증됩니다.

• 업스트림 SentinelX Core는 자체 내부 베어러 토큰 및 허용 목록을 계속 적용합니다.

• Keycloak은 권장되는 테스트 완료 옵션이지만, 유일한 선택지는 아닙니다.

• 유효한 발급자 및 JWKS 엔드포인트를 노출하는 모든 호환 OIDC 공급자가 작동해야 합니다.

인증 모델

SentinelX Core MCP는 MCP 계층에서 OIDC/OAuth 베어러 토큰을 사용하도록 설계되었습니다.

즉, 일반적인 배포에는 두 가지 다른 인증 계층이 있습니다:

1. 외부 MCP 인증

   • sentinelx-core-mcp에 의해 검증됨

   • OIDC_ISSUER, OIDC_JWKS_URI 및 선택적 OIDC_EXPECTED_AUDIENCE 기반

   • ChatGPT 또는 기타 MCP 소비자와 같은 MCP 클라이언트를 위한 것

2. 내부 SentinelX Core 인증

   • sentinelx-core에 의해 검증됨

   • SENTINELX_TOKEN 기반

   • MCP 브리지가 업스트림으로 요청을 전달할 때만 사용됨

권장 사항

프로덕션 환경과 유사한 배포를 위해서는 실제 OIDC 공급자를 사용하십시오.

Keycloak은 잘 알려져 있고 이 프로젝트의 원래 참조로 사용되었기 때문에 좋은 참조 구현입니다. 그러나 저장소는 이식 가능해야 하므로, 문서는 Keycloak을 필수 의존성이 아닌 예시로 취급합니다.

시작하기

• 일반적인 개요는 이 README를 참조하십시오.

• 구체적인 Keycloak 가이드는 docs/keycloak-example.md를 참조하십시오.

문제 해결

MCP는 시작되지만 도구가 실패하는 경우

확인 사항:

• SENTINELX_URL이 실행 중인 SentinelX Core를 가리키는지 확인

• SENTINELX_TOKEN이 업스트림 코어와 일치하는지 확인

• OIDC 발급자 및 JWKS URI가 올바른지 확인

• 토큰이 MCP 계층에서 예상하는 범위를 가지고 있는지 확인

업스트림 코어 직접 확인

curl -s -H "Authorization: Bearer changeme" http://127.0.0.1:TU_PUERTO_CORE/state | jq

보안 참고 사항

• 배포 환경에 적절하게 MCP 서비스를 바인딩하십시오.

• 가능하면 명시적인 프론팅 계층과 함께 로컬 전용 바인딩을 선호하십시오.

• 전용 OIDC 클라이언트와 최소한의 범위를 사용하십시오.

• 자격 증명을 주기적으로 교체하고 로그를 정기적으로 검토하십시오.