> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/ja/dev-reference/mcp-server.md).

# MCP サーバー

RealmJoin MCP サーバー: エンドポイント、MCP アクセストークン、クライアント設定、デバイス状態とソフトウェアデータの読み取り専用ツール、レート制限とセキュリティ。

RealmJoin は [Model Context Protocol](https://modelcontextprotocol.io/) （MCP）サーバーは RealmJoin Customer-API の一部として提供されます。MCP クライアント、たとえば AI アシスタントや IDE エージェントは、MCP アクセストークンを使って接続し、ツールを呼び出してあなたの Tenant のデバイス状態とソフトウェア データを読み取ります。

すべてのツールは読み取り専用です。MCP サーバーはデバイス、パッケージ、割り当て、設定を変更できません。

## 要件

* MCP サーバーはあなたの Tenant で有効です。この機能は RealmJoin によって有効化されます。有効化するには RealmJoin Support に連絡してください。
* トークンの作成と取り消しには、RealmJoin Portal で管理者ロールが必要です: RealmJoin の **Admin** ロール、または Entra ID **Global Administrator** ロール（Portal ポリシー `CanAdministerOwnTenant`；これはを通じて付与できません [カスタムロール](https://docs.realmjoin.com/ja/to/permission/custom-roles.md)）。 **MCP Access** 設定タブは、このロールがあり、かつこの機能が有効な場合にのみ表示されます。
* Streamable HTTP トランスポートをサポートし、カスタムな `Authorization` ヘッダー。MCP サーバーは OAuth サインインを提供しないため、OAuth 経由でリモート サーバーにのみ接続するクライアントは使用できません。

## エンドポイントと認証

| プロパティ   | 値                                        |
| ------- | ---------------------------------------- |
| URL     | `https://customer-api.realmjoin.com/mcp` |
| トランスポート | Streamable HTTP                          |
| 認証      | `Authorization: Bearer <MCP token>`      |
| サーバー名   | `realmjoin`                              |

このエンドポイントは MCP アクセストークンのみを受け付けます。ここで使用するユーザー名とシークレットは [RealmJoin API](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication.md) （HTTP Basic）はここでは受け付けられません。

すべてのリクエストで次の点が確認されます：

1. 有効なトークン：存在し、有効期限切れでも取り消し済みでもなく、シークレットが一致すること。
2. 承認された所有者：トークンを作成したユーザーが、まだ有効なアカウントと、その Tenant に適用される管理者ロールを持っていること（参照 [トークン所有者チェック](#token-owner-check)).
3. MCP サーバー機能が有効なアクティブな Tenant。

| レスポンス                   | 原因                                                                             |
| ----------------------- | ------------------------------------------------------------------------------ |
| `401 Unauthorized`      | Bearer トークンがない、トークンの形式が不正、未知、有効期限切れ、または取り消し済みのトークン、もしくはトークン所有者が所有者チェックに失敗した場合。 |
| `403 Forbidden`         | MCP サーバー機能が Tenant で有効になっていないか、Tenant が無効です。                                   |
| `429 Too Many Requests` | Tenant のレート制限を使い切った場合（参照 [レート制限](#rate-limit)).                                |

## MCP アクセストークン

MCP アクセストークンは RealmJoin Portal の以下で管理されます： **Settings** > **MCP Access**.

### トークンを作成

{% stepper %}
{% step %}

### MCP Access を開く

RealmJoin Portal で、以下を開きます **Settings** > **MCP Access** を開き、次をクリックします **新規追加** 検索フィールドの横にある（プラスアイコン）。
{% endstep %}

{% step %}

### トークンに名前を付け、有効期間を選択します

次の **新しい MCP トークン**、次を入力します **名前** クライアントまたは用途を識別するもの。たとえば `Claude Desktop` （必須、最大 100 文字）。次を選択します **有効期限**：30、90（既定）、180、または 365 日。次をクリックします **作成**.

<figure><img src="https://3438325150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-5eaace9fadaabec3068651837b60d659c666e233%2Fmcp-new-token.png?alt=media" alt="New MCP token dialog with the fields Name and Expires after"><figcaption><p>新しい MCP トークン</p></figcaption></figure>
{% endstep %}

{% step %}

### トークンをコピー

ダイアログ **MCP トークンが作成されました** はトークンを1回だけ表示します。コピーしてシークレットストアに保存してから、次をクリックしてください **完了**。RealmJoin はトークンのシークレットのハッシュのみを保存するため、トークンを再表示することはできません。紛失した場合は、新しいトークンを作成し、古いものを取り消してください。
{% endstep %}
{% endstepper %}

トークンの形式は次のとおりです `rjm_<tenant ID>.<token ID>.<secret>`。これは、トークン作成時に Portal で選択されている Tenant と、それを作成したユーザーに紐づきます。顧客 Tenant でパートナー管理者が作成したトークンは、その顧客 Tenant にのみアクセスできます。

### トークン一覧

次の **MCP Access** タブには、どの管理者が作成したものでも、Tenant のすべてのトークンが新しい順に表示されます。検索フィールドは名前と所有者で絞り込みます。

<figure><img src="https://3438325150-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-e4e64be11dc0e2b77352f58966b158091cbbc968%2Fsettings-mcp-access.png?alt=media" alt="MCP Access settings tab with the token list"><figcaption><p>MCP Access タブ</p></figcaption></figure>

| 列      | 内容                                                                          |
| ------ | --------------------------------------------------------------------------- |
| 名前     | 作成時に入力した名前。                                                                 |
| Owner  | トークンを作成したユーザーの User principal name。 **あなたのもの** は、自分のトークンを示します。              |
| 状態     | **有効**, **期限切れ** または **取り消し済み**。カーソルを合わせると **取り消し済み** 誰がトークンを取り消したかが表示されます。 |
| 有効期限   | 有効期限時刻。期限の必須化前に作成されたトークンは次を表示します **次回使用後**：次回使用時から 90 日の有効期限が設定されます。        |
| 最終使用日時 | 最後の認証済みリクエストの時刻。更新は 1 分に 1 回までで、または **なし**.                                 |
| 作成日時   | 作成時刻。                                                                       |

### トークンを取り消す

次をクリックします **取り消す** トークンの行で確認します。すべての管理者は、他のユーザーのトークンを含め、Tenant のすべての有効なトークンを取り消せます。取り消しは次のリクエストで有効になります。取り消し済みおよび期限切れのトークンは、状態付きで一覧に残り、再有効化はできません。

### トークン所有者チェック

トークンは、それを作成したユーザーのアクセス権で動作します。各リクエストで、RealmJoin はそのユーザーのホーム Tenant における所有者を確認します：

* ユーザーアカウントが存在し、有効である。
* ユーザーが現在、次を付与するロールを持っている `CanAdministerOwnTenant`：RealmJoin の **Admin** ロール（参照 [定義済みロール](https://docs.realmjoin.com/ja/to/permission/pre-defined-roles.md#admin-permissions)）または有効な Entra ID **Global Administrator** ロール。
* ホーム Tenant 以外の Tenant では、ホーム Tenant はその Tenant のパートナーとして登録されています。

結果は 5 分間キャッシュされます。そのため、アカウントが無効になるか管理者ロールが削除されると、トークンを取り消さなくても 5 分以内にそのユーザーのトークンは停止します。たとえば Microsoft Graph が利用できないなど、チェックを完了できない場合は、リクエストは 1 分間拒否されます。

{% hint style="warning" %}
チェックでは所有者の現在のグループ メンバーシップと Active Directory ロールを使用します。所有者の管理者アクセスが Privileged Identity Management (PIM) による場合、トークンはグループ メンバーシップまたはロールが有効化されている間のみ機能します。
{% endhint %}

## クライアントを接続する

クライアントをエンドポイント URL と次のもので構成します `Authorization` トークンを含むヘッダー。構成形式はクライアントによって異なります。トークンはソース管理にコミットされる構成ファイルに含めず、代わりにクライアントの環境変数またはシークレット入力の仕組みを使用してください。

{% tabs %}
{% tab title="汎用（mcpServers JSON）" %}
次を使用するクライアント `mcpServers` JSON 形式で、トークンは環境変数から取得されます `REALMJOIN_MCP_TOKEN`:

```json
{
  "mcpServers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${REALMJOIN_MCP_TOKEN}"
      }
    }
  }
}
```

変数が展開されるかどうかは `${...}` クライアントによって異なります。
{% endtab %}

{% tab title="Claude Code" %}

```bash
claude mcp add --transport http realmjoin https://customer-api.realmjoin.com/mcp \\
  --header "Authorization: Bearer $REALMJOIN_MCP_TOKEN"
```

シェルが展開します `$REALMJOIN_MCP_TOKEN` コマンドの実行時に、Claude Code は結果のヘッダーをその構成に保存します。
{% endtab %}

{% tab title="VS Code" %}
`.vscode/mcp.json`；VS Code は初回起動時にトークンの入力を求め、それをシークレットストレージに保存します：

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "realmjoin-mcp-token",
      "description": "RealmJoin MCP token",
      "password": true
    }
  ],
  "servers": {
    "realmjoin": {
      "type": "http",
      "url": "https://customer-api.realmjoin.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:realmjoin-mcp-token}"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

## 利用可能なツール

すべてのツールは JSON をテキストとして返し、トークンが紐づく Tenant のデータのみを読み取ります。デバイス データは RealmJoin Agent が報告するデバイス状態に基づきます。Agent のないデバイスは見つかりません。ソフトウェア データは次から取得されます [Software Reporting](https://docs.realmjoin.com/ja/toekusupto/software-reporting.md).

| ツール                   | パラメーター                         | 返す内容                                              |
| --------------------- | ------------------------------ | ------------------------------------------------- |
| `get_tenant_overview` | なし                             | アクティブおよび合計のデバイス数とユーザー数、ソフトウェア パッケージ数、アクティビティしきい値。 |
| `search_devices`      | `クエリ`                          | マシン名またはデバイス ID プレフィックスに一致するデバイスを最大 25 台。          |
| `get_device_by_name`  | `名前`                           | その名前を持つ、最も最近検出されたデバイスの完全なデバイス状態。                  |
| `get_device_state`    | `deviceId`、省略可能 `パス`、省略可能 `完全` | 1 台のデバイスの要約、選択したセクション、または完全なデバイス状態。               |
| `list_packages`       | 省略可能 `検索`                      | デバイス数とユーザー数を含むソフトウェア パッケージを最大 50 件。               |
| `get_software_report` | `packageId`                    | 1 つのパッケージのインストール済みバージョンと、デバイス数、ユーザー数、使用回数。        |

### get\_tenant\_overview

返す内容：

* `Devices.Active` / `Devices.Total`：アクティビティしきい値内で検出されたデバイスと、すべてのデバイス。
* `Users.Active` / `Users.Total`：ユーザーについても同様です。
* `SoftwarePackages`：Tenant 内の RealmJoin パッケージ数。
* `ActivityThreshold`："アクティブ" の判定時刻（現在時刻から Tenant のアクティビティ期間を引いた値、既定では 90 日）。

### search\_devices

`クエリ` マシン名にそれが含まれる場合（大文字小文字を区別しない）または RealmJoin client ID、Entra device ID、Intune device ID がそれで始まる場合にデバイスに一致します。最新の検出順で最大 25 台のデバイスを返し、それぞれに次を含みます `ClientID`, `UserID`, `MachineName`, `VersionTray` （エージェント バージョン）と `ServerTimestamp` （最後のチェックイン）。一致するデバイスがさらにある場合、レスポンスには合計で何台一致したかが示されます。

### get\_device\_by\_name

`名前` はホスト名とマシン名に対して大文字小文字を区別せず比較され、完全一致のみがカウントされます。複数のデバイスが同じ名前を共有している場合は、最も最近検出されたものが返されます。レスポンスにはデバイスの完全な状態が含まれ、20,000 文字で切り捨てられます。次を使用してください `get_device_state` と `パス` を使って特定のセクションを指定します。

### get\_device\_state

`deviceId` は GUID です：RealmJoin client ID、Entra device ID、または Intune device ID。

* 次を指定しない場合 `パス` と `完全`、レスポンスには次のセクションが含まれます： `ClientID`, `MachineName`, `HostName`, `UserID`, `ServerTimestamp`, `VersionTray`, `OperatingSystem`, `Intune`, `Msoa`, `AzureAD`, `User`.
* `パス` はこの選択をデバイス状態の一覧にあるプロパティ パスに置き換えます。たとえば `Intune`, `BranchCache`, `LocalAdminManagement` または `CustomStates.PrinterInventory`。パスには、英字、数字、アンダースコア、ハイフン、ドット、配列インデックスを含めることができます。
* `full: true` 完全なデバイス状態を返します。

20,000 文字を超えるレスポンスは切り捨てられ、合計長を示す注記が付きます。

### list\_packages

パッケージ ID が次で始まる Software Reporting データのパッケージを一覧表示します `generic-` （Package Store パッケージ）。デバイス数で並べ替え、最大 50 件。 `検索` パッケージ ID の部分文字列で絞り込みます。たとえば `chrome`。各エントリには次が含まれます `PackageId`, `DeviceCount` と `UserCount`.

### get\_software\_report

`packageId` はパッケージ ID と完全一致する必要があります。たとえば `generic-7zip`；次を使用してください `list_packages` 見つけます。最大 20 件を返し、バージョンの高い順です。各エントリにはパッケージ ID、 `バージョン`, `Publisher`、インストールの種類、 `DeviceCount`, `UserCount`, `LicenseCount`、実行に基づくデバイス数、ユーザー数、ライセンス数、 `TotalExecutions` と `LastExecution`.

## レート制限

各 Tenant は MCP エンドポイントに 1 分あたり 60 件のリクエストを送信できます。これは 10 秒区間 6 個のスライディング ウィンドウでカウントされます。この制限は Tenant に適用されるため、1 つの Tenant のすべてのトークンで共有されます。制限を超えたリクエストは直ちに次で拒否されます `429 Too Many Requests`；キューには入りません。

セッション初期化やツール一覧取得を含め、MCP メッセージはすべて個別の HTTP リクエストです。そのため、クライアントは 1 回のツール呼び出しで複数のリクエストを使用します。次で拒否されたリクエストは `401` または `403` カウントされません。

## セキュリティ上の考慮事項

* **トークンの範囲：** トークンは、それを作成したユーザーのアクセス権で、その Tenant のデバイス状態とソフトウェア データへの読み取りアクセスを提供します。トークンを持つ人は、有効期限が切れるか取り消されるまで使用できます。
* **RealmJoin から外部に出るデータ：** ツールの結果は、デバイス名、UserID、その他のデバイス状態を含め、MCP クライアントに渡され、AI アシスタントの場合はクライアントが使用するモデルプロバイダーにも渡されます。クライアントを接続する前に、これがあなたの Tenant のデータで許可されていることを確認してください。
* **保管：** トークンはパスワードマネージャーやシークレットストア、またはクライアントのシークレットストレージに保存してください。ソース管理にコミットしたり、チケットやチャットに貼り付けたり、複数の人やクライアントで 1 つのトークンを共有したりしないでください。
* **有効期間とローテーション：** 用途に合う最短の有効期間を選択してください。ローテーションするには、新しいトークンを作成し、クライアントを更新してから、古いトークンを取り消します。
* **取り消し：** 使用されなくなった、または漏えいした可能性のあるトークンを取り消してください。Tenant のすべての管理者は、その **MCP Access** タブで任意のトークンを取り消せます。確認してください **最終使用日時** 未使用のトークンを見つけます。
* **所有者変更：** 所有者が離脱するか管理者ロールを失うと、そのトークンは 5 分以内に動作しなくなります。それでも取り消して、一覧に実際の状態を表示させてください。
* **Tenant の削除：** Tenant を削除すると、そのすべての MCP トークンも削除されます。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/ja/dev-reference/mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
