S02E03 · Agentic Capabilities: MEGA lesson video by Angie Jones
Angie Jones demonstrates how an agent can use MCP tools and resources, read local files, and use code mode to coordinate tool calls and process results. The lesson uses a retail agent example to explain tool discovery, access boundaries, and retrieving context when needed.
videoAngie Jones · hq.mega.dev · Saved Nov 19, 2026
mega course, model context protocol, code mode, context engineering, agent infrastructure
Transcript of the lesson video for S02E03 of the MEGA.dev course, by Angie Jones. Agenda: AGENTS.md · MCP · Agent Skills · Context Management. The video plays on the lesson page in MEGA Student HQ (needs a login).
0:05 So far, we've given our agent tools by defining them in our application and then registering them with the agent. But suppose another team wants to use order lookup in a different application. It wouldn't really make sense for them to redefine something that we've already built. By exposing the capability through MCP, or the Model Context Protocol, we can give compatible applications a shared way to discover and call that capability. Let's expose the existing lookup through an MCP server and then connect our agent as a client. The MCP client is the part of our application that communicates with an MCP server on the agent's behalf. So the server exposes capabilities such as our order lookup tool, and MCP defines the messages that they exchange so that compatible applications can use those capabilities.
The client can ask the server which tools it offers and what inputs they accept. When our agent, or any agent actually, calls order lookup, the client sends the tool name and the order number to the server, and these messages travel over HTTP to the server's endpoint. The server runs the lookup and sends the result back to the client. Our application gives that result to the agent so that it can answer the customer. Now, both sides run on our machine for now since we're still actively developing, but I'll go over deployment in a bit. This is the interface an MCP client discovers. So we're exposing the existing get_order operation with its description and its input.
The order server exposes our existing order lookup. We don't need to change its service rules or anything like that. To define it as an MCP server, we give the server an ID, a name, and a version, and we put the tool in its tools object. And then this get_order key is the name that's exposed by the server, and the value is the tool definition that we've imported. We also register the MCP server with the running application here, and that makes the server available through the endpoint that the client will call. Now that we're using this tool in a portable MCP server, we need to consider that another application can discover this tool without knowing our code or our agent's instructions.
So it's really important that the tool's description makes sense on its own. This description explains what the tool retrieves, whose orders it can return, and when to use it. So a name like get_order, that alone is not going to explain all of that, you know? So the MCP client retrieves this description along with the tool's name and its input schema, and then the application makes that information available to its model to help it choose a tool. The client handles the communication. The model uses the description to decide whether the tool fits the customer's request. And then the input schema tells the caller what to supply, which in this case is an order ID. The output schema describes either a found order or an explicit not found result.
And together with the description, these define what another application needs to know to use the tool. Now, the server's tool calls the existing service with the order ID and the configured customer identity, and the description explains the ownership restriction, and then the service enforces it. Moving the tool behind MCP preserves that check. On our agent side, we configure an MCP client with the server's endpoint under the name orders. And then here, list_tools discovers the tools offered by the configured server. So for our agent, we select the discovered order lookup and register it directly alongside its existing tools. The client names this tool orders_get_order, combining the server name and the tool name, and that's the name that we'll see in the agent's tool calls.
Its description and input schema, that comes from the server, so we don't have to define another order lookup tool in our application. And then the server registration makes the capability available over MCP, and the agent registration makes it available to our model. We need both of those connections for the interaction. So if you're adapting an existing tool, follow the request in both directions. The model selects a tool, our client calls the server, the server runs the service, and the result returns to our agent. If the lookup fails, that sequence tells you which connection to inspect. Now, currently, our server is running on localhost, so this address is for applications on our machine. But to let another team's application connect remotely, we need to deploy the MCP server to a host that they can reach.
Here, we've hosted the MCP server at an HTTPS address. We configure our retail agent with that endpoint, and the other team configures its MCP client with the same address. Each client can discover and call the order lookup tool without running its own copy of our server. And we've built it so that another team could use this capability in their application, but- This could also work for customers who want to connect their own agent to access our store's capabilities. So their agent will call our MCP server and use the result to answer them. We expose the order lookup tool, but we could also expose the product search or an exchange workflow or anything like that.
And that would let customers interact with our store through the agent that they already use while our services enforce the rules. The MCP server calls the order service, which accesses the order data. That service and its database could already be hosted. Exposing it through MCP is not going to require, like, moving the data into the MCP server, for example, right? So this shows how the connections could look once this was deployed. In a shared deployment serving customers, the server would establish the customer's identity from verified authentication context and enforce which orders that customer can access. And with that shared connection in place, let's look at how the server can provide reference information as well as tools.
Our agent has system instructions, and remember, those instructions are included every time we call the model. There's other information we want the model to have, but only when it needs it. Alongside tools, an MCP server can expose resources. An MCP resource is information that a client can read. That's really helpful if we want to share our store's return policy or maybe an item size guide. So to add a resource to an MCP server, we define its URI, readable name, and its content type. The URI identifies which reference the client wants, and then list resources describes the available references, and get resource content returns the text for a requested URI. The handler returns the resource's content based on the requested URI.
For the policy resource, the server builds the policy text from the stored rules that's used by our eligibility checks, and that keeps the explanation connected to those rules. For your own agent, decide where the authoritative information lives before you start writing your handlers, because you don't want another separate copy that you're going to have to maintain. The resource is available on the MCP server, but our agent needs a way to request it. So we need to give our agent two tools for working with resources. List MCP resources tools. This one asks the configured MCP servers what resources they offer, so not just our server, but all servers that are configured in the client, and then that returns each resource's name and URI grouped by the server.
And then read MCP resource tool. This one accepts a server name and a URI from the list, and then it asks the MCP client to read the resource. So this works for any resources that we add. Publishing a resource doesn't automatically put its contents into the model's content. This gives it a way to make reference information available through our MCP server and retrieve it when it's needed. So let's see how our agent retrieves this policy when a customer asks about it. So given we ask the agent something like, "What's its return policy?" We see that the model looked at a list of tools that were available. It didn't see one that would give it the information that was needed to answer the customer's question, but it does see that it has a tool to discover additional resources, so it calls that.
And that tells the model that there are two resources available, one of which is for the return policy. This is just what the model was looking for. So it then calls the read MCP resource with the server name and the URI from that result, and with that, it now has the information to answer the customer's question. MCP resources make reference information available through a server, but we can also make files available directly to our agent application, such as a folder of product care documents, for example. To do that, we choose which files the agent can access, and then we give it tools to find and read those files. And then we also need to decide whether the agent can change those files.
For something like care instructions, reading is enough, right? So let's see how the agent uses them to answer the customer's questions. So this question identifies the everyday jacket, so the task is to locate that product's care instructions. The agent listed the files that it could access, and it found the document for the everyday jacket, and then it read that file to get the care instructions that it used to answer the customer. So here's how we configure that access in our agent definition. We give the agent a workspace which contains a local file system, and its base path points to our product care folder, and read only prevents changes through that file system. So attaching the workspace to the agent makes its file tools available to the agent, and the file system's instructions option adds Our description of the collection.
We keep the default instructions, which describes the directory and its access boundary, and then we add what the documents cover. So, these instructions are included in the model's context alongside the agent's instructions. We don't have to list every single document here. New files can be discovered with the same tools as long as this description still fits the collection. And these files are on the machine running our agent. So when deploying the agent, we need to include or mount the documents in its environment. Now, whatever framework you use, check how it enforces file access. This is how it's done in Mastra. So, the general lesson here is to give your agent the context that it needs to be successful, right?
Describe the available information, provide the tools to discover and read it, and then load the relevant content when needed. So, we've now given our agent the ability to retrieve information from an MCP server as well as from files. Next, let's use code to combine tool results before sending an answer to the model. Our customer needs a rain jacket and a backpack within one budget, right? So to help them, our agent needs to find jackets in their size and backpacks that are in stock, and then work out which combination fits their budget. With direct tool calls, the model would search for those products, and it's going to check the available options, and then all of those results will come back to the model, which then has to compare them and then pick the cheapest combinations.
If you have like a really large inventory of products, that means that sending a lot of data back to the model and then asking it to compare prices across all of those combinations is going to be slow, and it's also going to be a lot of tokens, right? Code mode lets the model write itself a program that calls those same tools and then processes their results. So, the agent runs the program in a restricted environment, like a sandbox, for example, and then it's going to return the selected information to the model. So, MCP still connects us to the server, but code mode just changes how we coordinate the calls and how we process the results, and it could also work with tools outside of MCP, okay?
So, our catalog contains hundreds of products, each with different sizes or capacities, right? So, finding like three combinations means checking far more than three products. Let's go ahead and send this request to our agent. Now, it's going to run some code, and it is going to find the three options that are under 150 bucks. So, let's inspect how the agent found these. So, it ran this execute TypeScript, and this program searches for jackets and backpacks, and then it requests their available size, their stock, their prices, and it keeps the jackets that are in a size large, and it filters out items that are out of stock. And then it pairs each eligible jacket with each eligible backpack, it adds their prices, and then it keeps the combinations that are under, under 150 dollars.
So, there's more than 1,700 eligible combinations here. The program sorts them by total and price, and then it returns the cheapest three. Now, the model doesn't need to read every product record or compare every pair itself. The model wrote this program for the customer's request, and if the customer changes the budget or changes the size, it can write a different filtering logic using the same MCP tools. Now, to enable code mode, we pass the tools that it can use to Mastra's create_code_mode function, right? Here are the product search and variant tools available through MCP. Now, the program runs in the sandbox, and it doesn't have access to the file system or the network. Create_code_mode returns an execution tool and generated instructions.
So, we need to register both of those with the agent. So here, we add those generated instructions to the agent's instructions, and this explains how to write a program, returns its results, and call the available functions. And then here, we register the execution tool. So, the model sends its program to this tool, which runs it in the sandbox and returns the results. So, I tested this request three times using direct MCP tool calls and then three times using code mode to call those same MCP tools. With direct calls, all 720 variants entered the model's input. With code mode, only the four variants used in the selected combinations did, right? Because the program processed the full results before returning the selected products to the model.
Direct calls averaged 51,537 tokens per request. Code mode averaged 2,106, including its instructions and the generated code. So, that's almost 96% fewer tokens. Also, the time to find the answer went from 20.54 seconds to 5- 0.64 seconds, which is like a 72.5% reduction. We also checked the answers against the catalog. So, code mode found the correct three combinations in all three runs without retries. Direct calls returned the correct three combinations only in one of three runs. So, running code successfully doesn't necessarily guarantee a correct answer, so we still need to check the results, okay? But it does seem a whole lot more promising. Now, these measurements apply to this request in this catalog. For a simple order lookup, direct calls are enough, right?
Code mode is useful when the model would otherwise have to read and compare a lot of intermediate results. So, if you're considering using code mode in your agent, I suggest that you test both approaches on your own task, check the correctness alongside the tokens in this time. Okay? So, we have seen how our agent can use MCP tools to find and compare products. Next, let's return to that exchange workflow that we implemented in the last video, and now I want to add functionality to let a customer confirm an exchange through another agent application. Now, our existing exchange workflow saved its progress and waited for confirmation. Now I want to expose that same workflow through an MCP tool so that a customer can use it from a different agent.
When the workflow needs confirmation, MCP elicitation lets our server ask another agent to collect the customer's decision. So, our workflow still checks eligibility, it still calculates the proposal and controls whether the exchange is committed, but we're changing how the customer answer reaches it. So here, the customer is using Goose, an open-source general agent, and it has connected our store's MCP server. So here we can see that Goose called, uh, the get_order tool, and then get_inventory, and then exchange with confirmation. So, the server runs our workflow until it reaches the confirmation step, and then it sends the saved proposal and the expected answer to Goose, which presents this form. Now, our server defines the question and the allowed answers, and then Goose controls how the form looks, including the amount of time that it'll wait for the customer's response.
Let's choose to decline. Now, clicking submit sends the customer's answer to the server. The workflow records our choice without creating an exchange or changing any inventory. And all we needed to do to enable this was to add the inventory lookup in the exchange with confirmation tools to our MCP server. And these are reusing our existing tools and connects MCP to the workflow that we already built. We reuse our confirmation schema to tell the MCP client what answer we need, confirm or decline, and this schema is used to request a form from the client. And then the new suspend schema keeps the workflow run ID in the form's message so that the answer can continue the same exchange.
When the customer submits the form, their answer arrives as resume data, and we use it to resume the saved workflow at this confirmation step. Elicitation handles collecting the answer through another client, and our workflow and database still manage the business process in its saved state. Since we're enhancing our MCP server, we might as well go all out, right? Um, let's provide a customized store interface in other agents, and we can do that with MCP apps. In the last video, we defined a response schema so that our store's website could display the agent's results. Our agent returns some structured data, and the website would build the interface around that data. But the customer might be using another agent application.
With MCP apps, our server could also provide an interface for a compatible client to display, including product images, exchange details, and even store branding. Let's send our request for an exchange again. This time, we have a really nice interface with our custom branding showing the proposal, and this is also connected to our application's workflow. In preview exchange tool, the metadata connects preview exchange to a resource URI that starts with UI, and it tells a compatible client which interface to display with this tool's result. We registered that URI with its HTML file on the same MCP server, so the client reads the resource and displays it in a sandbox frame. And the file includes the interface code, so it doesn't need to, like, fetch scripts or images or anything like that from another website.
And then this handler receives the tool result, and it renders the proposal. So, the structured data gives us the amounts and the product details, and then our interface code decides how to present them. And then when the customer clicks a button, the app calls decide_exchange with their choice and assigned reference to the saved proposal. So, this tool is available to the app, so the customer's click supplies the decision instead of the model, and the server verifies the reference and resumes our existing workflow, which checks the exchange before completing it. So, when should you use either technique? Use elicitation when the client's form is enough to collect an answer, and then use MCP app when the interaction needs your own layout or controls.
Both can connect to the workflows that you already use in your agent application. So, giving a model tools doesn't guarantee that it's going to use them the way that we intend. Throughout this course, we've been adding instructions and controls to make our agent more reliable. We've provided system instructions as well as ways to retrieve just-in-time information when it's needed. Now, we're going to add a procedure that teaches agents how to do a task in the way that we want it done, and we can package that procedure as an agent skill. So, an agent skill is a set of instructions that teaches agents a specific task by explaining the steps to follow and also in which order to follow those steps.
So, this customer wants another jacket because it wasn't in the box, [chuckles] but that doesn't tell us whether it was lost, if it was shipped separately, or if it just hasn't left the warehouse. So, we've added three tools to read shipments, to also, uh, track shipments, as well as get existing support cases, and each tool describes what it reads. And then this skill explains when to use those tools, like which records to check and what to do with the results. So, the agent verified the order, it matched the jacket to its shipment, and then it checked that shipment's tracking. This order contains a backpack and a jacket, but they shipped separately, so each one of those has its own tracking.
The backpack was delivered, but the jacket is still in transit. This is the procedure that the agent loaded. It lives in this skill, and it's loaded when the model thinks that it could help it with a given task. So, the names and descriptions of all enabled skills are available to the model at the start of a session, just like the tools are. The model will only load the skill's full instructions if it thinks that it's relevant. So, we don't have to worry about the instructions being brought into the context when it's not needed. The name and mostly the description is what the agent considers when determining if a given skill should be loaded or not.
So, the description essentially works as a trigger that tells the model in what types of scenarios would this information be helpful. So, you want to write your descriptions around the situations in the language that your customers might use, because the model is comparing the description to the customer's intent. So, ours includes missing items and requests to send something, right? Because the customer won't know to ask for something like a missing item investigation, you know? [chuckles] And then the numbered steps in here explain how to use the tools together. So, first, we say, "Verify the order and identify the missing item." And notice we tell the model which tool to use so that this is one less thing that it needs to figure out.
And then we match its SKU to a shipment. If the agent checked the backpack's tracking, it would see delivered, and it might mistakenly tell the customer that their jacket had arrived too, right? So, match the missing item SKU to its shipment, make sure that we're checking the jacket's tracking, okay? Now, could a model figure this out on its own? Maybe, but what are the chances of that happening every single time? Why risk it when we can just add that guidance in a skill? Now, on step three, the procedure branches. If the jacket has no tracking ID, we say, "Okay, check the fulfillment support." If it is in transit, we say, "All right, explain its status," and then stop, okay?
If the carrier says that it's delivered, but, you know, the customer says that it's missing, then go ahead and load the missing delivery procedure and check the existing support cases. So, we put that additional procedure in a separate file under references within the skill folder. If we had included all of that detail in the skill.md, it would enter the model's context every time this skill loads, even when an item is still in transit and we don't need those instructions. Instead, the skill links to the references, and it tells the model when to read it, right? That's what references are for, supporting information that the model can load when it actually needs it. Okay, so I'm going to send a similar request, but just with a different order.
For our customer, the jacket's own tracking says delivered, right? So, the agent needs the additional procedure, and it reads the reference that's linked from skills.md. Now, this is progressive disclosure. The model first sees the skill's name and description, it loads the main procedure when the task matches, and then it reads a supporting file only when that branch requires it. Agent Skills is an open standard that specifies how clients should discover skill files, how they should give the model their descriptions, and then provide a way to read them. So, Mastra loads them from a configured skill folder, and then it configures them in the agent's workspace. So, when testing the skill, start with whether it loads for the right request.
You want to try different ways of asking for the task in unrelated requests where it shouldn't load, right? And then you're going to check whether the agent follows the procedure, if it uses the tools and the references when it needs to, and if it completes the task correctly. You also want to include some cases with missing information or some tool errors so you can see whether it asks for help or whether it stops appropriately or whatever. Run the same request with and without the skill. Does it improve accuracy? Does it reduce unnecessary steps, right? Or does it make the process more consistent? Of course, repeat the test, because one successful run doesn't mean that the skill works reliably forever.
Now, Skills over MCP provides another way to share this procedure. So, this is an MCP extension where a server can publish skill files as resources to help clients understand how to use these tools effectively. Okay, so our agent is coming along beautifully. In the next chapter, we're going to look at how to have our agent collaborate with other agents. [rattling sound]