Add a kizen mcp-servers command group

CHANGELOG.md

@@ -14,6 +14,12 @@ called out explicitly under **Changed** or **Removed**.
 
 ## [Unreleased]
 
+### Added
+
+- **`kizen mcp-servers`** lists, creates, updates and deletes MCP servers
+  from a spec, checks tool names against the live catalogue, and shows a
+  server's tools and change history.
+
 ## [0.3.0] — 2026-10-21
 
 ### Changed

CONTRIBUTING.md

@@ -107,6 +107,7 @@ src/kizen_builder/
     files.py                     #   raw file bytes: the S3 upload/download legs (not JSON)
     forms.py                     #   form/survey CRUD (base_path-shared with surveys)
     layouts.py                   #   record-layout CRUD (field/block arrangement)
+    mcp_servers.py               #   MCP server CRUD, tool catalogue, events history
     messages.py                  #   automation-scoped message resources (notify_* step content)
     permissions.py               #   roles, permission groups, permissions catalog
     pipelines.py                 #   pipeline-stage CRUD + record stage-move
@@ -125,6 +126,7 @@ src/kizen_builder/
     form_ui.py                   #   build a form/survey's visual, submittable page layout
     forms.py                     #   list/get forms and surveys (base_path-shared)
     layouts.py                   #   list/get, block helpers, inject_layout_ids
+    mcp_servers.py               #   resolve/list/get MCP servers, tool catalogue, history
     messages.py                  #   automation message content (notify_* step templates)
     objects.py                   #   list_objects(), get_object(api_name)
     permission_builder.py        #   enumerate/build/mutate the full permission-group structure
@@ -159,6 +161,7 @@ src/kizen_builder/
       fields.py                  #     plan_create_field, plan_update_field
       forms.py                   #     plan_create/update/delete forms/surveys + fields
       layouts.py                 #     plan_update_layout
+      mcp_servers.py             #     plan_create/update/delete MCP servers
       messages.py                #     plan_create automation message content
       objects.py                 #     plan_create/update_object, plan_create/update_category
       permissions.py             #     plan_create/update/delete roles + permission groups
@@ -170,6 +173,7 @@ src/kizen_builder/
   translate.py                   # Automation GET → PUT wire translation.
   models/spec/                   # Pydantic shapes for desired state (spec inputs);
                                   #   package, one module per cluster — see __init__.py.
+    mcp_servers.py               #   MCPServerDef + its sharing block
   output.py                      # Shared table/json/csv output layer for read commands.
   cli/                           # Typer wrappers around tools/. The `kizen` command.
     __init__.py                  #   exports `app`; imports every module below, IN ORDER
@@ -203,6 +207,7 @@ src/kizen_builder/
     forms_fields.py              #   …and its `fields` / `fields options` sub-apps
     automations_write.py         #   kizen automations — create/update/lifecycle
     folders.py                   #   kizen automations folders
+    mcp_servers.py               #   kizen mcp-servers
     apply.py                     #   kizen apply
     smart_connectors.py          #   kizen smart-connectors — app, shared helpers, build/configure
     smart_connectors_seeds.py    #   kizen smart-connectors seeds

src/kizen_builder/api/mcp_servers.py

@@ -0,0 +1,59 @@
+"""MCP server configuration against the Kizen API.
+
+An MCP server is a named set of Kizen tools that AI steps and outside MCP
+clients call. This module configures servers; it does not call one. A server's
+``endpoint_url`` (``/api/mcp/{api_name}``) is the JSON-RPC endpoint MCP clients
+use at run time, and nothing here touches it.
+
+Endpoints:
+  GET    /api/mcp-servers                      list servers (DRF page)
+  POST   /api/mcp-servers                      create
+  GET    /api/mcp-servers/{id}                 one server, incl. its tools
+  PATCH  /api/mcp-servers/{id}                 partial update
+  DELETE /api/mcp-servers/{id}                 hard delete (204)
+  GET    /api/mcp-servers/tools                the tool catalogue, by group
+  GET    /api/mcp-servers/{id}/events-history  change history (DRF page)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kizen_builder.api.client import KizenClient
+
+
+def list_mcp_servers(client: KizenClient) -> list[dict[str, Any]]:
+    """GET /api/mcp-servers — every server, with ``tool_count`` and no ``tools``."""
+    return client.paginate("/api/mcp-servers")
+
+
+def get_mcp_server(client: KizenClient, server_id: str) -> dict[str, Any]:
+    """GET /api/mcp-servers/{id} — one server, with ``tools`` expanded."""
+    return client.get(f"/api/mcp-servers/{server_id}")
+
+
+def create_mcp_server(client: KizenClient, payload: dict[str, Any]) -> dict[str, Any]:
+    """POST /api/mcp-servers — returns the created server's read shape."""
+    return client.post("/api/mcp-servers", json=payload)
+
+
+def update_mcp_server(
+    client: KizenClient, server_id: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    """PATCH /api/mcp-servers/{id} — only the supplied keys change."""
+    return client.patch(f"/api/mcp-servers/{server_id}", json=payload)
+
+
+def delete_mcp_server(client: KizenClient, server_id: str) -> None:
+    """DELETE /api/mcp-servers/{id}."""
+    client.delete(f"/api/mcp-servers/{server_id}")
+
+
+def get_tool_catalog(client: KizenClient) -> dict[str, Any]:
+    """GET /api/mcp-servers/tools — ``{groups: [{key, label, tools: [...]}]}``."""
+    return client.get("/api/mcp-servers/tools")
+
+
+def list_events_history(client: KizenClient, server_id: str) -> list[dict[str, Any]]:
+    """GET /api/mcp-servers/{id}/events-history — written a second or so after a change."""
+    return client.paginate(f"/api/mcp-servers/{server_id}/events-history")

src/kizen_builder/cli/__init__.py

@@ -52,6 +52,7 @@
 from kizen_builder.cli import forms  # noqa: F401
 from kizen_builder.cli import automations_write  # noqa: F401
 from kizen_builder.cli import folders  # noqa: F401
+from kizen_builder.cli import mcp_servers  # noqa: F401
 from kizen_builder.cli import apply  # noqa: F401
 from kizen_builder.cli import smart_connectors  # noqa: F401
 from kizen_builder.cli import smart_connectors_seeds  # noqa: F401