MCP Server for ZenML

This project implements a Model Context Protocol (MCP) server for interacting with the ZenML API.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It acts like a "USB-C port for AI applications" - providing a standardized way to connect AI models to different data sources and tools.

MCP follows a client-server architecture where:

• MCP Hosts: Programs like Claude Desktop or IDEs that want to access data through MCP
• MCP Clients: Protocol clients that maintain 1:1 connections with servers
• MCP Servers: Lightweight programs that expose specific capabilities through the standardized protocol
• Local Data Sources: Your computer's files, databases, and services that MCP servers can securely access
• Remote Services: External systems available over the internet that MCP servers can connect to

What is ZenML?

ZenML is an open-source platform for building and managing ML and AI pipelines. It provides a unified interface for managing data, models, and experiments.

For more information, see the ZenML website and our documentation.

Features

The server provides MCP tools to access core read functionality from the ZenML server, providing a way to get live information about:

Core Entities

• Users - user accounts and permissions
• Stacks - infrastructure configurations
• Stack Components - individual stack building blocks
• Flavors - available component types
• Service Connectors - cloud authentication

Pipeline Execution

• Pipelines - pipeline definitions
• Pipeline Runs - execution history and status
• Pipeline Steps - individual step details, code, and logs
• Schedules - automated run schedules
• Artifacts - metadata about data artifacts (not the data itself)

Deployment & Serving

• Snapshots - frozen pipeline configurations (the "what to run/serve" artifact)
• Deployments - runtime serving instances with status, URL, and logs
• Services - model serving endpoints

Organization & Discovery

• Projects - organizational containers for ZenML resources
• Tags - cross-cutting metadata labels for discovery
• Builds - pipeline build artifacts with image and code info

Models

• Models - ML model registry entries
• Model Versions - versioned model artifacts

Compatibility APIs (migration recommended)

• Pipeline run templates remain available in ZenML 0.96.4, while Snapshots are preferred for new workflows (see Migration Guide)

The server also allows you to trigger new pipeline runs using snapshots (preferred) or the deprecated template-based trigger parameter.

Note: We're continuously improving this integration based on user feedback. Please join our Slack community to share your experience and help us make it even better!

Tool profiles and write policy

The default compact profile advertises 16 tools. Seven generic tools cover the resource catalog, reads, ordinary mutations, and finite lifecycle actions:

| Tool | Purpose | |------|---------| | zenml_describe_resources | Discover supported resource types and bounded operation schemas | | zenml_list_resources | List one resource type with validated filters and pagination | | zenml_get_resource | Get one resource, with parent and project scope where required | | zenml_create_resource | Create a supported resource from a typed payload | | zenml_update_resource | Update one exact resource UUID | | zenml_delete_resource | Delete or archive one exact resource UUID | | zenml_action_resource | Run an allowlisted lifecycle or relation action without retries |

Nine focused tools remain because they provide diagnostics, active context, streamed logs or code, pipeline execution, or an interactive App:

• diagnose_zenml_setup
• get_active_user and get_active_project
• trigger_pipeline
• get_step_logs, get_step_code, and get_deployment_logs
• open_pipeline_run_dashboard and open_run_activity_chart

Use ZENML_MCP_PROFILE=legacy when an existing client still depends on the old entity-specific names such as list_pipeline_runs. This retains the characterized tool-name and schema compatibility layer for ZenML 0.96.4. It does not add support for older ZenML server versions. Use it only while migrating: legacy response shapes may expose more operational metadata than the compact tools, although the server omits credential-bearing configuration and other sensitive fields from both profiles.

Registration and write access are independent:

| Profile | Policy | Advertised tools | |---------|--------|-----------------:| | compact | read_write | 16 | | compact | read_only | 11 | | legacy | read_write | 57 | | legacy | read_only | 52 |

Set ZENML_MCP_WRITE_POLICY=read_only to remove all four generic mutation tools and trigger_pipeline from MCP discovery and dispatch. Resource discovery also omits create, update, delete, and action schemas. The older ZENML_MCP_READ_ONLY=true setting remains accepted; invalid policy values fail closed to read-only mode. An invalid ZENML_MCP_PROFILE stops startup with a configuration error.

Version 2.0.0 requires MCP Python SDK 2.2.0 and ZenML 0.96.4. The compact profile is the new default and is a breaking discovery change for clients that call entity-specific tool names. Set ZENML_MCP_PROFILE=legacy while migrating those clients, then move each call to the generic resource tools.

Mutation results distinguish completed, accepted, and unknown outcomes. The server does not retry a mutation after it may have reached ZenML. For an accepted or unknown result, follow the reconciliation instructions in the response before deciding whether to call again. Use the named read when one is available. Webhook creation and secret rotation can return a new signing secret once; later reads omit it. Delete schemas state whether an operation archives metadata, removes metadata, deprovisions a live resource, or can delete stored artifact data.

The first 2.0 release covers ordinary operations for projects, stacks and components, flavors, services, pipelines and runs, snapshots and templates, deployments, artifacts and versions, models and versions, tags, connectors, code repositories, webhooks, triggers, wait conditions, and hook invocations. Users, schedules, service connector types, secrets, and resource requests have the read-only coverage shown by zenml_describe_resources. It excludes ZenML Cloud control-plane administration, Resource Manager administration, user and credential administration, secret-value CRUD, connector login and verification, raw webhook events, and aggregate debugging or lineage tools.

Start a generic workflow by discovering the precise schema, then calling it:

zenml_describe_resources(resource_type="pipeline_run", operation="list")
zenml_list_resources(
    resource_type="pipeline_run",
    filters={"status": "completed", "sort_by": "desc:created"},
    page=1,
    size=10,
)

Prompts and resources remain available in both profiles. The analysis prompts, the bounded resource-schema endpoints, and most_recent_runs are MCP prompts or resources rather than tools.

Run-template compatibility

ZenML 0.96.4 retains run-template CRUD APIs. Snapshots are preferred for new workflows. Pipeline convenience creation and the template-based trigger parameter are deprecated. In the legacy profile, get_run_template and list_run_templates remain available for existing clients.

The legacy tag input remains in list_run_templates for schema compatibility, but ZenML 0.96.4 has no equivalent server-side filter. A non-null value is rejected before the SDK call. Snapshot tag filtering remains available.

Migration: Run Templates → Snapshots

Why the change? Snapshots replaced run templates as ZenML's preferred runnable pipeline artifact. The 0.96.4 SDK still supports run-template CRUD, while new code should use snapshots.

Quick Migration Guide

| Legacy Pattern (Templates) | Compact Pattern (Snapshots) | |----------------------------|-----------------------------| | list_run_templates() | zenml_list_resources(resource_type="snapshot", filters={"runnable": true, "named_only": true}) | | get_run_template(name) | zenml_get_resource(resource_type="snapshot", resource_id=id) | | trigger_pipeline(template_id=...) | trigger_pipeline(snapshot_name_or_id=...) |

Example Workflow (Snapshot-First)

1. Discover project context:
   → get_active_project()

2. Find runnable snapshots:
   → zenml_list_resources(resource_type="snapshot", filters={"runnable": true, "named_only": true})

3. Trigger a run:
   → trigger_pipeline(snapshot_name_or_id="my-snapshot")

4. Check deployments:
   → zenml_list_resources(resource_type="deployment", filters={"status": "running"})
   → get_deployment_logs(name_id_or_prefix="my-deployment", tail=100)

Note: get_deployment_logs returns bounded output (default 100 lines, max 1000, capped at 100KB) and requires the appropriate deployer integration to be installed.

Quick Setup via Dashboard (Recommended)

The easiest way to set up the ZenML MCP Server is through your ZenML dashboard's MCP Settings page.

Navigate to Settings → MCP in your ZenML dashboard to get:

• Pre-configured snippets for your specific server URL and credentials
• One-click installation via deep links for supported IDEs
• Copy-paste configurations for VS Code, Claude Desktop, Cursor, Claude Code, OpenAI Codex, and more
• Docker and uv options based on your preference

ZenML Pro Users

The MCP Settings page lets you generate a Personal Access Token (PAT) with a single click. The token is automatically included in all generated configuration snippets.

ZenML OSS Users

1. First create a service account token via Settings → Service Accounts
2. Paste the token into the MCP Settings page
3. Copy the generated configuration for your IDE

---

Prefer manual setup? See the detailed instructions below.

MCP Apps (Experimental)

What are MCP Apps? MCP Apps are interactive HTML UIs that MCP servers can serve directly into AI clients. They render in sandboxed iframes and can call server tools bidirectionally. See the official announcement for full details.

This server includes two experimental MCP Apps:

| App | Tool | Description | |-----|------|-------------| | Pipeline Runs Dashboard | open_pipeline_run_dashboard | Interactive table of recent pipeline runs with status, step details, and logs | | Run Activity Chart | open_run_activity_chart | Bar chart of pipeline run activity over the last 30 days with status breakdown |

These apps are included as proof-of-concept examples. We welcome feedback and contributions for more MCP Apps. It is still early days for this new feature so we'll have to see how it evolves. We expect to support it more fully in the future.

Supported Clients

MCP Apps require Streamable HTTP transport (not stdio). The following clients currently support MCP Apps:

• ✅ VS Code (Insiders Edition)
• ✅ Goose
• ✅ ChatGPT (launching soon)
• ⚠️ Claude Desktop -- as of late January 2026, doesn't yet render Apps.
• ⚠️ Claude.ai (web) — as of late January 2026, doesn't yet rende