Transcription
My name is Nate and I work at Prefect on the open source. And today I'm going to be talking about how to use the Prefect MCP server both as an interactive debugging tool as well as a thing that you can plug into your agents um within your programmatic workflows to get a window into your prefix ecosystem at large so that agents can make informed decisions within your environment.
So let's pop over to the terminal and talk about what this actually looks like. Just to get oriented, um I'm in a little bit of a prefetch project here. I got a little Python package defined by a pi project.l. I have prefect getting pulled in by pyantic AI. Um, prefect is an extra. We'll talk more about Pantic AI in a moment, but the important part for now is that I have prefect installed and I have this I have a couple flows. I have this one just gets some stars. Um, this will probably look familiar from the readme. Um, just gets the stars from GitHub and prints it out. Um, and then the other one is cleaning up my database for my prefect instance. And we'll talk more about that later. Um, but for now, I have a couple things I want to do. Um, I'll go ahead and get rid of this and that and this. And I need a prefect instance. So, right now, if I look, I don't really have anything going on. So, I'll say docker run prefect in the background. Please port forward port forwarded to 4200. Um, you could very uh just as well run prefect server start. Um, but one way or another, I now have prefect config view. I am now connected to 4200. Um, there we go. That seems cool.
So now what I'd like to do is I'd like to deploy my code. Um, and I wrote this little uh just file that just calls a prefect CLI with um no prompt meaning non-interactive. And then I'm going to deploy everything that I've already defined in my prefix.yamel, which in this case are just the two flows that I already mentioned. Um, get stars for these four repos. Um, here's my entry point relative to the uh root of the repo that I'm cloning at runtime. Um, and then I also have this other one, which again we'll talk more about later. Um, but I want to deploy both of them to my new server. And because I'm lazy, I'm going to have Claude do it for me. Um, there's a lot of things that Claude can do. So, I'm just getting familiar with what what Claude can do for me. Um, so in order to enable Claude, I'm going to add the Perfect MCP server to Claude so that it can connect to it and use the tools that are exposed by the Prefect MCP server. And so, I'm going to use this command um, uvx and then the executable, which is prefect MCP server from the Prefect MCP Pippi package. Um, so I'll go ahead and do that. And now I can go ahead and start Claude with dangerously skip permissions, which is a personal choice that maybe you want to start without that flag just that that you understand what's going on and you don't um have anything unexpected happen. Um, but now we should be able to see that if I do for/mcp, we have some MCP servers. In particular, we have this prefect one um, which is configured in this file via the CLI. And I can go ahead and click view tools and see all these tools that it has access to. So basically, you'll notice that all these are uh reads. Um there's no mutations going on. Um however, you can inform Claude to um perform mutations via the prefix CLI. Um so let's get into how we might deploy our code.
Um so I'll just say, hey Claude, I have a couple flows. I just started a new prefix server. Um, first of all, can you just confirm that you're connected to the correct prefix server, please? And I'm saying prefix server, but um, if your profile is configured to talk to Prefect Cloud, then that would just work. Um, cloud would tell you instead of this, which is, hey, yes, confirmed. I'm connected to your local prefix server, it would say, hey, I'm connected to Prefect Cloud at this workspace. So, I'm just choosing to run a prefix server instead. Um, okay. Would you like me to check the status of your flows? No, actually I just need help deploying my code. There's a just file in the root of the repo which you should be able to use. Um, can you go ahead and deploy, please? Um, so it's a bit overkill to ask cloud to do this, but what should happen is that we're going to encounter a bit of an issue which I think is a useful thing to um just step through. Um, can you please check the output from that command? And you don't need to run deployment commands in the background from now on please. Um it ran it in the background which just obscures the output. So um what we should see is that that uh deployment that we have is referencing a workpool called default which cloud has correctly identified. Um I think I need to create that workpool. I I'm I'm planning to run all my code on as subprocesses. So I think I need a process workpool. And so Claude should be able to just use this prefix CLI on my behalf. Pref workpool create default type process. Looks good to me. Cool. Now let's see if Claude decides to rerun the deployment. Yes, please.
Okay, so Claude was like, "Hey, seems like you're trying to deploy to a workflow that doesn't exist. Let me create that workpool for you." Um, and redeploy. And now we have some stuff going on. We have deployments in the UI, those two that we mentioned. Um, all righty. That looks good. Um, how about you start a prefect worker in the background and then you can kick off a flow and see how it goes. Actually, let's do the get stars flow first, please. And I've introduced a bit of a bug here and we'll see how this goes. um Claude should hopefully identify um that something went wrong with the flowun and then um help me fix it and redeploy. Um, so let's see what's going on. It's it's going to read details about that flow. Get flow runs filtering for the specific ID. Ooh, looks like Claude found the logs and it says key error stargazer count. Hm. The Floren ran but failed with a key error. H I think I introduced a bug. I did introduce a bug on purpose. Claude found it. There it is. Um it's stargazer's count. So lots of times in our workflows, uh the bug is um an error in our code, a semantic error, or um it could also be a misuse or a misunderstanding of prefect. Um, so what happened just now is that Claude ran it again because it didn't realize that it's pulling from GitHub at Yeah. Okay, here we go. There we go. Um, Claude ran it again, but it didn't push the code. So, the version of the code that lives on GitHub that's getting pulled at runtime is still the old version that had the old key. And Claude realized this worker is still running from the old clone on git clone. Um, now it's going to go through. There we go. It's It's reading the old worker logs, which is why it's showing that key error again. But you can see in the most recent time that it ran this, it successfully completed, all the stuff happened correctly. There we go. Okay, we could do a little sanity check and make sure that cloud didn't do anything crazy by popping over just opening the repository where our code lives. Um, we can see that cloud was pushing code on our behalf the last couple commits. Um, fix correct GitHub API field name from Stargazer to Stargazer's count. Great. Okay. Excellent.
So, um, there's a lot of different things that Claude can do. Um, one one thing that I'll do real quick, um, I think if we look at our code, there's in the UI, there's one thing that we might notice about it rather quickly. Um, all these get stars are happening sequentially. Um, so I'm going to tell Claude what I'm thinking. All these tasks are happening sequentially. Um, it would be nice if these IO calls would happen concurrently. I think Prefect has a thing for that called map or something. I can't really remember. Can you search the docs and figure out how that works? Okay. So what should happen is that the MCP server has a prefect docs MCP proxied through it. All that means is that the tools from the docs MCP are exposed also on this prefix MCP server. And so it went through it found our documentation. It says prefix has a map method on tasks that allows you to run them concurrently. Imagine that. Um, so it correctly replaced this for loop where you're calling each task sequentially with the map method. And Claude actually made a slight error, I think, because it is not necessarily resolving the futures. Um, it will probably work, but it's susceptible to timing problems. So, I'm going to inform Claude of this. Hey, Claude, I think that's pretty much right, but I think you forgot to resolve your terminal futures. Um, if you you're gonna want to add weight on the end of that map thing, you you can check the docs on this. Um, so in general, the prefix MCP server is nice, especially for when you have a fuzzy understanding that this thing exists or you have some intuition about how things work. Um, but you don't remember exactly what it is. Um, and so Claude is just really fast at go reading the documentation. And of course, sometimes it's too fast. it will gloss over some details just like humans do sometimes. Um, but see here we go. It added the correct weight. Sorry about the motorcycle. Um, so now we have the features definitely resolved. And if we go ahead wait for cloud to push our code. Um, let's run this again. Can you run this again for me so I can check it out in the UI, please? Um, we should see that our code is going to happen concurrently this time. Okay, there's our URL. Oops. Um, let's go to runs pending smooth ostrich. Okay, nice line of concurrent tasks. Cool.
Okay, so this is the first mode in which it is useful to use the prefect MCP server, which is as an interactive debugging tool as you're working on prefect stuff, deploying your workflows and stuff like that. This the second one is a little bit more interesting which is to use uh the MCP server as an extension of an agent's capabilities. So in the same way that we were just enabling Claude to inspect the state of our prefix server um and make informed decisions, we can empower different agents like Pyantic AI's agent to interact with our prefect instance and make decisions.
So, what I have right here um is I'm instantiating a cleanup agent using the Pyantic AI integration with Prefect for durable agent execution. Um, and basically all that's going on here is I'm I'm saying I have an agent. Here's the model it uses. Uh, I'm going to use HighQ 4.5. Um, here's my API key loaded from myv. Um and importantly there's this output type a structured output that you ask the agent to produce. So a structured output is usually a type dictionary or a base model. In this case it's a decision about whether to proceed with database cleanup and I'll I'll just go ahead and add that in there. And it's yes or no. How confident are you? Um what's your reasoning? And what are your concerns? So, we're asking the agent to look at our database and come up with this as a cleanup decision. Um, and in order to come to that cleanup decision, we're going to give it the prefect MCP server so that it can inform itself on the actual state of our prefect environment. Um, so now we have the prefect MCP that is passed in as a tool set for this agent. And then we add some config in to say like hey if something fails um is something that you do like a tool call um which is wrapped in a task fails then you can retry it using the prefix semantics that already exist.
Going into our cleanup flow um we'll go down to the bottom just to show what's going on broadly here. Um we have this database cleanup flow. it goes ahead, it checks um what type of things we might want to delete. Um whether or not it's a dry run. Um and then based on our criteria for what to delete, we'll preview what things we're about to delete. Um and there are two modes to this workflow, you might notice, um which are that it's either uh going to be reviewed by a human or viewed by AI. um approval type human or AI and so by default it's human however we can instead of pausing the flow run as you might be familiar with in prefect you can pause the flow run give yourself a form go inspect the form once you're happy press the button and then it continues instead we could replace that pause with an agent that's hooked up to the prefix MCP server and so it has access to our prefix environment as defined by the terms of the prefix MCP and it can inspect the state of our uh database and decide whether or not this operation to clean up our database should proceed. Um, so that's exactly what's going on. Uh, let's go back over here down to the bottom. We'll say get cleanup approval. All righty. So if the the approval type is human, then we pause and we wait for a human to come look through the form and say okay. Otherwise, if it's an AI approval, then we take our nice cleanup agent that we defined in the other file and we run it on this rendered prompt, which is, hey, review this database cleanup operation and decide if it's safe to proceed. And here's where you could get, you know, very specific based on your situation, the type of workload you have in your database, the resource allocation you have in your um prefect installation. Um, but I wrote some basic prompt to say like, hey, please inspect these things. decide whether this cleanup operation is a thing that we should do.
Um, so let's try it out. Um, hey Claude, uh, I think I've been running a lot of code recently. Um, I should probably clean up my database. Can you kick off the database cleanup flow? So, let's go over to the UI and see what happens here. Um, I trust Claude is going to kick that off successfully. Looks like it did. Um, so let's refresh here. Database cleanup. So there should be a lot of stuff going on because the prefect uh wrapper around the Pantic AI agent is going to um instrument tool calls and LLM calls with um one thing I didn't consider is that it might be using human uh human review. Oh no, approval type is AI. Excellent. Okay. Um, so it's going to get cleanup approval after previewing the flow runs. So it found four flow runs that would be deleted. Uh, failed, failed, completed, completed. So now it's Haiku is pretty fast. So it went through this already, but I want to see exactly sort of what it did here. As it went through, it did a lot of things quite quickly. But you can kind of see what it was up to. It read some events using the MCP. It got some deployments. It got workpools, um, got flow runs, all this other stuff. So, let's I don't know, that's kind of opaque. Let's see what its reasoning actually was. Okay, approved because uh, all of them were the GitHub stars. All of them are in terminal states. The ages uh, are between these dates well beyond the five minute retention window, which I set up specifically for this video. Uh, the floor the four runs are isolated. uh the system health um the workflow is ready. So you know this is quite verbose as LLM tend to be but you could tweak that prompt to focus on specific things that you know are important um to sort of inject the intelligence and context that you have uh in your mind um to tweak the behavior as far as this approval goes. And you can get pretty creative with pyantic as far as defining this schema. For example, one small improvement I could make here is I could say that like this is going to be exactly a field where the uh confidence is not just begging for it to be between zero and one but it absolutely has to be between zero or one or else pantic AI will not um allow the agent to proceed. It has to produce a confidence that that's between zero and one or else it can't go forward and there's many other constraints that you can add in so that the conclusion that it comes to is very statically defined by your wishes.
Um, so that is an example of how you can use a uh an MCP client or an agent like Pantic AI's um offering or something like Cloud Code hooked up to a Prefect MCP which imbuss it with extra capability um as far as inspecting the state of the world with respect to prefect um and then when presented with decisions like hey I'm going to do this database cleanup um should we proceed or not it can go inform itself on uh the terms of the perfect MCP server or any other MCP server you would like to connect to that agent u maybe some that you've written yourself and deployed on fast MCP cloud. So hopefully this was a good introduction to both the inter in inter interactive mode of interacting with the perfect MCP server as well as the programmatic mode of incrementally allowing agents to take action within your workflows where previously you might have had some manual intervention that's necessary. So hopefully that was helpful.