https://prefect.io logo
Join Slack
Powered by
<@ULVA73B9P> what does anyone do if prefect mcp no...
# marvin-ai
s
@Marvin what does anyone do if prefect mcp not working at runtime, but the installation is stable?
m
✅ thought for 314.8 seconds
Got it — if install looks good but the Prefect MCP server won’t run at runtime, it’s almost always auth/config or client-transport related. Here’s a quick triage you can run. Assuming Prefect 3.x. 1) Verify Prefect connectivity in the same shell the MCP server will use - Check which settings are taking effect:
Copy code
prefect config view --show-sources
prefect profile ls
prefect profile inspect
- Sanity test the API connection:
Copy code
prefect work-pool ls
If these fail, fix Cloud login first:
Copy code
prefect cloud login -k <PREFECT_API_KEY> -w <account_handle>/<workspace_handle>
2) Run the MCP server directly with debug logs
Copy code
PREFECT_LOGGING_LEVEL=DEBUG uvx --from prefect-mcp prefect-mcp-server
- If you rely on a non-default profile, set it explicitly:
Copy code
PREFECT_PROFILE=<your_profile> uvx --from prefect-mcp prefect-mcp-server
- Or export env vars instead of profiles:
Copy code
export PREFECT_API_URL="<https://api.prefect.cloud/api/accounts/<id>/workspaces/<id>>"
export PREFECT_API_KEY="pnu_xxx..."
PREFECT_LOGGING_LEVEL=DEBUG uvx --from prefect-mcp prefect-mcp-server
3) Common runtime errors and quick fixes - 401 Unauthorized: wrong/expired key or wrong workspace. Re-run 
prefect cloud login
or reset 
PREFECT_API_KEY
and 
PREFECT_API_URL
. - Connection/timeouts to OSS server: ensure the server is reachable from that machine; for self-signed certs in dev, try:
Copy code
export PREFECT_API_SSL_VERIFY_CERTS=false
- Profile not loading under your client: set 
PREFECT_PROFILE
or use env vars as above (some clients don’t load shell profiles). - Slow/large workspace: increase timeout:
Copy code
export PREFECT_API_REQUEST_TIMEOUT=60
4) Client (Claude/Cursor/etc.) configuration checks - Prefer STDIO transport: point the client’s MCP server command to:
Copy code
uvx --from prefect-mcp prefect-mcp-server
- If you tried an HTTP/WebSocket transport, switch to STDIO unless you’ve confirmed HTTP is supported in your client and opened any required ports. - Check the client’s MCP logs (most clients have a logs pane for each MCP server) for the first error line — that’s the most useful clue. 5) If it still won’t start, please share: - Which MCP client (Claude Desktop/Code, Cursor, etc.) and OS - Prefect Cloud vs self-hosted, and how you’re authenticating (profile vs env vars) - The exact error or the first 30–40 lines of the MCP server startup logs from:
Copy code
PREFECT_LOGGING_LEVEL=DEBUG uvx --from prefect-mcp prefect-mcp-server
Helpful references - Docs: Use the Prefect MCP server - Repo / issues: prefect-mcp-server on GitHub If you’d like, I can also loop in our team to take a quick look live — happy to set that up.
n
hi @Servando - can you be more specific about what's not working?
or is this a proactive question about a failure that could happen?
s
been witnessing this multiple times
n
what's your client/installation command?
s
what that
n
what MCP client are you using (looks like codex)? and how are you installing the prefect MCP server>?
s
ooh yeah codex and uvx --from prefect-mcp prefect-mcp-server
n
hrm yea im not sure, do you have an old 
codex
executable? i can't reproduce this
Copy code
» codex mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server
Added global MCP server 'prefect'.

» codex --dangerously-bypass-approvals-and-sandbox e 'whats my prefect identity'
OpenAI Codex v0.104.0 (research preview)
--------
workdir: /Users/nate/github.com/prefecthq/prefect-mcp-server
model: gpt-5.3-codex
provider: openai
approval: never
sandbox: danger-full-access
reasoning effort: high
reasoning summaries: auto
session id: 019c7c13-4179-75d0-b4d8-f11b1133af26
--------
user
whats my prefect identity

mcp: prefect starting
mcp: prefect ready

mcp startup: ready: prefect

thinking
**Planning identity retrieval**
codex
I'll query your connected Prefect instance now and return the identity details directly.
tool prefect.get_identity({})
prefect.get_identity({}) success in 55ms:
{
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"identity\":{\"api_url\":\"<http://localhost:4200/api/>\",\"version\":\"0.8.4\"},\"error\":null}"
    }
  ],
  "structuredContent": {
    "success": true,
    "identity": {
      "api_url": "<http://localhost:4200/api/>",
      "version": "0.8.4"
    },
    "error": null
  },
  "isError": false
}

thinking
**Clarifying identity display logic**
codex
Your Prefect identity is:

- `api_url`: `<http://localhost:4200/api/>`
- `version`: `0.8.4`

No user/account identity was returned, which usually means you're connected to a local OSS Prefect API.
tokens used
7,323
Your Prefect identity is:

- `api_url`: `<http://localhost:4200/api/>`
- `version`: `0.8.4`

No user/account identity was returned, which usually means you're connected to a local OSS Prefect API.
13 Views
Open in Slack
PreviousNext
Powered by