How to use the Prefect MCP server

The Prefect MCP server enables AI assistants to interact with your Prefect workflows and infrastructure through the Model Context Protocol (MCP). This integration allows AI tools like Claude Code, Cursor, and Codex CLI to help you monitor deployments, debug flow runs, query infrastructure, and more.

The Prefect MCP server is currently in beta. 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

The MCP tools are primarily designed for reading data and monitoring your Prefect instance. For creating or updating resources, the integrated docs proxy provides AI assistants with current information on how to use the prefect CLI.

Security considerations

The Prefect MCP server provides read-only access to your Prefect instance. It can only access information available to the account you authenticate with—it cannot access data outside those bounds.

Important: The MCP server does not operate in isolation. MCP clients (such as Claude Code, Cursor, or Codex CLI) may have additional capabilities beyond the MCP server’s read-only tools. For example, an AI assistant with terminal access could execute destructive CLI commands like prefect deployment delete independently of the MCP server.When using AI agents autonomously, consider the Prefect Role associated with your API key and what actions the agent could take through other means (CLI, SDK, etc.).

For detailed answers to common security questions—including authentication patterns, RBAC, file access requirements, and recommendations for internal pilots—see the Security FAQ.

Quick start

The fastest way to get started depends on your AI assistant:

Claude Code

Recommended: Use the marketplace

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

This installs both the MCP server and a CLI skill for working with Prefect.Alternative: Manual setup

# Uses your local Prefect profile from ~/.prefect/profiles.toml
claude mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

Cursor

Add this configuration to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"]
    }
  }
}

Codex CLI

codex mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

Gemini CLI

gemini mcp add prefect uvx --from prefect-mcp prefect-mcp-server

Test your setup

Once configured, try these prompts to verify the connection:

“Show me my recent flow runs”
“What deployments are available?”
“Debug my last failed flow run”

Installation options

Local installation (stdio transport)

The default setup runs the MCP server locally using uvx. The server automatically inherits credentials from your active Prefect profile:

uvx --from prefect-mcp prefect-mcp-server

Credentials: Uses ~/.prefect/profiles.toml by default

Cloud deployment (HTTP transport)

Deploy the MCP server to FastMCP Cloud for remote access from any client:

Fork the repository

Fork the prefect-mcp-server repository on GitHub

Deploy to FastMCP Cloud

Sign in to fastmcp.cloud
Create a new server pointing to your fork
Configure:
- Server path: src/prefect_mcp_server/server.py
- Requirements: pyproject.toml (or leave blank)

Set environment variables

Configure credentials 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 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)

Find your account ID and workspace ID in your Prefect Cloud browser URL: https://app.prefect.cloud/account/[ACCOUNT-ID]/workspace/[WORKSPACE-ID]/dashboard

Get your server URL

Copy the generated URL (e.g., https://your-server-name.fastmcp.app/mcp) and use it in your client configuration

When deploying to FastMCP Cloud, environment variables are configured on the FastMCP Cloud server itself, not in your client configuration. FastMCP’s authentication secures access to your MCP server, while the MCP server uses your Prefect API key to access your Prefect instance.

Prefect Cloud users on Team, Pro, and Enterprise plans can use service accounts for API authentication. Pro and Enterprise users can restrict service accounts to read-only access (only see_* permissions) since the Prefect MCP server requires no write permissions.

Client configuration

Configuration basics

All MCP clients need these components to connect:

Command: uvx
Arguments: --from prefect-mcp prefect-mcp-server
Environment variables (optional): Explicit Prefect credentials

The configuration format varies by client. See detailed setup instructions below:

Claude Code

Marketplace (Recommended)
Manual CLI Setup

The easiest way to install:

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

This installs both the MCP server (for read-only diagnostics) and a CLI skill (for mutations like triggering deployments or cancelling runs).

The plugin uses your local Prefect configuration from ~/.prefect/profiles.toml. For explicit credentials, use the manual CLI setup.

Local (stdio):

# Uses credentials from ~/.prefect/profiles.toml
claude mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

With explicit Prefect Cloud credentials:

claude mcp add prefect \
  -e PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  -e PREFECT_API_KEY=your-cloud-api-key \
  -- uvx --from prefect-mcp prefect-mcp-server

With FastMCP Cloud (HTTP):

claude mcp add prefect --transport http https://your-server-name.fastmcp.app/mcp

Cursor

Basic Setup
With Explicit Credentials
HTTP Transport (FastMCP)

Create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"]
    }
  }
}

Uses credentials from ~/.prefect/profiles.toml

Add environment variables to the configuration:

{
  "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-cloud-api-key"
      }
    }
  }
}

For FastMCP Cloud deployments:

{
  "mcpServers": {
    "prefect": {
      "httpUrl": "https://your-server-name.fastmcp.app/mcp"
    }
  }
}

Codex CLI

CLI Setup
Config File

Basic setup:

# Uses credentials from ~/.prefect/profiles.toml
codex mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

With explicit Prefect Cloud credentials:

codex mcp add prefect \
  --env PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  --env PREFECT_API_KEY=your-cloud-api-key \
  -- uvx --from prefect-mcp prefect-mcp-server

Edit ~/.codex/config.toml:Basic setup:

[mcp.prefect]
command = "uvx"
args = ["--from", "prefect-mcp", "prefect-mcp-server"]

With explicit credentials:

[mcp.prefect]
command = "uvx"
args = ["--from", "prefect-mcp", "prefect-mcp-server"]

[mcp.prefect.env]
PREFECT_API_URL = "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]"
PREFECT_API_KEY = "your-cloud-api-key"

Gemini CLI

CLI Setup
Config File

Basic setup (stdio):

gemini mcp add prefect uvx --from prefect-mcp prefect-mcp-server

With explicit Prefect Cloud credentials:

gemini mcp add prefect \
  -e PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  -e PREFECT_API_KEY=your-cloud-api-key \
  uvx --from prefect-mcp prefect-mcp-server

HTTP transport (FastMCP Cloud):

gemini mcp add prefect --transport http https://your-server-name.fastmcp.app/mcp

Edit ~/.gemini/settings.json:Basic setup (stdio):

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"]
    }
  }
}

With explicit credentials:

{
  "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-cloud-api-key"
      }
    }
  }
}

HTTP transport (FastMCP Cloud):

{
  "mcpServers": {
    "prefect": {
      "httpUrl": "https://your-server-name.fastmcp.app/mcp"
    }
  }
}

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:

PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]
PREFECT_API_KEY=your-cloud-api-key

For self-hosted Prefect with basic auth:

PREFECT_API_URL=http://your-server:4200/api
PREFECT_API_AUTH_STRING=your-auth-string

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 the prefect 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”

​What is the Prefect MCP server?

​Security considerations

​Quick start

​Test your setup

​Installation options

​Local installation (stdio transport)

​Cloud deployment (HTTP transport)

​Client configuration

​Configuration basics

​Credentials configuration

​Default behavior

​Environment variables

​Credential precedence

​Available capabilities

​Monitoring & inspection

​Orchestration & actions

​Intelligent debugging

​Documentation access

​Prompting tips

​Use the prefect CLI for write operations

​Leverage the docs proxy

​Ask diagnostic questions

​Learn more

What is the Prefect MCP server?

Security considerations

Quick start

Test your setup

Installation options

Local installation (stdio transport)

Cloud deployment (HTTP transport)

Client configuration

Configuration basics

Credentials configuration

Default behavior

Environment variables

Credential precedence

Available capabilities

Monitoring & inspection

Orchestration & actions

Intelligent debugging

Documentation access

Prompting tips

Use the prefect CLI for write operations

Leverage the docs proxy

Ask diagnostic questions

Learn more