prefect-mcp-server

[!WARNING] This project is under active development and may change drastically at any time.

This is an experimental MCP server for Prefect. APIs, features, and behaviors are subject to change without notice. We encourage you to try it out, provide feedback, and contribute. Please create issues or open PRs with your ideas and suggestions.

An MCP server for interacting with prefect resources.

The server gives MCP clients read-only tools for inspecting Prefect Cloud and self-hosted Prefect instances, plus a docs proxy so assistants can look up current Prefect CLI, SDK, and deployment guidance.

Choose Your Setup

Claude Code Plugin

The easiest setup for Claude Code is the Prefect plugin:

# add from marketplace
/plugin marketplace add prefecthq/prefect-mcp-server

# install the plugin
/plugin install prefect

This connects Claude to Prefect’s hosted, read-only MCP server for diagnostics, documentation, and current release notes. Claude opens Prefect Cloud OAuth during installation so you can select the workspaces it may access.

[!NOTE] The plugin does not read ~/.prefect/profiles.toml or require a local Prefect installation. For self-hosted Prefect or explicit credentials, use the local uvx setup below.

Codex Plugin

The same hosted MCP server and workflow guidance are available as a Codex plugin:

# add from marketplace
codex plugin marketplace add prefecthq/prefect-mcp-server

# install the plugin
codex plugin add prefect@prefect

Like the Claude Code plugin, Codex authenticates directly with Prefect Cloud OAuth. The plugin contains no API keys or placeholder credentials.

The same plugin bundle is suitable for Cowork and Claude Tag because it references the hosted MCP URL instead of launching a process on the user’s machine. Claude Tag administrators attach it and its Prefect credential to the appropriate Access bundle.

Prefect’s privacy policy and terms and conditions apply to the hosted service.

Run Locally

When running the MCP server locally with stdio transport, it automatically uses your local Prefect configuration from ~/.prefect/profiles.toml if available.

# minimal setup - inherits from local Prefect profile
claude mcp add prefect \
  -- uvx --from prefect-mcp prefect-mcp-server

# or explicitly set 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

[!NOTE] For self-hosted Prefect servers with basic auth, use PREFECT_API_AUTH_STRING instead of PREFECT_API_KEY.

[!TIP] 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 since this MCP server requires no write permissions.

Deploy Your Own Server

Deploy your own server when you need a custom Prefect API target, self-hosted Prefect, a private network, or an API-key-based team deployment.

1. Fork this repository on GitHub:

   gh repo fork prefecthq/prefect-mcp-server
   

2. Deploy it on Prefect Horizon or FastMCP Cloud.

3. Configure the server:

   • server path: src/prefect_mcp_server/server.py
   • requirements: pyproject.toml
   • environment variables:
     • PREFECT_API_URL: https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]
     • PREFECT_API_KEY: your Prefect Cloud API key
     • PREFECT_API_AUTH_STRING: basic auth credentials for self-hosted Prefect, if needed
     • OPENAI_APPS_CHALLENGE_TOKEN: domain-verification token for an OpenAI public plugin submission, if needed

4. Add the deployed HTTP URL to your MCP client:

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

[!NOTE] For self-hosted deployments, environment variables are configured on the deployed MCP server, not in your MCP client configuration. The MCP host authenticates access to the MCP server, while this server uses the configured Prefect credentials to access Prefect.

Other MCP Clients

Capabilities

This server enables MCP clients to interact with Prefect read-only APIs:

Monitoring and inspection

• View dashboard overviews with flow run statistics and work pool status
• Query deployments, flows, flow runs, task runs, work pools, and automations with advanced filtering
• Retrieve detailed execution logs from flow runs
• Track events across your workflow ecosystem
• Review rate limit usage for Prefect Cloud

Documentation access

• Search current Prefect documentation through the mounted docs MCP server
• Find current CLI and SDK syntax for write operations
• Look up deployment, work pool, and automation patterns

Intelligent debugging

• Get contextual guidance for troubleshooting failed flow runs
• Diagnose deployment issues, including concurrency problems and unhealthy work pools
• Identify root causes of workflow failures

Development

Evals

This project includes scenario tests that connect Pydantic AI agents to the MCP server and validate that they can solve realistic Prefect support tasks. See evals/README.md.

Evals should be written like support case reproductions: set up a workspace state that represents a real customer problem, ask the agent the kind of question a user or support engineer would ask, and verify the final answer identifies the concrete cause or next action. Protocol behavior such as OAuth token validation belongs in unit tests; evals should prove that the MCP server helps an agent solve user-facing Prefect problems.

uv run pytest evals

Links

• FastMCP - the framework used to build this MCP server
• Prefect Horizon - managed MCP deployment
• Prefect - workflow orchestration
• Model Context Protocol - the MCP specification
• Claude Code - an MCP client

---

mcp-name: io.github.PrefectHQ/prefect-mcp-server