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セッションの初期化が機能していること

• プロトコルのフレーミングが正しいこと

• サーバーがツールを正しく公開していること

• 少なくとも1つのパブリックツール呼び出しがエンドツーエンドで機能すること

認証に関する重要な注意点

保護された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ベアラートークン用に設計されています。

つまり、一般的なデプロイメントには 2つの異なる認証層 が存在します:

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クライアントと最小限のスコープを使用してください

• 定期的に認証情報をローテーションし、ログを確認してください