ToolJet MCP Server

tooljet-mcp

コーディングエージェント（Codex、Claude Code、…）がToolJetの管理されたAPIを通じて ToolJet アプリを構築・保守できるMCPサーバーです。対象となるAPIは、ワークスペース、アプリ／ページ、データソースクエリ、ToolJet DBテーブル、コンポーネント、レイアウト、ライフサイクルイベントです。生成されたコンポーネントおよびデータソースのカタログも含まれているため、エージェントは設定キーを推測せず、ファーストパーティの仕様を使用できます。

ブラウザーのOAuth接続

リモートHTTPクライアントの場合、OAuthの設定を行うと、PATをコピーすることなく、ワークスペースのToolJetログインおよび同意フローを通じて接続できます。このリリースではOAuthはCloud専用であり、MCP_OAUTH_ENABLED=trueおよび5つすべてのOAuthマイグレーションを有効にした、対応するToolJet Cloudバックエンドが必要です。既存のローカルPATプラグインも引き続きサポートされます。以下の前提条件は、そのローカル設定について説明しています。

前提条件

• 個人アクセストークンに対応したToolJetインスタンス。
• 対象のToolJetワークスペース用の個人アクセストークン。
• Node.js 20以降。

セットアップ

git clone https://github.com/ToolJet/tooljet-mcp.git
cd tooljet-mcp
cp .env.example .env        # then edit .env with your creds
npm install
npm run build               # compiles to dist/

.env:

TOOLJET_URL=http://localhost:3000        # your ToolJet deployment
TOOLJET_PAT=tj_pat_...                   # Settings -> Access tokens, in the target workspace
# Only needed if the UI is served from a different origin than TOOLJET_URL (defaults to it otherwise):
# TOOLJET_DEPLOYMENT_URL=http://localhost:8082

デフォルトのMCPプロファイルでは、ツールの選択肢を絞るため、バッチ作成ツールのみを公開します。各バッチでは1つの項目を受け付けます。古いクライアントで重複する単数形のエイリアスを復元するには、TOOLJET_INCLUDE_LEGACY_SINGULAR_TOOLS=trueを設定してください。

Codexプラグインとしてインストール

このリポジトリは、同梱のMCPサーバーとtooljet-app-builderスキルを一緒に登録する、自己完結型の Codexプラグイン です。Codexマニフェストは.codex-plugin/plugin.jsonにあり、.mcp.jsonはユーザー側でインストールやビルドを行わずにbundle/index.jsを起動します。

公開リストへの掲載は不要です。.agents/plugins/marketplace.jsonによって、このリポジトリ自体がマーケットプレイスになります。

codex plugin marketplace add ToolJet/tooljet-mcp --ref main
codex plugin add tooljet-app-builder@tooljet

Codexデスクトップでは、マーケットプレイスコマンドを実行してアプリを再起動し、［プラグイン］を開いてToolJetのソースを選択し、ToolJet App Builderをインストールします。Codex CLIでは、/pluginsからインストールすることもできます。

Codexを起動する前に、スタンドアロンMCPサーバーで使用するものと同じ認証情報を設定してください。

export TOOLJET_DEPLOYMENT_URL="https://your-instance.tooljet.com"
export TOOLJET_PAT="tj_pat_..."
# only needed if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# export TOOLJET_URL="https://api.your-instance.tooljet.com"

プラグインはこれらの環境変数をMCPプロセスに渡します。認証情報を保存したり変更したりすることはありません。Codexから利用できるよう、Node 20以降を用意する必要があります。

Codexへの手動登録

Codexは~/.codex/config.tomlからMCPサーバーを読み込みます。次の内容を追加してください。

[mcp_servers.tooljet]
command = "node"
args = ["/absolute/path/to/tooljet-mcp/bundle/index.js"]

[mcp_servers.tooljet.env]
TOOLJET_DEPLOYMENT_URL = "https://your-instance.tooljet.com"
TOOLJET_PAT = "tj_pat_..."
# only if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# TOOLJET_URL = "https://api.your-instance.tooljet.com"

次に、Codexがツールの使い方を認識できるよう、スキルをインストールします。skill/ディレクトリ全体をCodexのスキルディレクトリにコピーするか、npm run sync:skillを使用してください。コンパクトなエントリーポイントから、テーブル、フォーム、イベント、データソース、セキュリティ、QAに関する個別のリファレンスが段階的に読み込まれます。

Codexを再起動すると、create_app、list_datasources、get_datasource_query_schema、get_component_catalog、lint_app_spec、バッチ作成ツール、validate_appなどのToolJetツールが利用可能になります。

Streamable HTTP での実行

2 つの HTTP 形態があり、それぞれ異なる用途に対応します。どちらも stdio と同じ方法で認証しますが、異なるのは 認証情報がどこから来るかです。

ダイレクトモード は、あなたがサーバーを実行し、あなた自身のエージェントがそれに接続する形態です。同梱の バンドルはこの方式で動作するため、Node 以外に何も必要としません:

MCP_TRANSPORT=http PORT=8787 TOOLJET_DEPLOYMENT_URL=https://your-instance.tooljet.com TOOLJET_PAT=tj_pat_... \
  node bundle/index.js

これは 127.0.0.1 にバインドし(MCP_HTTP_HOST で上書き可能)、http://127.0.0.1:8787/mcp を提供します。 認証情報はどちら側からでも取得できます:

• サーバーの環境変数にある TOOLJET_PAT、または
• リクエストごとにクライアントから、Authorization: Bearer <pat> または x-tooljet-pat: <pat> として

リクエストごとのトークンは、プロセスのトークンとマージされるのではなく、それを完全に置き換えるため、1 つの サーバーが複数の人にサービスを提供しても、誰も他人の ID を引き継ぐことはありません。

ゲートウェイモード は、あるインスタンスの前面に立つ 1 つの共有サーバーであり、ToolJet の AI シムからのみ 呼び出されます。MCP_SHARED_TOKEN を設定すると、サーバーは 0.0.0.0 にバインドし、そのトークンを Authorization: Bearer として要求し、実行ユーザーを x-tooljet-session と x-tooljet-workspace-id から 取得します。x-tooljet-pat は完全に拒否します。PAT はその所有者を特定し、数週間有効であるため、ここでそれを受け入れると、 ビルドがそれを要求した人ではなくトークン保有者に帰属されてしまうからです。

ローカル開発用に npm run start:http(src/http.ts、ポート 3001、ループバック、 TOOLJET_MCP_HTTP_HOST / TOOLJET_MCP_HTTP_PORT、および /health エンドポイント)もあります。これは同じ リクエストごとの認証情報を受け入れ、ダイレクトモードと同様に、独自のベアラーゲートを持ちません。

ローカルのステートフルなトランスポートは、初期化時に ID をバインドします。すべての POST、GET/SSE、DELETE で 同じベアラーおよび実行ユーザーのヘッダーを送信してください。認証されたセッションを認証するのはセッション ID だけでは ありません。ビルドトークンの失効/期限切れはアクセスを終了させます。これは最大 256 セッションを保持し、30 分間の アイドルまたは合計 6 時間の後にセッションを削除し、期限切れ/失効したセッションを毎分スイープします。これらの制限は createHttpMcpServer のオプションで設定可能です。認証情報のないローカルセッションはプロセス設定の ID を保持します。 この開発用トランスポートは公開エンドポイントではなくループバック上に保ってください。

ビルドトークンの発行は、信頼された ToolJet バックエンドのためのなりすまし権限であり、エンドユーザー向けの API ではありません。MCP_BUILD_TOKEN_SECRET はサーバー側に保ってください。TOOLJET_MCP_TOKEN はその発行 シークレットの互換フォールバックとして引き続き機能します。どちらかを設定すると mint/revoke エンドポイントが有効になります。 発行シークレットをサンドボックス/クライアントに渡さないでください。意図するユーザーに対して発行された短命の ビルドトークンのみを渡してください。

レンダリング監査の境界

verify_page_render は、MCP ホスト上のオプションの Playwright 1.48+ インストールと Chrome を使用します。 これは新しく認証されていないコンテキストを作成します。プライベートアプリでは手動の認証済みブラウザ QA が必要になる 場合があります。保存されたビューアセッションを読み込んだり、アプリを公開したり、サインイン/空/エラーページを合格と みなしたりすることはありません。検出結果は kind "unreachable" を保持し、その理由はブラウザの欠如、認証、 ネットワークポリシー、HTTP エラー、ウィジェットの欠如を区別します。

設定された ToolJet ビューアオリジンは信頼されます。これには明示的に設定された localhost または プライベート/セルフホストのアドレスも含まれます。別のビューア/API/CDN オリジンには、オペレーターが制御する MCP_RENDER_AUDIT_ALLOWED_ORIGINS のカンマ区切りリストが必要です。ツールの引数でこれを拡張することはできません。 すべての HTTP(S) リソースは同じ許可リストを使用します。HTTP リダイレクトは追跡されず(正規 URL を設定してください)、 Service Worker はブロックされ、WebSocket 依存関係は未検証として報告されます。 多層防御として、インフラストラクチャの egress 制限を備えた専用のブラウザコンテナを使用してください。 アプリケーションレベルの URL チェックは、ネットワーク分離や DNS リバインディング保護の代わりにはなりません。

Copilot / VS Code エージェントプラグインとしてインストールする

リポジトリのルートにある plugin.json と mcp.json は、VS Code、Copilot CLI、Copilot アプリが共通で採用している Agent Plugins 1.0 形式に準拠しています。Chat: Install Plugin From Source（または Agent Customizations エディターの Plugins タブ）からインストールし、このリポジトリの URL を指定してください。

スキルは skills/ から検出されるため、Claude Code が読み込むものと同じ skills/tooljet-app-builder が、別のコピーを用意せずにここでも読み込まれます。エディターの起動環境で TOOLJET_DEPLOYMENT_URL と TOOLJET_PAT を設定してください（API のオリジンが TOOLJET_DEPLOYMENT_URL と異なる場合に限り、TOOLJET_URL も設定してください）。値が未設定または空の場合はサーバー独自のデフォルト値が使用され、トークンがない場合はサーバーが停止するのではなく、ハンドシェイク時にその旨が報告されます。

リモート MCP 接続向けのスキル専用プラグイン

ToolJet がリモート MCP/OAuth を通じてすでに接続されている場合は、tooljet-app-builder-skills を使用してください。統合プラグインと同じアプリビルダーのスキル、対象を絞ったリファレンス、ブラウザー監査ヘルパーを提供します。コンポーネントの仕様は、接続された MCP の get_component_catalog ツールから取得します。生成されたオフラインのカタログ JSON は含まれません。MCP サーバーを登録せず、認証情報も要求せず、2つ目の PAT 接続も開始しません。

Claude Code では、マーケットプレイスを追加してスキル専用エントリーをインストールします。

/plugin marketplace add ToolJet/tooljet-mcp
/plugin install tooljet-app-builder-skills@tooljet

リモート ToolJet MCP サーバーには、別途接続して認証してください。このスキルは接続で公開されているツール名を使用するため、サーバーの名前が tooljet である必要はありません。ガイダンスの重複読み込みを避けるため、セッションではこのパッケージか統合版の tooljet-app-builder プラグインのいずれかを使用してください。Codex マーケットプレイスにも、独自のスキル専用マニフェストを持つ tooljet-app-builder-skills が用意されています。

リポジトリのルートから自己完結型のディレクトリをビルドします。

npm run build:skill-plugin
claude plugin validate ./plugins/tooljet-app-builder-skills
claude --plugin-dir ./plugins/tooljet-app-builder-skills

このコマンドは、スキルとリファレンスを再生成してから plugins/tooljet-app-builder-skills/ にパッケージ化します。ビルドにサーバーバンドル、稼働中の ToolJet インスタンス、TypeScript ビルド、認証情報は必要ありません。生成されたスキルファイルは Git からインストールできるようコミットされています。scripts/generate-skill.mjs または参照先のソースを編集してから、再ビルドしてください。パッケージのメタデータは scripts/build-skill-plugin.mjs と package.json から取得されます。

Claude Code プラグインとしてインストールする

このリポジトリは自己完結型の Claude Code プラグインでもあります。インストールすると、MCP サーバーと tooljet-app-builder スキルがまとめて登録されます。ユーザー側で npm install やビルドを行う必要はありません。単一ファイルのバンドル（bundle/index.js）と data/ 内のランタイムカタログがコミットされています。

インストール（マーケットプレイスは不要）：

/plugin install github:ToolJet/tooljet-mcp

更新を受け取れるマーケットプレイス経由でもインストールできます。

/plugin marketplace add ToolJet/tooljet-mcp
/plugin install tooljet-app-builder@tooljet

ローカル開発の場合は、パスを指定してインストールすることもできます：/plugin install path:/absolute/path/to/tooljet-mcp。

認証情報を設定します。 プラグインからシークレットを尋ねることはできないため、MCP サーバーは環境変数から読み取ります（TOOLJET_DEPLOYMENT_URL のデフォルトは localhost、TOOLJET_URL のデフォルトは TOOLJET_DEPLOYMENT_URL です）。Claude Code を起動する前に、次を実行してください。

export TOOLJET_DEPLOYMENT_URL="https://your-instance.tooljet.com"
export TOOLJET_PAT="tj_pat_..."
# only needed if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# export TOOLJET_URL="https://api.your-instance.tooljet.com"

TOOLJET_DEPLOYMENT_URL と TOOLJET_PAT が設定されていない場合、サーバーは必須変数が不足していることを明確に示して起動時に終了します。設定後、再起動してください。

同梱内容とビルド方法。 bundle/index.js はサーバーを esbuild で単一ファイルにバンドルしたもので、すべての依存関係がインライン化されているため、node_modules がなくても実行できます。実行時には data/ からコンポーネントとデータソースのスキーマ、およびコンポーネントの互換性メタデータを読み込みます。generate:skill は、重点的な参照資料をすべて含め、同じソースから skill/ とパッケージ化された skills/tooljet-app-builder/ の両方を生成します。ソースやカタログを変更した後は、次のコマンドですべてを再ビルドしてください。

npm run generate:catalogs && npm run generate:skill && npm run build:plugin

プラグインマニフェストは .claude-plugin/plugin.json（${CLAUDE_PLUGIN_ROOT}/bundle/index.js 経由で MCP サーバーを宣言）で、マーケットプレイスカタログは .claude-plugin/marketplace.json です。

スキルのみを変更する場合は、npm run generate:skill && npm run build:plugin を実行してください。兄弟リポジトリのチェックアウト、MCP サーバー、Python MCP パッケージ、認証情報は不要です。生成には、data/skill-source-snapshot.json 内の固定されたグリッド／ウィジェットのスナップショットを使用します。上流の情報を更新するには、TOOLJET_ROOT=/path/to/ToolJet node scripts/generate-skill.mjs --refresh-source-snapshot を明示的に実行し、スナップショットの差分を確認してから再生成／パッケージ化してください。生成された Markdown にはそのソースが示されます。生成物ではなく、そのソースを編集してください。両方のスキルパッケージに含まれるオフラインカタログには、すべてのデフォルト値、renderingHints、defaultChildren が含まれ、生成、テスト、プラグインのパッケージ化の際に再ビルドされます。CI では Markdown を再生成して差分がないことを確認し、テストを実行し、バンドルをビルドして、MCP の初期化を検証します。

デモ

Codex では：

ToolJet DB を使ってチケットのダッシュボードを作成してください。

Codex は list_datasources → create_app → lint_app_spec → apply_app_phase の順に実行し、その後の対象を絞った追加には add_queries／add_components を使用する想定です。create_app は、作成状況を確認するためのエディターリンクと、完成したページをテストするためのビューワーリンクを返します。

ツール

ツール	目的
list_workspaces() / use_workspace(workspace_id)	アクティブな ToolJet ワークスペースを確認または切り替えます。結果にはその手動データソース設定 URL が含まれます
manage_app_permissions(...)	対象となるユーザー/グループを一覧表示し、ページ/クエリ/コンポーネントのアクセスを確認、制限、または解除します。変更は確認され、ライセンスによって制限されます
list_workspace_apps(...)	現在の PAT に固定されたワークスペース内のアプリを一覧表示します
list_workspace_users(...)	PAT 認証を通じて、ページネーションとステータスフィルタリングを備えたワークスペースユーザーの一覧表示/検索を行います
list_workspace_groups(...)	グループ/メンバーを一覧表示します。include_permissions:true で権限スイッチと詳細ルールを読み取り、resource_type で選択可能なリソースを検出します
manage_workspace_groups(...)	グループの作成/名前変更/削除/複製、メンバーの削除、権限スイッチの更新、詳細アクセスの作成/更新/削除を行います。確認と ToolJet 管理者権限が必要です
manage_workspace_users(...)	PAT 認証を通じてワークスペースユーザーを招待/更新/アーカイブします。変更には確認が必要で、ToolJet のロールチェックの対象となります
create_app(name)	新しいアプリ + バージョン + ホームページ → ID、明示的なエディター/ビューアーリンク、およびワークスペースのデータソース設定 URL を返します（app_url はエディターのエイリアスのままです）
create_app_version(app_id, version_name, version_from_id, version_description?)	既存のバージョンを新しいドラフトに複製し、編集を継続するための新しい version_id を返します
switch_app_version(app_id, version_id)	正確なアプリバージョンを検証し、ToolJet エディターがそれを選択するために使用できるメタデータを返します
release_app(app_id, version_id, confirm:true)	必要に応じて特定のバージョンを本番環境に公開および昇格させ、ライブリリースバージョンにして、アプリを読み戻すことで変更を検証します
list_datasources(version_id)	新規/既存のアプリで自動的に利用可能なワークスペースソースを、それぞれ直接設定 URL 付きで一覧表示します。アプリごとのリンクはありません
get_datasource_query_schema({datasource_id, version_id, operation?, sections?})	コンパクトなリクエスト契約と、判明している場合はレスポンスの形状/ステータスを取得します。kind の検索とバッチもサポートします
inspect_datasource_schema({datasource_id, version_id, method, ...})	プラグインが公開する読み取り専用メタデータメソッド（スキーマ/テーブル/カラム/コレクション）を 1 つ呼び出します
list_tables() / get_table_schema(table_name)	ToolJet DB のテーブル、制約、デフォルト、リレーションシップを確認します
create_tables(...) / add_table_column(...)	1 つ以上の ToolJet DB テーブルを作成するか、既存のモデルを進化させます。バッチは書き込み前に依存関係を事前チェックします
insert_rows_batch(...)	1 つまたは複数の ToolJet DB テーブルへの挿入専用のシード書き込みです。生成されたシリアルキーは実際のシーケンスを使用し、競合は明確に失敗します
drop_table_column(..., confirm:true) / drop_table(..., confirm:true)	明示的に確認された破壊的な ToolJet DB クリーンアップです
get_component_catalog({type?, types?, sections?, ...})	コンポーネントパレット、または選択的な単一/バッチ契約。ネストされた authoringHints を含みます
generate_form_schema({table_name, mode, ...})	ToolJet DB テーブルから 1 つのスキーマ駆動の作成/編集フォームを生成します
lint_app_spec(...) / apply_app_phase(...) / validate_app(app_id)	論理フェーズをドライランし、その一度限りのプラントークンを適用してから、永続化された状態を静的に検証します
get_app_summary({app_id, sections?, filters?, *_fields?})	実際に永続化された値を選択的に確認します
add_pages(...) / update_pages(...)	ページを追加し、その後、個々の非ホームページの名前変更、スタイル変更、並べ替え、または非表示を行います。メニュー全体には update_app_settings.navigation_hidden を使用します
delete_page(..., confirm:true)	イベントとコンポーネントの参照を確認した後、非ホーム/非グループのページを 1 つ完全に削除します
add_queries(...)	1 つ以上のデータソースクエリを作成します。options にはスキーマツールを使用します
add_components(...) / add_component_batches(...)	1 つのページまたは複数の独立したページを配置します。アトミックな親/子バッチやネイティブのヘッダー/ボディ/フッタースロットを含みます
add_events(...) / add_query_lifecycles(...)	任意のインタラクションを追加するか、標準的なミューテーションの成功/失敗フローを 1 つのバッチで拡張します
update_* / 確認済みの delete_* / run_query(...)	アプリをその場で修復します。削除には正確なターゲットの確認が必要で、大規模/課金対象の読み取りには明示的な承認が必要です
グループ管理は PAT ワークスペース内で行われます。manage_workspace_groups は create、rename、delete、remove_member、duplicate、update_permissions、create_access、update_access、delete_access をサポートします。list_workspace_groups でグループとメンバーシップ ID を読み取ります。権限の切り替え項目と詳細なルール ID を取得するには、group_id と include_permissions:true を追加します。選択可能なリソースを確認するには、resource_type（app、module、workflow、data_source のいずれか）を使用します。

権限の更新で変更されるのは、指定された切り替え項目のみです。新しい詳細ルールでは、省略されたアクションの切り替え項目は無効になります。更新では、関連しないアクションはそのまま保持されます。canEdit／canView または canConfigure／canUse を有効にすると、対になる切り替え項目は無効になります。両方を同時に有効にすることはできません。access.resource_ids は選択済みのリソースを置き換え、access.is_all:true はその種類の現在および今後のすべてのリソースを対象にします。複製には、少なくとも 1 つの copy カテゴリーを選択する必要があります。無効化されたグループは変更できません。制限付きプランによって提供される合成ルールは、書き込み可能なルール ID を持たず、理由とともに read_only:true として返されます。ロールを変更する更新には、明示的な allow_role_change:true が必要であり、ToolJet の認可およびライセンスの確認も適用されます。デフォルトの Admin 権限と、デフォルトのロールグループ名／メンバーシップは保護されています。既存の manage_workspace_users は、カスタムグループへのメンバー追加に使用します。

ワークスペースのテーマの作成と管理には manage_theme を使用します。アプリへのテーマの適用は、引き続き update_app_settings で行います。定義の構造とトークンベースのスタイル設定については、docs/theme-api-tool.md に記載されています。

リソース

読み取り専用のカタログデータです。ローカルでプランを検証または作成し、このサーバーと同じカタログを照合する必要があるクライアント向けです。各データは application/json 形式で、{ "mcp_version", "catalog_version", "data_version", "data" } という構造です。data はサーバーが読み込むデータファイルで、data_version はその SHA-256 の先頭 12 桁の 16 進文字列です。catalog_version は 4 つの要素すべてを合わせたデータに対する同じ種類のハッシュで、各要素で同一です。そのため、各要素を個別に読み取るクライアントは、それらが一貫した 1 つのカタログを構成していること（ローリングデプロイ中に 2 台のサーバーから取得したデータが混在していないこと）を確認できます。リソース一覧には、各エントリーの _meta に両方のバージョンが含まれるため、クライアントはキャッシュ済みのデータを読み飛ばせます。

URI	データ
tooljet://catalog/components	コンポーネントの種類、プロパティ、スタイル、イベント、アクション、サイズ設定、作成時のヒント（data/component-schemas.json）
tooljet://catalog/component-compatibility	レガシーコンポーネントの種類とその置き換え先（data/component-compatibility.json）
tooljet://catalog/datasources	すべてのデータソースの種類のクエリー仕様（data/datasource-schemas.json）
tooljet://catalog/page-icons	ページアイコンのパッケージ、バージョン、名前（data/page-icons.json）

プライバシーポリシー

このコネクターには、ToolJet のプライバシーポリシーが適用されます：tooljet.com/privacy。

開発

npm test          # vitest (unit tests, mocked HTTP)
npm run build     # tsc → dist/
npm run dev       # tsx src/index.ts (stdio server)
npm run dev:http  # tsx src/http.ts (Streamable HTTP server)
npm run generate:catalogs  # refresh component + datasource contracts from local ToolJet source

エンドポイントの実装に関する注記と、その根拠のレベルは docs/contracts.md に記載されています。現在のモック契約テストが、回帰テストの基準です。