Prefect MCP Server

The Prefect MCP Server connects your AI assistant to Prefect, a popular Python tool for orchestrating data pipelines and AI workflows. Orchestration means Prefect schedules, starts and monitors runs and retries them when they fail. MCP, the Model Context Protocol, is an open standard that lets assistants such as Claude Code, Cursor or Codex work with external services. Prefect builds the server itself and publishes it on GitHub under the MIT license. It works with Prefect Cloud as well as with self-hosted Prefect servers.

What is the Prefect MCP Server good for?

Anyone running data pipelines knows the drill: a nightly run failed, a deployment will not start, or runs sit in the queue for hours. Until now, that meant clicking through the UI, the logs and the work pool settings. With the MCP server, you ask in plain language instead: Why is my deployment not running? What happened in the last failed flow run? Which work pools have no active worker right now? The assistant fetches the data itself, reads the logs and suggests a cause. Because it can also see your code in the editor, it can often fix the problem right where it started.

Tools at a glance

According to the README and the documentation, the server covers three areas. For monitoring, there is an overview of system health plus queries for deployments, flows, flow runs, task runs, work pools, automations, events and logs, each with filters. In Prefect, a flow is a Python function that runs as a workflow, and a flow run is a single execution of it. For debugging, the server offers help with failed runs and with common deployment problems such as exhausted concurrency or work pools without workers. On Prefect Cloud, it also shows how much of your API rate limit you are using. For documentation, a second MCP server is mounted that searches the current Prefect docs, including CLI and SDK examples.

Read-only by design

Every tool only reads and, according to Prefect, changes nothing in your workspace. If you want to create a deployment or rerun a flow, you let the assistant use the prefect command in the terminal or the Python SDK instead. The built-in docs search provides the current syntax for that. Prefect itself points out that an assistant with terminal access can run such commands without the MCP server. If you want to prevent that, higher plans let you use a service account with read-only permissions.

Local or hosted

Locally, the server starts with uvx, a tool that runs Python programs without installing them first. It then picks up the active Prefect profile on your machine or the environment variables PREFECT_API_URL and PREFECT_API_KEY. For self-hosted servers with basic auth, there is PREFECT_API_AUTH_STRING. As an alternative, Prefect runs a hosted server with OAuth sign-in. OAuth is a method where you approve access in the browser without handing over a key. There you choose which workspaces the assistant may read. Teams can also run the server themselves on Prefect Horizon and keep the credentials in one place.

Clients

For Claude Code and Codex, Prefect offers a plugin from its own marketplace that uses the hosted server. Claude has a connector and ChatGPT a plugin. For Cursor, VS Code, Windsurf, Kiro and the Gemini CLI, the documentation describes the local route via uvx.

Cost

The server itself is open source and free. For Prefect Cloud, the pricing page lists a free Hobby tier, paid plans and enterprise tiers. Service accounts for unattended agents require one of the higher plans. If you run Prefect yourself, you pay Prefect nothing.

Who is the Prefect MCP Server for?

It suits data engineers, ML teams and platform owners who already use Prefect and want to troubleshoot faster. Prefect still labels the server as beta, so features may change. Because it only reads, the everyday risk is modest, and getting started takes a few minutes.

A Prefect Cloud workspace or a self-hosted Prefect server. For the local route, uv with uvx plus a Prefect profile or the environment variables PREFECT_API_URL and PREFECT_API_KEY or PREFECT_API_AUTH_STRING. For the hosted route, a Prefect Cloud account and a client that supports remote servers and OAuth.

With the Prefect MCP Server, your AI assistant reads deployments, flow runs, work pools and logs straight from Prefect. The server is official, open source and strictly read-only. This guide shows the three setup routes and gives tips for everyday troubleshooting.

Requirements

You need a workspace in Prefect Cloud or a self-hosted Prefect server. For the local route, uv must be installed, because the server starts via uvx. If you already use Prefect on your machine, you usually have an active profile that the server picks up automatically.

Route 1: Plugin for Claude Code and Codex

The plugin is the quickest way in. In Claude Code, enter /plugin marketplace add prefecthq/prefect-mcp-server and then /plugin install prefect. In Codex, the commands are codex plugin marketplace add prefecthq/prefect-mcp-server and codex plugin add prefect@prefect. The plugin uses Prefect's hosted server. On first use, you sign in to Prefect Cloud and pick the workspaces the assistant may read. Your local profile is not used.

Route 2: Locally with uvx

For self-hosted Prefect or your own credentials, run the server locally. In Claude Code, claude mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server is enough. Without further settings, the server uses your active Prefect profile. For a specific Cloud workspace, add -e PREFECT_API_URL=… and -e PREFECT_API_KEY=… before the double dash. You will find the account and workspace IDs in the Prefect Cloud address bar. For your own server with basic auth, use PREFECT_API_AUTH_STRING instead of the API key. In Codex, the command is codex mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server, and in Cursor you add an entry to .cursor/mcp.json with command uvx and the arguments --from, prefect-mcp and prefect-mcp-server.

Route 3: Hosted for the team

Teams can run their own copy of the repository on Prefect Horizon. You store the credentials once on the server, and everyone connects with claude mcp add prefect --transport http and the address of that server.

First questions

Start with questions such as: Why is my deployment not running? Investigate the last failed flow run. Why are my runs starting late? Which work pools have no active worker? The assistant reads states and logs and names a likely cause.

Work safely

The server changes nothing. An assistant with terminal access can still run prefect commands on its own, though. For unattended agents, a service account with read-only permissions is the better choice. If you use the plugin and a local server side by side, give the local one its own name such as prefect-local and have the assistant check with get_identity which workspace is active.

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

Locally through the active Prefect profile or the environment variables PREFECT_API_URL and PREFECT_API_KEY, and PREFECT_API_AUTH_STRING for self-hosted servers. Hosted through OAuth with your Prefect Cloud account, without an API key, where you pick the workspaces you allow.

Read-only: deployments, flows, flow runs, task runs, work pools, automations, events, logs and, on Prefect Cloud, rate limit usage, plus the public Prefect documentation. According to Prefect, the server changes no resources and only sees what the account in use is allowed to see.

Locally, the server runs on your machine and talks directly to your Prefect API. On the hosted route, queries go through Prefect's server, and Prefect's privacy policy and terms apply. Logs and run data that end up in the chat also reach the client's AI provider.

Low to medium. The server itself only reads, but logs may contain credentials or internal data that end up in the chat. An assistant with terminal access can run prefect commands independently of the server. Use a read-only service account for agents and check with get_identity which workspace the server points to before acting.