The Prefect MCP server is currently in alpha. APIs, features, and behaviors may change without notice. We encourage you to try it out and provide feedback through GitHub issues.
What is the Prefect MCP server?
The Prefect MCP server is an MCP server that provides AI assistants with tools to:- Monitor & inspect: View system health, query deployments, flow runs, task runs, work pools, and execution logs
- Debug intelligently: Get contextual guidance for troubleshooting failed flows and deployment issues
- Access documentation: Query up-to-date Prefect documentation through an integrated docs proxy
prefect
CLI.
Installation
Local installation
Install and run the MCP server locally usinguvx
:
~/.prefect/profiles.toml
).
Cloud deployment
Deploy the MCP server to FastMCP Cloud for remote access:- Fork the prefect-mcp-server repository on GitHub
- Sign in to fastmcp.cloud
-
Create a new server pointing to your fork:
- Server path:
src/prefect_mcp_server/server.py
- Requirements:
pyproject.toml
(or leave blank)
- Server path:
-
Configure environment variables in the FastMCP Cloud interface:
Environment Variable Prefect Cloud Self-hosted Prefect PREFECT_API_URL
https://api.prefect.cloud/api/
accounts/[ACCOUNT_ID]/
workspaces/[WORKSPACE_ID]
Your Prefect server URL (e.g., http://your-server:4200/api
)PREFECT_API_KEY
Your Prefect Cloud API key Not used PREFECT_API_AUTH_STRING
Not used Your authentication string (if using basic auth) -
Get your server URL (e.g.,
https://your-server-name.fastmcp.app/mcp
)
When deploying to FastMCP Cloud, you must provide credentials via environment variables since the server has no access to your local Prefect configuration.
Client setup
Configure your AI assistant to connect to the Prefect MCP server.General setup
All MCP clients need three pieces of information to connect to the Prefect MCP server:- Command:
uvx
- Arguments:
--from prefect-mcp prefect-mcp-server
- Environment variables (optional): Credentials for your Prefect instance
Claude Code
Claude Code
Add the Prefect MCP server to Claude Code using the CLI:
Cursor
Cursor
Add the Prefect MCP server to Cursor by creating or editing To use explicit credentials, add an
.cursor/mcp.json
in your project:env
section:Codex CLI
Codex CLI
Add the Prefect MCP server to Codex using the CLI:Alternatively, edit
~/.codex/config.toml
directly:Credentials configuration
The Prefect MCP server authenticates with your Prefect instance using the same configuration as the Prefect SDK.Default behavior
When running locally without environment variables, the server inherits credentials from your active Prefect profile:- Profile configuration:
~/.prefect/profiles.toml
- Uses the same API URL and authentication as your current
prefect
CLI commands
Environment variables
Override the default credentials by setting environment variables: For Prefect Cloud:Find your account ID and workspace ID in your Prefect Cloud browser URL:
https://app.prefect.cloud/account/[ACCOUNT-ID]/workspace/[WORKSPACE-ID]/dashboard
Credential precedence
Environment variables take precedence over profile settings:- Environment variables (
PREFECT_API_URL
,PREFECT_API_KEY
) - Active Prefect profile (
~/.prefect/profiles.toml
)
Available capabilities
The Prefect MCP server provides these main capabilities:Monitoring & inspection
- View dashboard overviews with flow run statistics and work pool status
- Query deployments, flow runs, task runs, and work pools with advanced filtering
- Retrieve detailed execution logs from flow runs
- Track events across your workflow ecosystem
- Review automations and their configurations
Orchestration & actions
- Trigger deployment runs with custom parameters and tags
- Pass dynamic configurations to workflows at runtime
Intelligent debugging
- Get contextual guidance for troubleshooting failed flow runs
- Diagnose deployment issues including concurrency problems
- Identify root causes of workflow failures
- Analyze rate limiting issues (Prefect Cloud only)
Documentation access
The MCP server includes a built-in docs proxy that provides AI assistants with up-to-date information from the Prefect documentation. This enables your AI assistant to:- Look up current API syntax and usage patterns
- Find the correct
prefect
CLI commands for creating and updating resources - Access the latest best practices and examples
Prompting tips
To get the most out of the Prefect MCP server, guide your AI assistant with these patterns:Use the prefect CLI for write operations
The MCP tools are optimized for reading and monitoring. For creating or updating resources, prompt your assistant to use theprefect
CLI:
Example prompts:
- “Use the
prefect
CLI to create a new deployment” - “Show me how to update this deployment’s schedule using
prefect
” - “Create an automation using the
prefect
CLI”
Leverage the docs proxy
The integrated docs proxy gives your assistant access to current Prefect documentation: Example prompts:- “Look up the latest syntax for creating a work pool”
- “Find documentation on how to configure Docker work pools”
- “What are the current best practices for deployment configuration?”
Ask diagnostic questions
The MCP server excels at helping diagnose issues: Example prompts:- “Why is my deployment not running?”
- “Debug the last failed flow run”
- “Why are my flow runs delayed?”
- “Show me which work pools have no active workers”