MCP-KittoX: the MCP server

Kitto^x Enterprise feature

MCP-KittoX is part of the Kittoˣ Enterprise edition and ships together with KIDE^x. It uses the same OnGuard license file (%CSIDL_COMMON_DOCUMENTS%\Ethea\KIDEX\Registration.ini) — a single registration unlocks both. See the Feature Matrix for the full comparison with the Open-Source edition.

MCP-KittoX is a standalone executable (MCPKittoX.exe) that exposes the functionality of KIDE^x to AI agents — Claude Desktop, Claude Code, Codex, LM Studio and any other client compatible with the Model Context Protocol.

While KIDE^x remains the human-facing visual IDE, MCP-KittoX is the AI-facing design tool: agents can scaffold new applications, reverse- engineer Models from a database, generate Views and Layouts, validate metadata, and refresh translation files — all conversationally, without leaving the agent.

Why use it

• Fast onboarding: an agent can create a complete Kitto^x app scaffold ("scaffold an app named MyApp under D:\Dev with FireDAC, JWT auth and all 4 deployment modes") without you opening RAD Studio or KIDE^x.
• Assisted maintenance: ask the agent to validate the project, refresh the .po translation files, or propagate database schema changes back into the Model YAML files.
• Enterprise differentiator: pair the visual IDE with an AI tool — the same way a developer pairs an IDE with an LLM-powered code assistant.

Quick start

After installing KIDE^x Enterprise (which deploys MCPKittoX.exe to the same Bin\ folder as KIDEX.exe) and registering the OnGuard license, wire your MCP client:

Claude Desktop / Codex (STDIO transport)

%APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kittox": {
      "command": "C:\\Program Files\\Ethea\\KIDEX\\Bin\\MCPKittoX.exe",
      "args": ["--stdio", "--workspace=D:\\Dev\\KittoXProjects"]
    }
  }
}

Restart Claude Desktop. The agent will discover all the tools registered by the server (currently 9 — see the Feature Matrix below) and use them autonomously when you ask for Kitto^x development tasks.

Test the connection

MCPKittoX.exe --version

prints MCP-KittoX 4.0.7 and exits with code 0. From a JSON-RPC client (or MCPJam Inspector), invoke meta_version to verify the license check passes:

{
  "name": "MCP-KittoX",
  "version": "4.0.7",
  "build_date": "2026-05-07",
  "mcp_spec": "2025-06-18",
  "kittox_version": "4.0.7",
  "license_status": "(Trial version. Expiration days: 30)"
}

Conversational example: scaffold + reverse-engineer Models

A typical end-to-end interaction once the MCP server is wired:

You — "Scaffold a new Kitto^x app named Northwind2 under D:\Dev\Examples, then point me at the SQL Server Northwind database and generate Models for every table."

Agent —

1. Calls project_create_app (project_name Northwind2, template Basic). The wizard's defaults kick in: Auth: TextFile with the demo FileAuthenticator.txt (admin/admin), JWT envelope, AccessControl: Null.
2. Asks you to edit Home\Metadata\Config.yaml so Databases.Main points at your SQL Server (or you tell the agent how it's reachable and it edits the file via your IDE).
3. Calls project_open on the freshly-generated .kproj.
4. Calls models_create_from_db with dry_run: true and shows you the proposed action tree — typically N add_model actions and a few hundred add_field / add_reference_field sub-actions.
5. After your OK, calls models_create_from_db again with dry_run: false — this time the tool executes the actions and writes the YAML files to Home\Metadata\Models\. Returns applied: true and a summary.
6. Suggests the next step (open the project in KIDE^x or RAD Studio, run the DataView Wizard to scaffold List/Form views, or ask for it conversationally once the relevant tools are added to the next Phase).

The whole exchange runs without you opening RAD Studio or KIDE^x — the agent uses MCP-KittoX's tools the same way it would use a filesystem or a shell tool, and the resulting Models/ is identical to what the Model Wizard would have written if you'd driven it visually.

Architecture

Aspect	Implementation
Library	MCPConnect (delphi-blocks, MIT) — attribute-driven, multi-transport
Serialization	Neon (MIT) — RTTI-based JSON, snake_case field naming
Logging	Logify (MIT) — meta-logging facade
Transport (current)	STDIO (Claude Desktop, Codex)
Transport (planned)	Indy HTTP (LM Studio, web-based clients)
MCP spec	2025-06-18
Naming convention	snake_case for tool args/results, plural scope for collections (models_list), singular-typed scope for typed creators (view_grid_create)
License gate	OnGuard, shared with KIDEx; every tool method calls EnsureLicensed first; unlicensed → EKXLicenseError (EJRPCException) → JSON-RPC error visible to client

The server is a standalone executable, not embedded in your Kitto^x runtime nor inside KIDE^x. Agents talk to it; KIDE^x continues to be the human visual IDE. Both share a common headless layer so that — for instance — the models_create_from_db tool produces a Models/ folder byte-identical to what the Model Wizard writes when driven manually.

Feature Matrix

The following table tracks the implementation status of each MCP tool. Tools are organised by scope: collections use plural names (e.g. models, views) for browse/CRUD operations; typed creators use singular per-controller scopes (e.g. view_grid, view_chart) so the tool surface can grow additively without breaking changes.

Implemented (Phases 1 → 3)

Scope	Tool	Description	Status
meta	meta_version	Server identity, build date, MCP spec, license status	✅ Done
meta	meta_capabilities	Registered tool scopes + runtime feature flags (readonly, allow-update, allow-delete, workspace root)	✅ Done
meta	meta_list_metadata_templates	List the YAML templates KIDEx uses as design-time defaults	✅ Done
project	project_open	Open a Kittox project (.kproj file or Home/ folder)	✅ Done
project	project_info	Snapshot of the currently-open project	✅ Done
project	project_list_apps	List the application configs (Config.yaml variants)	✅ Done
project	project_close	Close the currently-open project	✅ Done
project	project_create_app	Generate a new app from a template (Empty / Basic), with full parametrization: DB drivers, auth + JWT envelope, access control, server settings, deployment modes (Standalone / Desktop / ISAPI / Apache), language, charset, theme. Default Auth: TextFile ships with a ready-to-use FileAuthenticator.txt so the generated app authenticates without a users table	✅ Done
models	models_create_from_db	Reverse-engineer Models from a database connection (the headless equivalent of the Model Wizard inside KIDEx). Reads the live schema, diffs it against the open project's Models/, and returns the proposed action tree. Defaults to dry_run: true (preview only); pass dry_run: false to commit. Output is byte-identical to what the visual Model Wizard would write	✅ Done

Planned (Phase 4 and beyond)

Scope	Tool	Description	Status
models	models_list	List all Models in the active project	⏳ Todo
models	models_read	Read a Model YAML by name	⏳ Todo
models	models_generate_ddl	Forward-engineer CREATE/ALTER TABLE from a Model	⏳ Todo
models	models_apply_to_db	Execute generated DDL against the database (with two-step confirmation)	⏳ Todo
models	models_update	Update an existing Model (opt-in, two-step confirmation)	⏳ Todo
models	models_patch_node	Granular edit of a single Model YAML node	⏳ Todo
models	models_delete	Delete a Model (opt-in, two-step confirmation with reference impact)	⏳ Todo
views	views_list	List all Views	⏳ Todo
views	views_read	Read a View YAML	⏳ Todo
views	views_controllers	Discovery — list creatable view controller types	⏳ Todo
views	views_update	Update an existing View (opt-in)	⏳ Todo
views	views_delete	Delete a View (opt-in, with reference check)	⏳ Todo
view_grid	view_grid_create	Scaffold a GridPanel view from a Model	⏳ Todo
view_list	view_list_create	Scaffold a List view from a Model	⏳ Todo (future)
view_grouping_list	view_grouping_list_create	Scaffold a GroupingList view	⏳ Todo (future)
view_chart	view_chart_create	Scaffold a ChartPanel view (bar/line/pie/doughnut)	⏳ Todo (future)
view_calendar	view_calendar_create	Scaffold a CalendarPanel view	⏳ Todo (future)
view_googlemap	view_googlemap_create	Scaffold a GoogleMap view	⏳ Todo (future)
view_template_data	view_template_data_create	Scaffold a TemplateDataPanel view	⏳ Todo (future)
layouts	layouts_list / read / update / delete	Layout CRUD	⏳ Todo
config	config_read	Read Config.yaml (sensitive fields auto-sanitized)	⏳ Todo
config	config_update	Update Config.yaml (opt-in)	⏳ Todo
config	config_patch_node	Granular edit	⏳ Todo
validate	validate_all	Run all validators (Config + Models + Views + Layouts)	⏳ Todo (Phase 3)
validate	validate_config / models / views / layouts	Targeted validation	⏳ Todo
locale	locale_list_languages	List .po files in Resources/locale/	⏳ Todo
locale	locale_read_po	Read a .po file	⏳ Todo
locale	locale_update_files	Run Update Locale Files headlessly: extract translatable strings from YAML metadata + Delphi sources, merge with existing .po files preserving translations	⏳ Todo (Phase 3)
db	db_list_connections	List connections defined in Config.yaml	⏳ Todo
db	db_test	Test a connection	⏳ Todo
db	db_introspect	Snapshot DB schema	⏳ Todo
db	db_list_tables	List tables of a connection	⏳ Todo
db	db_describe_table	Detailed table info (columns, PK, FK, indexes)	⏳ Todo
menu	menu_generate_main_menu	Generate Views/MainMenu.yaml from existing Models with sensible folder grouping (the placeholder folder shipped by the Basic template is meant to be filled by this tool)	⏳ Todo
resources	resources_list / read / refresh	Manage Home/Resources/ files	⏳ Todo

Safety: write operations are opt-in

By default MCPKittoX.exe exposes read tools only. Update operations require --allow-update on the command line; delete operations require --allow-delete. Delete tools further follow a two-step preview→confirm pattern: a first call with confirm: false returns the impact (would_delete, references_count, would_break: [...]); a second call with confirm: true actually executes, only if the preview is still in cache for the session.

Workspace sandboxing (--workspace=PATH) prevents path traversal outside an allowed root.

CLI flags

MCPKittoX.exe [options]

Transport:
  --stdio                 STDIO transport (default — for Claude Desktop, Codex)
  --http                  Indy HTTP transport (planned)
  --port=PORT             HTTP port (default 4000, ignored in --stdio)
  --bind=ADDRESS          HTTP bind address (default 127.0.0.1)

Project:
  --project=PATH          Project to open at startup (optional)
  --workspace=PATH        Sandbox root — projects must live underneath

Security:
  --api-key=KEY           API key required for HTTP transport
  --readonly              Disable all write tools (creates / updates / deletes)
  --allow-update          Enable *_update tools (off by default)
  --allow-delete          Enable *_delete tools (off by default)

Diagnostics:
  --log-file=PATH         Logify file destination
  --log-level=LEVEL       debug | info | warn | error (default info)
  --version               Print version and capabilities, exit

License status

When the server starts, the OnGuard license check runs. The result is:

• printed to stderr as a one-line banner (visible when running interactively):

  [LICENSE] (Trial version. Expiration days: 30)
  [LICENSE] Software registered to "Carlo Barazzetta".
  [LICENSE] Unregistered version! You must acquire license from "support@ethea.it"

• exposed in the JSON-RPC meta_version response under license_status (so an agent can read it and warn the user when expiration is approaching).

If the license is invalid, every tool method throws an EKXLicenseError that propagates through the JSON-RPC envelope as a structured error:

{"error":{"code":-32603,"message":"Unregistered version! You must acquire license from \"support@ethea.it\""},"id":2,"jsonrpc":"2.0"}

The server still answers initialize and tools/list so the client can show the tool catalog — but no tool can be invoked successfully until KIDE^x is registered.

See also

• KIDEX: the KittoX IDE — the visual IDE whose functionality MCP-KittoX exposes to AI agents; also includes the RAD Studio IDE plugin section that documents the gallery entries under File > New > Other > KittoX Projects
• New Project Wizard — the visual counterpart of project_create_app; same template engine, identical output
• Kitto Enterprise — what's included in the commercial edition
• Feature Matrix — Open Source vs Enterprise comparison
• Model Context Protocol (external) — the protocol specification
• MCPConnect (external) — the underlying Delphi MCP library