---
title: "安装 Prefect 插件与配置本地 MCP"
summary: "安装 prefect@prefect 后，通过 OAuth 连接 Prefect Cloud。本地 stdio 模式可连接自托管服务或指定工作区。"
category: mcp
level: starter
surfaces: [cli, app, ide]
tags: ["MCP", "Prefect", "plugins", "OAuth", "stdio"]
canonical: /tips/prefect-codex-plugin/
---

# 安装 Prefect 插件与配置本地 MCP

安装 prefect@prefect 后，通过 OAuth 连接 Prefect Cloud。本地 stdio 模式可连接自托管服务或指定工作区。

Prefect MCP 目前 beta。给 Codex 的**官方主路径**是插件：连 Prefect Cloud 托管只读 MCP，走 Cloud OAuth。插件使用 OAuth，无需提供 API key，也不读取 `~/.prefect/profiles.toml`。源仓是 `prefecthq/prefect-mcp-server`。marketplace.json 名是 `prefect`，插件 `name` 也是 `prefect`，所以 id 是 `prefect@prefect`。源仓 README 的 Codex Plugin 节：

```bash
codex plugin marketplace add prefecthq/prefect-mcp-server
codex plugin add prefect@prefect
```

0.154 起先在**当前会话**看 `/plugins`；当前会话没有再新开。IDE 扩展没有 `/plugins`，用桌面或 CLI。安装后重新打开会话，用 `@` 点名插件，或直接问「Why did my latest Prefect flow run fail?」。先让它 `get_identity`，确认当前连的是哪套工作区，再查失败的 flow run。托管模式下，工作区范围的工具还要带已授权的 `workspace_id`。

插件自动登记 `https://prefect.fastmcp.app/mcp`，无需重复添加同名 MCP 服务。

自托管 Prefect、需要指定 Cloud workspace、或插件装不上时，才走本机 stdio。官方 Codex CLI 节是 `uvx --from prefect-mcp prefect-mcp-server`：

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

无环境变量时，stdio 继承当前 Prefect profile（`~/.prefect/profiles.toml`）。已经装了插件时，把本机表改名 `prefect_local`，以便与插件连接区分。

指定 Cloud workspace 时，`PREFECT_API_URL` 可以写进 `env` 表（不是密钥）。从浏览器仪表板改写：地址是 `https://app.prefect.cloud/account/` 加账号 UUID、`/workspace/` 加工作区 UUID；MCP 用 `https://api.prefect.cloud/api/accounts/` 加同一账号 UUID、`/workspaces/` 再加工作区 UUID。通过环境变量提供 `PREFECT_API_KEY`，避免将密钥直接保存到配置文件。用 `env_vars` 从启动环境中转发：

```toml
[mcp_servers.prefect]
command = "uvx"
args = ["--from", "prefect-mcp", "prefect-mcp-server"]
env_vars = ["PREFECT_API_KEY"]
startup_timeout_sec = 60
enabled = true

[mcp_servers.prefect.env]
PREFECT_API_URL = "https://api.prefect.cloud/api/accounts/ACCOUNT_UUID/workspaces/WORKSPACE_UUID"
```

把 `ACCOUNT_UUID` / `WORKSPACE_UUID` 换成仪表板里的 UUID。自托管改成例如 `http://127.0.0.1:4200/api`，并把 `env_vars` 换成 `PREFECT_API_AUTH_STRING`（格式是 `username:password`），使用自托管服务的凭据。Team / Pro / Enterprise 可用只读服务账号。`env` 表是字面量。Codex 不读 `.env`。从已经 export 的终端启动。从 Dock 或开始菜单启动的桌面应用通常不会加载终端环境变量。

手写 TOML 时，使用 `[mcp_servers.prefect]` 和 `[mcp_servers.prefect.env]` 配置节。

MCP 工具用于读取 dashboard、deployment、flow run、日志、work pool 和文档。创建或修改资源通过 `prefect` CLI 完成，CLI 权限需单独管理。若 `uvx` 首次启动较慢，可设置 `startup_timeout_sec = 60`。

网页 Cloud 不读取 `~/.codex/config.toml`。配置后用 `codex plugin list` 核对已装。stdio 对照 `codex mcp get prefect` 看 command 是 `uvx`。

## 来源

- [Prefect · How to use the Prefect MCP server](https://docs.prefect.io/v3/how-to-guides/ai/use-prefect-mcp-server)
- [prefecthq/prefect-mcp-server](https://github.com/prefecthq/prefect-mcp-server)
- [prefect-mcp-server · SECURITY.md](https://github.com/PrefectHQ/prefect-mcp-server/blob/main/SECURITY.md)