SentinelX Core를 위한 MCP/OAuth 브리지. 서버 에이전트를 OIDC 토큰 검증이 포함된 MCP 도구로 노출합니다.
SentinelX Core MCP는 MCP 클라이언트(Claude, ChatGPT, Cursor 또는 기타 MCP 호환 에이전트)와 실행 중인 SentinelX Core 인스턴스 사이에서 작동합니다. 들어오는 OAuth Bearer 토큰을 JWKS 엔드포인트에 대해 검증한 다음, 도구 호출을 업스트림 에이전트로 전달합니다.
Claude / ChatGPT / Cursor / any MCP client
│
│ MCP + OAuth Bearer token
▼
sentinelx-core-mcp (public, port 8098)
│ validates token via OIDC/JWKS
│ HTTP + internal Bearer token
▼
sentinelx-core (local only, port 8091)
│
└─ command allowlist, structured editing, uploads, services두 개의 독립적인 인증 계층:
계층 | 검증 방식 | 토큰 유형 |
외부 (MCP) | OIDC/JWKS를 통한 | OAuth 액세스 토큰 (ID 제공업체에서 발급) |
내부 (에이전트) |
| 정적 Bearer 토큰 ( |
Related MCP server: mcp_sdk_eyra_accelerator_v19
도구 | 기능 | 필수 스코프 |
| 상태 확인 | public |
| 에이전트 런타임 상태 |
|
| 허용된 명령 실행 |
|
| 서비스 작업 (시작/중지/재시작/리로드/상태) |
|
| 등록된 서비스 재시작 |
|
| 구조화된 파일 편집 (쉘 인용 없음) |
|
| 대용량 편집 업로드 초기화 |
|
| 편집할 역할 파일 업로드 |
|
| 대용량 편집 완료 |
|
| 파일 업로드 (URL 또는 base64) |
|
| 청크 단위 업로드 초기화 |
|
| 청크 하나 업로드 |
|
| 청크 단위 업로드 완료 |
|
| 임시 bash/python3 스크립트 실행 |
|
| 허용된 명령, 서비스, 위치, 플레이북 |
|
| 에이전트 내장 도움말 |
|
실행 중인 SentinelX Core 인스턴스
OIDC 호환 ID 제공업체 (Keycloak, Auth0, Authentik, Zitadel 또는 JWKS 엔드포인트가 있는 모든 제공업체)
Python 3.11 이상
git clone https://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=your_internal_agent_token
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재시작 및 확인:
sudo systemctl restart sentinelx-core-mcp
sudo systemctl status sentinelx-core-mcp
sudo journalctl -u sentinelx-core-mcp -n 50 --no-pagerpython3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./run.sh로컬 기본값:
MCP 포트: 8099
업스트림 SentinelX Core: http://127.0.0.1:8092
경로 | 내용 |
| 애플리케이션 코드 |
| 환경 구성 |
| 로그 |
| systemd 유닛 |
/mcp의 MCP 엔드포인트는 HTTPS를 통해 노출되어야 합니다. Nginx 구성 예시:
server {
listen 443 ssl http2;
server_name sentinelx.example.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location = /mcp {
proxy_pass http://127.0.0.1:8098/mcp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 3600s;
add_header Cache-Control "no-cache";
}
}Claude 설정에 MCP 서버를 추가합니다:
https://sentinelx.example.com/mcpClaude는 처음 사용할 때 OAuth 로그인을 요청합니다. 인증 후에는 토큰의 스코프가 허용하는 모든 도구에 액세스할 수 있습니다.
MCP 서버 URL을 GPT Action으로 등록하거나 ChatGPT 커넥터 구성에 추가합니다. OAuth 흐름은 Authorization Code 흐름을 지원하는 모든 OIDC 제공업체와 작동합니다.
MCP 엔드포인트는 HTTP 기반의 JSON-RPC를 사용합니다. 최소 세션:
SESSION=$(curl -si -X POST https://sentinelx.example.com/mcp \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0","id":"1","method":"initialize",
"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}
}' | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r')curl -s -X POST https://sentinelx.example.com/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: $SESSION" \
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}'curl -s -X POST https://sentinelx.example.com/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: $SESSION" \
-d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"ping","arguments":{}}}' \
| sed -n 's/^data: //p' | jqcurl -s -X POST https://sentinelx.example.com/mcp \
-H "Content-Type: application/json" \
-H "mcp-session-id: $SESSION" \
-H "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN" \
-d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"sentinel_exec","arguments":{"cmd":"uptime"}}}' \
| sed -n 's/^data: //p' | jqOIDC 호환 제공업체라면 무엇이든 가능합니다: Keycloak, Auth0, Authentik, Zitadel 등. 다음이 필요합니다:
Authorization Code 흐름(대화형) 또는 Client Credentials(기계 간)로 구성된 클라이언트
노출하려는 도구와 일치하는 사용자 지정 스코프 (sentinelx:exec, sentinelx:edit 등)
제공업체의 JWKS URI
Claude 및 ChatGPT의 경우: 클라이언트에 등록된 올바른 리다이렉트 URI
env 파일에 다음을 설정합니다:
OIDC_ISSUER=https://your-provider.example.com/realms/your-realm
OIDC_JWKS_URI=https://your-provider.example.com/realms/your-realm/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE= # set to your client ID, or leave empty to skip audience validationOIDC_EXPECTED_AUDIENCE 정보제공업체가 aud 클레임에 클라이언트 ID를 포함하는 경우(기밀 클라이언트에서 흔함) 클라이언트 ID로 설정하세요.
확실하지 않으면 비워두세요 — 서버가 대상(audience) 검증을 건너뜁니다.
토큰이 거부되면 토큰을 디코딩(echo $TOKEN | cut -d. -f2 | base64 -d | jq)하여 aud 클레임을 확인하세요.
Claude 설정에 MCP 서버를 추가합니다:
https://sentinelx.example.com/mcpClaude는 처음 사용할 때 ID 제공업체로 리다이렉트합니다. 다음을 확인하세요:
리다이렉트 URI https://claude.ai/api/mcp/auth_callback이 OIDC 클라이언트에 등록되어 있어야 합니다.
서버가 올바른 authorization_servers 값을 가진 /.well-known/oauth-protected-resource를 노출해야 합니다.
MCP URL을 GPT Action으로 등록합니다. 클라이언트의 리다이렉트 URI에 https://chatgpt.com/aip/g-*/oauth/callback을 추가하세요.
토큰 획득, Claude 설정, 스모크 테스트 및 문제 해결을 포함한 Keycloak 전체 가이드는 docs/keycloak-example.md를 참조하세요.
Keycloak을 사용하지 않나요? Authentik, Zitadel 및 Zitadel Cloud에 대한 빠른 시작 가이드는 docs/oidc-alternatives.md를 참조하세요.
도구 실행 시 Missing Authorization header 오류 발생
MCP 클라이언트가 OAuth 토큰을 보내지 않는 것입니다. 인증 흐름이 성공적으로 완료되었는지 확인하세요.
Invalid access token
OIDC_ISSUER와 OIDC_JWKS_URI가 ID 제공업체와 정확히 일치하는지 확인하세요. 로그에서 토큰 검증 세부 정보를 보려면 일시적으로 AUTH_DEBUG=true를 활성화하세요.
Missing required scope
토큰에 해당 도구에 필요한 스코프가 포함되어 있지 않습니다. OIDC 클라이언트 구성에 스코프를 추가하고 다시 인증하세요.
ping은 작동하지만 다른 모든 도구가 실패함
보통 인증 문제입니다. ping은 공개 도구이며, 다른 모든 도구는 올바른 스코프가 포함된 유효한 토큰이 필요합니다.
MCP가 시작되지만 SentinelX Core에 연결할 수 없음
SENTINELX_URL이 실행 중인 코어 인스턴스를 가리키고 있는지, SENTINELX_TOKEN이 코어의 SENTINEL_TOKEN과 일치하는지 확인하세요.
MCP 서비스를 HTTPS 및 리버스 프록시 뒤에 두세요.
필요한 스코프만 있는 전용 OIDC 클라이언트를 사용하세요.
SENTINELX_TOKEN 및 OIDC 클라이언트 자격 증명을 주기적으로 교체하세요.
실행 감사 로그(/var/log/sentinelx/exec.log)를 정기적으로 검토하세요.
AUTH_DEBUG=true는 토큰 클레임을 로그에 남기므로 프로덕션 환경에서는 비활성화하세요.
sentinelx-core — 기본 HTTP 에이전트: 명령 실행, 구조화된 편집, 업로드 및 서비스 관리.
MIT
This server cannot be deployed
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
The Stytch MCP server is a reference implementation that demonstrates remote MCP server authentication and authorization using Stytch Connected Apps. It provides OAuth 2.1-compliant authorization (including PKCE), Dynamic Client Registration, and validates Stytch-issued access tokens to enable AI agents to securely interact with external services through permissioned access, supporting scopes like openid, email, profile, and manage:project_data.
