Prefect MCP Server

Official Prefect MCP server for monitoring and debugging workflow orchestration: flow runs, deployments, task runs, work pools, logs, events, and automations.

Automation by Prefect API Key active

GitHub Docs

Overview

The Prefect MCP server is an experimental, officially maintained Model Context Protocol server from Prefect that lets AI assistants inspect and debug Prefect workflow orchestration resources. It exposes read-only access to dashboards, flow runs, task runs, deployments, work pools, logs, events, and automations, so agents like Claude Code, Cursor, and Codex CLI can answer questions about the state of your orchestration platform and help diagnose failures.

The server is built on FastMCP and runs against either Prefect Cloud or a self-hosted Prefect OSS server. Authentication is handled via standard Prefect environment variables (PREFECT_API_URL, PREFECT_API_KEY, PREFECT_API_AUTH_STRING), or via per-request HTTP headers for multi-tenant deployments. The tools are read-only by design: for create or update operations, the documentation directs users to the prefect CLI or Python SDK, which AI assistants can invoke separately.

Notable capabilities include a Cloud-only review_rate_limits tool for diagnosing API throttling, an orientation tool that primes the agent with usage guidance, and a get_object_schema tool that returns JSON schemas (currently for automations) so agents can construct valid payloads when working with the CLI or SDK.

Tools

Tool	Description
`orientation`	Returns guidance on how to use the Prefect MCP server and what it can do.
`get_identity`	Returns the configured API URL, instance type (Cloud or OSS), and user info for the current connection.
`get_dashboard`	High-level overview including flow run statistics, work pool status, and concurrency limits.
`get_deployments`	Fetches deployments with optional filtering. Returns compact or detailed summaries.
`get_flows`	Lists flows registered in the workspace with optional filter support.
`get_flow_runs`	Retrieves flow runs with filtering by state, tags, and deployment.
`get_flow_run_logs`	Returns execution logs for a specified flow run with timestamps and log levels.
`get_task_runs`	Queries task runs including dependency tracking information.
`get_work_pools`	Returns work pool details including status, concurrency limits, and worker counts.
`read_events`	Filters and retrieves events from the Prefect instance by type and time range.
`get_automations`	Fetches automations with trigger and action configuration details.
`get_object_schema`	Provides JSON schemas for complex Prefect objects (currently supports 'automation').
`review_rate_limits`	Cloud-only. Analyzes API rate limit usage, identifying throttled operation groups and time periods.

Setup Guide

Prerequisites

A Prefect Cloud account with an API key, or a running Prefect OSS server
An MCP-compatible client (Claude Code, Claude Desktop, Cursor, Codex CLI, etc.)
uv / uvx installed for the local setup option

Option 1: Claude Code plugin (recommended)

/plugin marketplace add prefecthq/prefect-mcp-server
/plugin install prefect

Option 2: Add to Claude Code via uvx

claude mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

Option 3: Manual config (Claude Desktop / Cursor)

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

Environment variables

PREFECT_API_URL: Prefect Cloud workspace URL or OSS server URL
PREFECT_API_KEY: API key for Prefect Cloud
PREFECT_API_AUTH_STRING: Basic auth string for self-hosted OSS deployments

Multi-tenant headers

For hosted deployments you can pass credentials per request via headers (these take precedence over env vars):

X-Prefect-Api-Url
X-Prefect-Api-Key
X-Prefect-Api-Auth-String

Use Cases

Triage failed flow runs by pulling logs, task run history, and related events, then asking the agent to identify the root cause
Generate a daily standup summary of flow run health, deployment activity, and work pool status from get_dashboard and get_flow_runs
Diagnose Prefect Cloud API throttling using review_rate_limits to identify which operation groups are exceeding limits
Audit existing automations and their triggers/actions before changes, using get_automations plus get_object_schema
Investigate worker or infrastructure issues by querying get_work_pools and correlating with recent events via read_events

Example Prompts

"Show me all flow runs that failed in the last 24 hours and pull the logs for the most recent failure."
"Give me a dashboard overview of my Prefect workspace: how many flows are running, queued, and failed?"
"Are any of my work pools at their concurrency limit? Which workers are online?"
"Review my Prefect Cloud rate limits over the past week and tell me which API groups are getting throttled."
"List all automations in this workspace and explain what each one triggers on."

Pros

Officially maintained by Prefect (PrefectHQ org), so it tracks the API closely
Comprehensive read coverage of Prefect resources: flows, runs, deployments, work pools, logs, events, automations
Multiple install paths including a Claude Code plugin and a hosted FastMCP Cloud deployment
Supports both Prefect Cloud and self-hosted OSS, with per-request header auth for multi-tenant setups

Limitations

Read-only: creating or modifying resources requires falling back to the prefect CLI or Python SDK
Explicitly marked experimental with APIs subject to change
No MCP prompts or resources defined, only tools, so workflow templates must be supplied by the user

Alternatives

allen-munsch/mcp-prefect: community Prefect MCP server with broader CRUD coverage across artifacts, blocks, deployments, and flows
fortunto2/prefect-mcp-server: community MCP server focused on Prefect API interaction
Prefect CLI invoked directly by an AI agent through a shell/bash MCP tool, for write operations not covered by the official server