Beyond Entity MCP 利用ガイド

Beyond Entity MCP でできること

Beyond Entity MCP は、AI ツールが Beyond Entity プロジェクトのデータモデル、エンティティ、属性、リレーション、プロセッサ、データフロー、変更履歴を読み取り、作業できるようにする接続方式です。

Claude、ChatGPT、Cursor、VSCode など MCP 対応の AI ツールから自然言語で依頼できます。AI は Beyond Entity MCP を通じてプロジェクト構造を確認し、必要なモデリング作業、変更比較、ドキュメント作成を行うことができます。

たとえば、次のような作業を依頼できます。

  • 既存データベーススキーマを分析し、エンティティとリレーションを説明する
  • 新しいテーブル、カラム、制約、リレーションを設計または追加する
  • API、バッチ、ETL、データ同期などのプロセッサをモデル化する
  • SQL や処理ロジックをもとにデータフローと変換関係を文書化する
  • 個人情報、機微情報、暗号化対象カラムを探す
  • ブランチやコミット間のモデル変更を比較する
  • Web アプリで作成したモデルを AI コード生成、レビュー、ドキュメント作成に活用する
  • Beyond Entity に定義されたスキーマをもとに SQL、DDL、マイグレーションのドラフトを生成する
  • 既存コードから設計書を抽出する
  • 現在のコードが Beyond Entity に定義された設計に従っているか比較レビューする

MCP とは

MCP(Model Context Protocol) は、AI ツールが外部システムのデータを安全に読み取り、操作を実行するための標準的な接続方式です。

通常の AI チャットは、ユーザーが貼り付けた情報しか参照できません。Beyond Entity MCP を接続すると、AI はユーザーの権限内で Beyond Entity プロジェクトを直接参照できます。そのため、AI は最新のモデル構造、属性定義、リレーション、プロセッサ、データフロー、変更履歴にもとづいて回答し、作業できます。

対象ユーザー

Beyond Entity MCP は次のようなユーザーに役立ちます。

  • データモデラー: ERD、テーブル、カラム、キー、リレーションを素早く設計・レビューしたいユーザー
  • バックエンド開発者: データモデルをもとに API、DTO、ORM エンティティ、マイグレーションのドラフトを作成したいユーザー
  • データエンジニア: ETL、ELT、バッチ、ストリーミング、データ同期フローをモデル化・文書化したいユーザー
  • セキュリティ・ガバナンス担当者: 個人情報、機微情報、暗号化対象、データリネージを調査したいユーザー
  • プロジェクトリーダー: ブランチ、コミット、変更履歴を比較して設計変更をレビューしたいユーザー
  • アーキテクト・レビュアー: 実装コードが設計と一致しているか確認し、コードにしか存在しない設計情報を整理したいユーザー

主な作業タイプ

1. プロジェクト探索

AI にプロジェクト全体の構造を要約させることができます。

可能な作業:

  • アクセス可能なプロジェクト一覧の確認
  • 特定プロジェクトの選択
  • キャンバス、モデル、エンティティ、プロセッサ構造の要約
  • 名前やキーワードによるモデル要素の検索
  • 現在のブランチと変更状態の確認

依頼例:

アクセスできる Beyond Entity プロジェクトの一覧を表示して。

このプロジェクトのデータモデルと API プロセッサを一目で理解できるように要約して。

customer に関連するエンティティ、属性、プロセッサを探して整理して。

2. データモデルの読み取りと文書化

AI はモデル、エンティティ、属性、制約、リレーションを読み取り、人が理解しやすい文書に整理できます。

可能な作業:

  • 特定エンティティのカラム一覧と意味の説明
  • 主キー、外部キー、インデックス、制約の要約
  • エンティティ間リレーションの説明
  • 業務用語にもとづくデータ辞書ドラフトの作成
  • テーブル設計レビュー

依頼例:

Order エンティティのカラム、キー、リレーションを文書化して。

会員、注文、決済関連テーブルのリレーションを非開発者にもわかるように説明して。

このモデルで名前が似ている、または意味が重複しているように見えるカラムを探して。

3. データベースモデル設計

AI に新しいデータモデルを作成させたり、既存モデルにエンティティ、属性、制約、リレーションを追加させたりできます。

可能な作業:

  • MySQL、PostgreSQL、Oracle、SQL Server、BigQuery、Snowflake などのモデル作成
  • 新しいテーブルとカラムの設計
  • 主キー、外部キー、チェック制約、インデックスの追加
  • リレーション作成
  • 既存エンティティへの属性追加
  • モデル名、テーブル名、カラム名の修正

依頼例:

サブスクリプション決済機能に必要なデータモデルを設計して。顧客、サブスクリプション、支払方法、請求、決済試行テーブルが必要です。

Product エンティティに SKU、販売ステータス、販売開始日、販売終了日カラムを追加して。

Order 1 件が複数の Payment 試行を持てるリレーションを作成して。

4. API、バッチ、ETL プロセスのモデル化

Beyond Entity MCP はデータベーステーブルだけでなく、API サーバー、ETL バッチ、ELT ジョブ、ストリーミング処理、ファイル処理、データ同期などのプロセッサも扱えます。

可能な作業:

  • API リクエストとレスポンス構造のモデル化
  • バッチ入力、中間参照値、出力構造の定義
  • SQL ベースの抽出・変換ロジックの追加
  • プロセッサとデータエンティティ間の読み取り、書き込み、変換関係の文書化
  • 複数ステップの処理フローの整理

依頼例:

管理者ログイン API をプロセッサとしてモデル化して。入力は email と password、出力は accessToken と user 情報です。

毎日注文データを集計して daily_sales_summary テーブルに保存するバッチプロセスを設計して。

この SQL がどのテーブルを読み、どの出力フィールドを作るのかをデータフローとして登録して。

5. データリネージと影響分析

AI は属性、エンティティ、プロセッサ間のデータフローを追跡し、影響範囲を説明できます。

可能な作業:

  • 特定カラムがどこで読み取られ、どこに書き込まれるか追跡
  • API レスポンスフィールドがどの DB カラムから来ているか確認
  • バッチや ETL ロジックの入力と出力の整理
  • カラム変更時に影響を受けるプロセッサの検索
  • データフローの文書化

依頼例:

customer_email カラムがどの API レスポンスやバッチ出力で使われているか探して。

Payment.status カラムを変更すると影響を受ける可能性があるプロセッサを整理して。

会員登録から注文作成までの主要なデータフローを説明して。

6. 個人情報と機微情報の探索

プロジェクト内の個人情報、機微情報、暗号化対象属性を探し、管理基準に沿って確認できます。

可能な作業:

  • PII レベルが設定された属性の検索
  • 暗号化またはマスキング対象属性の確認
  • 機密度に応じたカラム一覧の作成
  • 個人情報を含むエンティティとプロセッサの識別
  • セキュリティレビュー用サマリーの作成

依頼例:

このプロジェクトで個人情報としてマークされた属性をすべて探して。

暗号化が必要そうだが、まだ暗号化設定がないカラムをレビューして。

ユーザー識別情報が API レスポンスとして露出する箇所を整理して。

7. 変更内容とバージョン比較

Beyond Entity プロジェクトは Git ベースのコラボレーションフローを使用します。MCP を通じて AI はブランチやコミット間の変更を確認し、要約できます。

可能な作業:

  • 現在のワークスペースの未コミット変更の確認
  • ブランチ間の変更比較
  • コミット間の変更比較
  • コミット履歴の確認
  • モデル変更レビューのドラフト作成

依頼例:

現在のブランチで変更されたモデル要素を要約して。

main ブランチと現在のブランチの差分をデータモデル観点で説明して。

最新コミットで変更されたエンティティと属性をレビューコメントとして整理して。

8. SQL、DDL、コード生成と開発支援

AI は Beyond Entity MCP でモデル構造を読み取り、データベースやアプリケーション開発に必要な成果物のドラフトを作成できます。

可能な作業:

  • Beyond Entity スキーマを基準に SQL DDL を生成
  • CREATE TABLE、カラム追加、インデックス、制約 SQL の作成
  • データベースマイグレーションのドラフト作成
  • 照会、検証、点検用 SQL の作成
  • ORM エンティティクラスのドラフト作成
  • API DTO、request、response 型の生成
  • テストデータ構造の提案
  • モデル構造にもとづく API 設計レビュー

依頼例:

現在の Beyond Entity モデルを基準に MySQL DDL を生成して。

新しく追加されたエンティティと属性だけを反映する PostgreSQL migration SQL のドラフトを作成して。

Order、Payment、Refund エンティティの主キー、外部キー、インデックスを含む CREATE TABLE 文を作成して。

Customer と Order エンティティを基準に JPA Entity のドラフトを作成して。

このプロセッサ定義を基準に FastAPI request/response Pydantic モデルを作成して。

Beyond Entity スキーマを基準に、本番リリース前に確認できるデータ検証 SQL を作成して。

9. 既存コードから設計書を抽出

AI がコードリポジトリと Beyond Entity MCP を併用すると、すでに実装されたコードからデータモデル、API、バッチ、プロセッサ設計書を抽出できます。

可能な作業:

  • ORM エンティティ、SQL、マイグレーションファイルからテーブルとカラム構造を抽出
  • コントローラ、ルータ、サービスコードから API リクエスト、レスポンス、利用テーブルを整理
  • バッチ、ETL、スケジューラコードから入力、処理、出力フローを文書化
  • コードにのみ存在するモデル要素を Beyond Entity 設計候補として整理
  • 既存実装をもとに初期データ辞書やシステム設計書ドラフトを作成

依頼例:

現在のコードの ORM エンティティとマイグレーションファイルを分析して、データモデル設計書のドラフトを作成して。

API ルータとサービスコードを基準に、ユーザー管理 API のリクエスト、レスポンス、利用テーブルを整理して。

バッチコードがどのテーブルを読み、どのテーブルに書き込むかを抽出して、プロセッサ設計候補にして。

10. 現在のコードと設計の比較レビュー

Beyond Entity に定義された設計と実際のコード実装を比較し、不一致や不足の可能性を確認できます。

可能な作業:

  • コード上のテーブル、カラム、型、制約が Beyond Entity モデルと一致するか確認
  • API request/response 構造がプロセッサ設計と一致するかレビュー
  • コードにはあるが設計にはないエンティティ、属性、API を探す
  • 設計にはあるがコードには実装されていない項目を探す
  • カラム名、型、null 許可、enum 値、リレーションの不一致候補を整理
  • コード変更と設計変更が両方反映されているかレビュー

依頼例:

現在のコードの User 関連 ORM モデルが Beyond Entity の User エンティティ設計と一致するか比較して。

注文作成 API の実装コードが Beyond Entity に定義されたプロセッサ入力、出力、データフローと合っているかレビューして。

コードには存在するが Beyond Entity 設計には登録されていないテーブル、カラム、API を探して。

Beyond Entity モデルにはあるが、現在のコードで実装が見つからない項目を整理して。

MCP 接続情報と API キーの発行

Beyond Entity MCP を使用するには、MCP サーバー URL と API キーが必要です。

MCP サーバー URL は、ユーザーまたは組織が利用する cell server によって異なる場合があります。他のユーザーから受け取った MCP URL をそのまま使うのではなく、自分の Beyond Entity Web アプリに表示される MCP URL を確認してください。

確認と発行の手順:

  1. Beyond Entity Web アプリにログインします。
  2. Settings に移動します。
  3. AI MCP Key 画面を開きます。
  4. 画面に表示された MCP サーバー URL を確認します。
  5. AI ツール接続用の API キーを作成します。
  6. MCP 対応 AI ツールに MCP サーバー URL と API キーを登録します。

AI ツールに登録する際は、通常次の情報が必要です。

  • MCP サーバー URL: AI MCP Key 画面に表示された URL
  • 認証ヘッダー: X-API-Key
  • API キー値: AI MCP Key 画面で作成したキー

Beyond Entity Web アプリの Settings > AI MCP Key 画面は、サーバーが返す接続ガイド Markdown をそのまま表示できます。このガイドには、ユーザーの組織 cell server に基づく実際の MCP URL が含まれます。

MCP Server URL は通常、次の 2 種類が提供されます。

推奨方式:

Streamable HTTP
https://{cell-server}/mcp

互換性方式:

SSE
https://{cell-server}/sse

ほとんどの最新 MCP クライアントでは Streamable HTTP の使用を推奨します。使用中の AI ツールが Streamable HTTP をサポートしていない場合、または SSE endpoint を明示的に要求する場合のみ SSE URL を使用してください。

特定プロジェクトに直接接続する Direct Checkout Mode では、次の形式を使用できます。

Streamable HTTP
https://{cell-server}/mcp?project_id={PROJECT_ID}

SSE
https://{cell-server}/sse?project_id={PROJECT_ID}

注意事項:

  • MCP サーバー URL は環境によって異なるため、文書や例の URL は参考用です。
  • API キーはパスワードと同様に扱い、公開リポジトリや共有文書に記載しないでください。
  • API キーを紛失した、または漏えいした可能性がある場合は、既存キーを廃止し新しいキーを発行してください。
  • API キーで実行される操作は、そのユーザーの権限に従います。

設定例:

{
  "mcpServers": {
    "beyond-entity": {
      "url": "AI MCP Key 画面に表示された MCP サーバー URL",
      "headers": {
        "X-API-Key": "発行された API キー"
      }
    }
  }
}

接続方式

Beyond Entity MCP は利用方法に応じて 2 つの接続方式を提供します。

どちらを選べばよいかわからない場合は、まず Streamable HTTP URL を使用してください。SSE は既存 MCP クライアントとの互換性のための方式です。

インタラクティブモード

複数プロジェクトを探索したり、会話中にプロジェクトを切り替えたりする場合に使用します。

適している場合:

  • Claude、ChatGPT、Gemini などのチャット型 AI ツールで使用する
  • 1 つの会話で複数プロジェクトを探索する
  • プロジェクト ID を事前に知らない
  • AI にプロジェクト一覧を表示させ、ユーザーが選択したい

基本フロー:

  1. MCP サーバーに接続します。
  2. AI がアクセス可能なプロジェクト一覧を取得します。
  3. ユーザーが作業対象プロジェクトを選択します。
  4. AI がそのプロジェクトをチェックアウトして作業します。
  5. 必要に応じて別プロジェクトへ切り替えます。

Direct Checkout Mode

1 つの IDE ワークスペースを 1 つの Beyond Entity プロジェクトに固定して使う場合に適しています。

適している場合:

  • VSCode、Cursor などの IDE で使用する
  • 1 つのワークスペースが 1 つのプロジェクトに対応する
  • 毎回プロジェクトを選ばず、すぐ作業を始めたい
  • プロジェクト ID をすでに知っている

基本フロー:

  1. MCP 接続 URL に project_id を含めます。
  2. 最初のツール呼び出し時に Beyond Entity がプロジェクトを自動チェックアウトします。
  3. 以降の作業はそのプロジェクトコンテキストで実行されます。

権限とセキュリティ

Beyond Entity MCP は、ユーザーの API キーとプロジェクト権限にもとづいて動作します。

  • ユーザーはアクセス権のあるプロジェクトのみ参照できます。
  • 読み取り専用ユーザーは変更操作を実行できません。
  • プロジェクト、ブランチ、キャンバス権限が適用されます。
  • MCP 経由の作業も Beyond Entity のコラボレーションと変更管理フロー内で実行されます。
  • 同じユーザーとプロジェクトでは、Web アプリ、MCP、IDE セッションが同じリモートワークスペースを共有できます。

注意点:

  • 同じプロジェクトで 1 つのセッションがブランチを変更すると、他のセッションにも影響する場合があります。
  • 重要な構造変更を依頼する前に、現在のブランチと変更状態を確認することを推奨します。
  • 削除操作はレビューと復旧手順を考慮して慎重に依頼してください。

推奨利用フロー

初めて使う場合は、次の順序で依頼することを推奨します。

  1. 「自分のプロジェクト一覧を表示して。」
  2. 「このプロジェクトを選択して。」
  3. 「全体のモデル構造を要約して。」
  4. 「重要なエンティティとプロセッサを探して。」
  5. 「実施したい変更の影響範囲を分析して。」
  6. 「現在のコードと設計が一致しているか比較して。」
  7. 「変更案を作成して。」
  8. 「変更内容をレビューコメントとして整理して。」

良い依頼の書き方

AI に依頼するときは、対象、期待する成果物、制約条件を一緒に伝えると効果的です。

良い依頼例:

現在のプロジェクトで注文ドメインの主要エンティティを探し、各エンティティの目的、主要カラム、リレーションを表で整理して。

サブスクリプション決済機能を追加したい。既存の顧客モデルと決済モデルを先に確認し、必要な新規エンティティとリレーションを提案して。すぐ変更せず、まず設計案を見せて。

email、phone、address のように個人情報に見えるカラムを探し、PII 設定があるか確認して。未設定候補は別に表示して。

現在のブランチの変更を main ブランチと比較し、レビュアーが確認すべきデータモデル変更だけを要約して。

コードリポジトリの API 実装を先に確認し、Beyond Entity に定義されたプロセッサ設計との差分だけを表で整理して。

よく使う依頼例

次の文をそのまま AI ツールに入力できます。

このプロジェクトの全体データ構造を、初めて見る人に説明するように要約して。

会員関連テーブルと API プロセッサを探し、どのデータがやり取りされるか整理して。

このモデルで外部キー関係が不足しているように見える参照カラムを探して。

新しいクーポン機能のデータモデルを設計し、Beyond Entity に追加して。

最近変更されたエンティティ、属性、リレーションをリリースノート形式で整理して。

個人情報を含むカラムと、そのカラムを使用するプロセッサを探し、セキュリティレビュー一覧を作成して。

この SQL クエリを分析し、入力、参照、出力データをプロセッサ変換として整理して。

現在のモデルを基準に、バックエンド開発者が実装すべき API DTO 一覧を提案して。

Beyond Entity の現在のスキーマを基準に SQL DDL とマイグレーションのドラフトを作成して。

設計された外部キー関係とインデックスを含めて PostgreSQL CREATE TABLE 文を生成して。

既存コードからデータモデル設計書を抽出し、Beyond Entity モデルに反映すべき候補を整理して。

現在のコードが Beyond Entity 設計と異なる箇所を探し、重要度別に整理して。

利用時の注意事項

Beyond Entity MCP は AI がプロジェクトをより正確に理解し作業するための機能ですが、すべての判断を自動で置き換えるものではありません。

  • AI が作成した設計案は、チームのモデリング規則と業務基準に合うか確認してください。
  • 大量変更や削除操作は、適用前に変更内容を確認することを推奨します。
  • コード生成結果は、実際の開発環境のフレームワーク、バージョン、命名規則に合わせて調整してください。
  • セキュリティ、プライバシー、権限に関する判断は、組織のポリシーと合わせてレビューしてください。

まとめ

Beyond Entity MCP は、AI が Beyond Entity プロジェクトの実際のモデルと変更履歴を直接理解し、データモデリング、プロセス設計、リネージ分析、セキュリティレビュー、SQL・コード生成、コードからの設計抽出、設計準拠レビューまで支援できる AI 作業連携機能です。