MCP（Model Context Protocol）

1. 概要

サーバー機能として、MCP（Model Context Protocol）に対応した機能を提供できます。

1.1. サーバー機能概要

メタデータを設定することで、MCP Tools 機能を提供することが可能です。

MCP Tools: Command として定義した機能を MCP クライアントから呼び出すことで利用することができます。

1.2. クライアント機能概要

MCP クライアントでは、サーバーで定義された機能を実行することができます。
サーバーの機能を利用するためには認証が必要であり、認証方法として、OAuth、個人アクセストークン（Bearer トークンによる認証）を利用することが可能です。

2. サーバーの設定

MCPサーバーを利用するための設定手順は以下の通りです。

iplass-ee-mcp モジュールの取り込み
web.xml へ mtp_mcp フラグメントの追加
Service Config の設定

2.1. iplass-ee-mcp モジュールの取り込み

MCPサーバーを利用するには、iplass-ee-mcp モジュールをプロジェクトに取り込む必要があります。

Gradle を利用している場合は、以下の依存関係を build.gradle に追加してください。

dependencies {
    runtimeOnly 'org.iplass.ee:iplass-ee-mcp' (1)
}

1	iplass-ee-bom で指定されているバージョンのモジュールを利用します。 iplass-ee-bom を利用しない場合は、明示的にバージョンを指定してください。

2.2. web.xml へ mtp_mcp フラグメントの追加

web.xml に mtp_mcp フラグメントを追加することで、MCPサーバーのリクエストを処理するための初期化処理が設定されます。
mtp_mcp フラグメントは、iplass-ee-mcp モジュールに含まれています。

web.xml 設定例（抜粋）

<web-app>
    <absolute-ordering>
        <name>mtp</name>
        :
        :
        <!-- mcp -->
        <name>mtp_mcp</name>
    </absolute-ordering>
    :
    :
</web-app>

2.3. Service Config の設定

Service Config 設定ファイルにMCPサーバーの設定を行います。
MCPサーバーの設定を行う際のポイントは以下の通りです。

mcp-service-config.xml を読み込む
McpService のプロパティ設定
- プロパティ enableMcp を true に設定する
- プロパティ tenantServerInfo に、有効化したいテナントのテナントID、サーバー名、バージョン情報を設定する
- 必要に応じて allowOrigin, allowHost プロパティを設定する。

<serviceDefinition>
    (1)
    <inherits>/mcp-service-config.xml</inherits>

    (2)
    <service>
        <interface>org.iplass.mtp.impl.mcp.McpService</interface>
        <class>org.iplass.mtp.impl.mcp.McpService</class>

        <!-- MCPサーバーの有効化 -->
        <property name="enableMcp" value="true" />

        <!-- テナントIDは環境に合わせて設定してください。 -->
        <!-- MCPサーバー利用テナント サーバー情報 -->
        <property name="tenantServerInfo" class="org.iplass.mtp.impl.mcp.McpServerInfo">
            <property name="tenantId" value="1" />
            <property name="serverName" value="tenant1-mcp" />
            <property name="version" value="1.0.0" />
        </property>
    </service>
</serviceDefinition>

1	mcp-service-config.xml の読み込み
2	McpService の設定。設定の詳細は Configuration - McpService を参照してください。

3. メタデータの設定

メタデータは AdminConsole で設定します。
AdminConsole メニューのパスは AI Integration > MCP です。

setup server setup metadata adminconsole menu

3.1. Tools メタデータの作成

Tools メタデータは、AdminConsole メニューの AI Integration > MCP > Tools で作成します。
設定項目は以下の通りです。

項目説明

有効

定義した MCP Tools を有効にするかどうかを設定します。

Tool名

名前を設定します。必須項目です。
クライアントから MCP Tools を呼び出す際に利用する項目です。

Toolタイトル

タイトルを設定します。クライアントから MCP Tools 一覧を取得した際に表示される項目です。

Tool説明

説明を設定します。クライアントから MCP Tools 一覧を取得した際に表示される項目です。

4. クライアントの設定

クライアントからMCPサーバーに接続するためには、リクエストするエンドポイントの指定と、認証情報の設定が必要です。

4.1. エンドポイント

クライアントから接続する場合のエンドポイントは、McpService で設定することが可能です。
McpService のプロパティ requestEndpoint にエンドポイントのパス（ /mcp/ から始まるパス）を設定してください。
McpService の詳細は Configuration - McpService を参照してください。

エンドポイントの設定値がデフォルト /mcp/message の場合、クライアントから接続する際のエンドポイントは以下のようになります。

(http|https)://<host><:port>/<context>/<tenant>/mcp/message

構成要素の説明

<host>: ホスト名
<:port>: ポート番号 (省略可能)
<context>: アプリケーションコンテキスト。サーバー構築時の設定により異なります。
<tenant>: テナント名。テナント構築時に設定したテナント名を指定します。

URL 例： https://example.com/iplass/tenant/mcp/message

4.2. 認証

MCPサーバーの利用にあたり、認証が必須となります。

サポートしている認証方法

OAuth 2.0 Bearer Token 認証

OAuth 2.0のアクセストークン。リクエストヘッダーの Authorization に Bearer トークンとして設定してください。

個人アクセストークン Bearer Token 認証

GEM(TopView) - アプリの管理を参照し個人アクセストークンを発行してください。
発行した個人アクセストークンは、リクエストヘッダーの Authorization に Bearer トークンとして設定してください。

認証情報の設定例

以下は、リクエストヘッダーの Authorization に Bearer トークンとして設定する例です。

Header 設定例

Authorization: Bearer <token>

5. 標準提供機能

5.1. メタデータCRUD

メタデータの操作（作成、読み取り、更新、削除）を行うための機能を、MCP Tool として提供します。

メタデータCRUD機能は、WebAPI のメタデータCRUDで利用しているコマンドを MCP Tool として提供するものです。
メタデータCRUD機能を利用するには、以下の設定が必要となります。

WebApiService の enableDefinitionApi プロパティの設定を行う必要があります。
詳細については、 Configuration - WebApiService を参照してください。
ツールを実行する利用者は、管理者としての権限が必要です。

メタデータCRUD機能は、開発時の利用を想定した機能です。

メタデータ取得

メタデータの定義の一覧や詳細を取得するための機能です。

ツール名

getDefinition

パラメータ
項目	説明
path	メタデータの定義のパスを設定します。`/` で終わる場合は一覧を取得します。それ以外の場合、定義が存在すればメタデータを取得します。
recursive	一覧取得時に利用します。true または false を設定します。 true が設定された場合、メタデータパス以下の階層を辿って一覧を取得します。

レスポンス（一覧取得の場合）
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。
list	指定されたパスのメタデータの一覧が返ります。

レスポンス（詳細取得の場合）
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。
definition	指定されたパスのメタデータの詳細が返ります。

メタデータ作成

メタデータの定義を新規に作成する機能です。
指定された path のメタデータを作成します。作成するメタデータの定義は definition で指定します。

ツール名

createDefinition

パラメータ
項目	説明
path	登録するメタデータのパスを設定します。必須項目です。
definition	登録するメタデータの定義を設定します。必須項目です。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。

メタデータ更新

メタデータの定義を更新する機能です。
指定された path のメタデータを更新します。更新するメタデータの定義は definition で指定します。
更新元のメタデータは、メタデータ取得で取得することを想定しています。

ツール名

updateDefinition

パラメータ
項目	説明
path	更新するメタデータのパスを設定します。必須項目です。
definition	更新するメタデータの定義を設定します。必須項目です。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。

メタデータ削除

メタデータの定義を削除する機能です。
パラメータで指定されたパスのメタデータ定義を削除します。

ツール名

deleteDefinition

パラメータ
項目	説明
path	削除するメタデータのパスを設定します。必須項目です。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。

5.2. EntityデータCRUD

Entityデータの操作（検索、登録、更新、削除）を行うための機能を、MCP Tool として提供します。

EntityデータCRUD機能を利用するには、以下の設定が必要となります。

操作対象の Entity に対して、EntityWebApi定義で該当する操作を許可する必要があります。操作の種別は INSERT、SELECT（Load）、SELECT（Query）、UPDATE、DELETE です。
詳細については、WebAPI - Entity CRUD API - 権限設定を参照してください。
データの操作は、ツールを実行する利用者の権限で行われます。利用者には、操作対象の Entity に対する Entity権限が必要です。
詳細については、認可 - 権限管理 - Entity権限を参照してください。

Entityデータ検索

Entityデータを検索またはロードする機能です。
パラメータの組み合わせにより、以下の 3 パターンの処理を実行します。

パターン	指定するパラメータ	処理
EQL検索	query	指定された EQL を実行します。
Entity指定検索	definitionName、filter（任意）	指定された Entity のデータを filter の条件で検索し、全プロパティを取得します。
ロード	definitionName、oid、version（任意）	oid で指定された単一の Entityデータをロードします。

パターン

指定するパラメータ

処理

EQL検索

query

指定された EQL を実行します。

Entity指定検索

definitionName、filter（任意）

指定された Entity のデータを filter の条件で検索し、全プロパティを取得します。

ロード

definitionName、oid、version（任意）

oid で指定された単一の Entityデータをロードします。

query と definitionName は、いずれか一方を必ず指定します。同時には指定できません。

ツール名

getEntity

パラメータ
項目	説明
query	検索する EQL を設定します。
definitionName	検索またはロードする Entity の定義名を設定します。
filter	definitionName で指定した Entity に対する Where句の条件式を設定します。 definitionName による検索時のみ有効です。
oid	ロードする Entityデータの oid を設定します。definitionName と組み合わせて指定します。
version	ロードする Entityデータのバージョンを設定します。oid と組み合わせて指定します。 oid を指定せずに version のみを設定した場合はエラーとなります。
countTotal	true または false を設定します。true が設定された場合、検索条件に該当するデータの総件数を取得します。検索時のみ有効です。
withMappedByReference	true または false を設定します。true が設定された場合、参照プロパティのうち被参照プロパティも取得します。 definitionName による検索およびロード時に有効です。未指定時のデフォルト値は Configuration - EntityWebApiService で設定します。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。
list	検索結果の Entityデータの配列が返ります。ロードの場合も、ロードした Entityデータを 1 件含む配列が返ります。該当するデータが存在しない場合は空の配列が返ります。
count	countTotal に true を設定した場合に、検索条件に該当するデータの総件数が返ります。

検索結果の件数が多い場合、LLMのコンテキストウィンドウを圧迫する可能性があります。なお、検索で取得できる件数には上限があります。上限件数は Configuration - EntityWebApiService の maxLimit で設定します。
EQL に limit句が指定されていない場合、検索結果は上限件数までに切り詰められます。ただし、throwSearchResultLimitExceededException が true の場合は、該当件数が上限を超えるとエラーとなります。
上限を超える件数の limit句を指定した場合もエラーとなります。
上限を超える件数のデータを取得する場合は、query による検索を利用し、EQL の limit句と offset句でページングして分割取得してください。definitionName による検索では limit を指定できないため、取得できる件数は常に上限件数までとなります。

Entityデータ登録

Entityデータを新規に登録する機能です。
指定された Entity にデータを登録し、登録したデータの oid を返却します。

ツール名

createEntity

パラメータ
項目	説明
definitionName	登録する Entity の定義名を設定します。必須項目です。
entity	登録する Entityデータを、プロパティ名をキーとするJSONオブジェクトで設定します。必須項目です。 JSONオブジェクトには、definitionName パラメータと同じ値の `definitionName` を含める必要があります。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。
oid	登録した Entityデータの oid が返ります。

entity パラメータの設定例

{
  "definitionName": "sample.Product",
  "name": "商品A",
  "price": 1000,
  "category": {"definitionName": "sample.Category", "oid": "1001"}
}

Entityデータ更新

Entityデータを更新する機能です。
oid で指定された Entityデータを更新し、更新したデータの oid を返却します。バージョン管理している Entity の場合は、更新後のバージョンも返却します。

ツール名

updateEntity

パラメータ
項目	説明
definitionName	更新する Entity の定義名を設定します。必須項目です。
oid	更新する Entityデータの oid を設定します。必須項目です。
version	更新対象のバージョンを設定します。バージョン管理している Entity の場合に有効です。 `-1` を設定した場合は、新しいバージョンのデータとして登録します。未指定の場合は、現在有効なバージョンのデータを更新します。
entity	更新内容を、プロパティ名をキーとするJSONオブジェクトで設定します。必須項目です。 JSONオブジェクトには、definitionName パラメータと同じ値の `definitionName` を含める必要があります。 JSONオブジェクトに含めたプロパティのみが更新対象となります。 `updateDate` に更新前の更新日時を含めた場合、更新時にタイムスタンプチェックが行われ、更新日時が一致しない場合はエラーとなります。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。
oid	更新した Entityデータの oid が返ります。
version	バージョン管理している Entity の場合に、更新後のバージョンが返ります。

Entityデータ削除

Entityデータを削除する機能です。
oid で指定された Entityデータを削除します。

ツール名

deleteEntity

パラメータ
項目	説明
definitionName	削除する Entity の定義名を設定します。必須項目です。
oid	削除する Entityデータの oid を設定します。必須項目です。
timestamp	削除対象の Entityデータの更新日時をエポックミリ秒で設定します。設定した場合、削除時にタイムスタンプチェックが行われ、更新日時が一致しない場合はエラーとなります。

レスポンス
項目	説明
status	ツールの実行結果を表します。成功した場合は "SUCCESS" を返却します。

利用にあたっての推奨事項

Entity およびプロパティの表示名（displayName）と説明（description）を十分に記述することを推奨します。
LLM が対象の Entity やプロパティを正しく特定し、意図した通りにデータを操作するための手がかりとなるためです。

各ツールの説明文では、プロパティ定義の確認にメタデータ取得を利用するよう LLM に案内しています。
名前だけでは意味や取りうる値が伝わらないプロパティ（コード値、フラグ、単位を持つ数値など）には、説明に意味と設定可能な値を記述してください。

メタデータ取得の利用には、メタデータCRUD に記載の設定と管理者権限が必要です。

6. その他の設定

MCPサーバーの機能に関連する設定について説明します。

6.1. MCPサーバー機能の権限管理

MCPサーバーの機能は、ロールベースで実行可能な機能を制御することができます。

認可に関しては、認可を参照してください。
MCPサーバーの権限管理については、認可 - 権限管理 - MCPサーバー権限を参照してください。

iPLAss 4.0 以前のバージョンから移行した場合、MCPサーバー権限エンティティがメニューに表示されません。
エンティティのデータを編集するためには、MCPサーバー権限エンティティをメニューに追加してください。

6.2. 閉塞機能の設定

MCPサーバーの機能は、サービス閉塞機能に対応しています。
サービス閉塞することで、MCPサーバーの機能を一時的に利用不可能にすることができます。

サービス閉塞機能については、開発・運用サポート - サービス閉塞機能を参照してください。