Skip to Content
DocsAgentsTools and MCP

Using Tools with Agents

Tools are typed functions that can be executed by agents or workflows. Each tool has a schema defining its inputs, an executor function implementing its logic, and optional access to configured integrations.

Creating Tools

Here’s a basic example of creating a tool:

src/mastra/tools/weatherInfo.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherInfo = createTool({
  id: "Get Weather Information",
  inputSchema: z.object({
    city: z.string(),
  }),
  description: `Fetches the current weather information for a given city`,
  execute: async ({ context: { city } }) => {
    // Tool logic here (e.g., API call)
    console.log("Using tool to fetch weather information for", city);
    return { temperature: 20, conditions: "Sunny" }; // Example return
  },
});

For details on creating and designing tools, see the Tools Overview.

Adding Tools to an Agent

To make a tool available to an agent, add it to the tools property in the agent’s configuration.

src/mastra/agents/weatherAgent.ts
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";
 
export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions:
    "You are a helpful assistant that provides current weather information. When asked about the weather, use the weather information tool to fetch the data.",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherInfo,
  },
});

When you call the agent, it can now decide to use the configured tool based on its instructions and the user’s prompt.

Adding MCP Tools to an Agent

Model Context Protocol (MCP)  provides a standardized way for AI models to discover and interact with external tools and resources. You can connect your Mastra agent to MCP servers to use tools provided by third parties.

For more details on MCP concepts and how to set up MCP clients and servers, see the MCP Overview.

Installation

First, install the Mastra MCP package:

npm install @mastra/mcp@latest

Using MCP Tools

Because there are so many MCP server registries to choose from, we’ve created an MCP Registry Registry  to help you find MCP servers.

Once you have a server you want to use with your agent, import the Mastra MCPClient and add the server configuration.

src/mastra/mcp.ts
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
// Configure MCPClient to connect to your server(s)
export const mcp = new MCPClient({
  servers: {
    filesystem: {
      command: "npx",
      args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Downloads",
      ],
    },
  },
});

Then connect your agent to the server tools:

src/mastra/agents/mcpAgent.ts
import { mcp } from "../mcp";
// Create an agent and add tools from the MCP client
const agent = new Agent({
  name: "Agent with MCP Tools",
  instructions: "You can use tools from connected MCP servers.",
  model: openai("gpt-4o-mini"),
  tools: await mcp.getTools(),
});

For more details on configuring MCPClient and the difference between static and dynamic MCP server configurations, see the MCP Overview.

Accessing MCP Resources

In addition to tools, MCP servers can also expose resources - data or content that can be retrieved and used in your application.

src/mastra/resources.ts
import { mcp } from "./mcp";
 
// Get resources from all connected MCP servers
const resources = await mcp.getResources();
 
// Access resources from a specific server
if (resources.filesystem) {
  const resource = resources.filesystem.find(
    (r) => r.uri === "filesystem://Downloads",
  );
  console.log(`Resource: ${resource?.name}`);
}

Each resource has a URI, name, description, and MIME type. The getResources() method handles errors gracefully - if a server fails or doesn’t support resources, it will be omitted from the results.

Agent MemoryAdding Voice