this is a draft. names, commands, and client behavior can still change.
the Prefect MCP server lets an assistant inspect Prefect. it can read flow runs, deployments, logs, work pools, and docs. you can ask normal questions, and the assistant can collect the context.
that already works well for local use.
local use has a simple trust model. you run the MCP server on your own machine. it can read the same Prefect profile or API key that your terminal uses.
a hosted MCP server is different. it runs at a URL. each tool call arrives over HTTP. the server must know who can use it, what Prefect data it can read, and when that access should stop.
local mcp and hosted mcp need different auth
a local MCP server can use local credentials.
a hosted MCP server cannot read ~/.prefect. it also should not ask users to paste long-lived API keys into an agent client.
Prefect Cloud issues the access token. the hosted MCP server verifies that token before it reads Prefect Cloud data.
Cloud stores the grant and answers these questions:
who approved this client?
which account or workspace can it read?
which MCP server can use this token?
when does this token expire?
has the grant been revoked?
browser auth for humans
when a person connects a client, the flow should stay familiar:
add the hosted Prefect Cloud MCP URL to the client.
click authenticate.
sign in to Prefect Cloud in the browser.
choose the workspaces that the client can read.
return to the client.
after that, the user can ask questions such as:
what failed in the production workspace this morning?
or:
compare late runs in these two workspaces.
the client handles the OAuth details. Cloud stores the grant. the grant records the user, the client, the selected workspaces, and the expiry.
service accounts for unattended agents
browser auth fits a person at a keyboard.
CI, scheduled jobs, workflows, and long-running agent loops need a non-interactive flow.
for those cases, a Prefect Cloud service account can have MCP OAuth credentials. the agent exchanges a client ID and client secret for a short-lived access token. then it calls the hosted MCP server with that token.
this keeps human access and machine access separate.
it also keeps MCP access separate from normal Prefect API keys. service accounts already exist for non-user access in Prefect Cloud. MCP OAuth credentials bind that access to the hosted MCP server.
see Prefect Cloud service accounts for the current service account model.
the mcp server verifies tokens. it does not sign them.
one early prototype gave the hosted MCP runtime the token signing secret.
that proved the flow. it also put too much power in the MCP runtime.
the hosted MCP server should only verify tokens. it should not be able to create them.
the deployed flow uses this split:
Prefect Cloud signs MCP access tokens with a private key.
Prefect Cloud publishes public keys at a JWKS endpoint.
the MCP server fetches those public keys.
the MCP server verifies tokens.
the MCP server cannot mint new tokens.
if the MCP server is compromised, the attacker should not get a token issuer for Prefect Cloud.
workspace choice is explicit
we tried a hidden active workspace first. the assistant could call a tool to switch the active workspace, and later tools would use that value.
that breaks down for a hosted server.
tool calls can land on different processes. some runtimes are stateless. hidden state also makes reviews harder, because a later tool call may not show which workspace it used.
so hosted workspace tools take a workspace_id.
the user can still speak naturally:
the assistant calls
list_authorized_workspaces.the user says "use marvinland" or "check integration-tests."
the assistant maps that name to an authorized workspace ID.
each later tool call includes that workspace ID.
each read names the workspace.
what the token says
for hosted MCP, the token should carry more than a login:
this client can call this MCP server, until this time, for this grant, with these workspaces.
audience and resource binding keep the token scoped. a token for one MCP server should not work against a different MCP server by accident.
the MCP authorization spec gives the protocol rules for remote HTTP MCP servers.
client registration handles only the client
MCP clients also need a way to identify themselves.
that can happen with pre-registered client metadata, Client ID Metadata Documents, or Dynamic Client Registration.
the WorkOS post about DCR and MCP gives more detail.
client registration answers:
which client is asking for access?
it does not answer:
which Prefect workspaces did the user approve?
or:
can this service account read this workspace?
Prefect Cloud still needs to store and enforce those grants.
what an assistant can do
if a user says:
the report is stale. can you check the pipeline?
the assistant can do a first pass:
list recent runs;
inspect failed runs;
fetch logs;
check deployments;
check work pool health;
compare activity across workspaces;
explain what looks wrong.
the existing Prefect MCP evals use this style of task. they should look like real support questions. HTTP status checks belong in tests. evals should prove that the assistant can investigate Prefect problems.
read-only first
the hosted Cloud MCP path starts read-only.
read-only tools can still answer many useful questions. they cannot change a deployment or a run.
write tools can come later. examples include:
retry this run;
cancel these late runs;
pause this deployment;
trigger this deployment with these parameters.
those actions need clearer consent and clearer UI. reading what happened is not the same as changing what happens next.
try the hosted server
there is now a hosted server URL:
https://prefect-cloud-mcp-server.fastmcp.app/mcpadd that URL to an MCP client that supports remote HTTP MCP.
the client should start the OAuth flow. Prefect Cloud opens in the browser. you sign in, choose the workspaces the client can read, and return to the client.
after that, the assistant can use the hosted MCP server without a local Prefect profile and without a copied API key.
the local MCP server still exists. it is useful when you want a server that runs on your own machine and uses your local Prefect credentials.
the hosted server gives you a shared URL, Cloud-managed auth, and explicit grants.
more background is in the Prefect MCP docs.
the code and evals are here: