Repository: mastra-ai/mastra
Pull request #4016: docs: Tools and MCP
Author: login: TylerBarnes
Created: 2025-05-02T00:05:33Z | Merged: 2025-05-02T20:19:56Z

- Combined `/docs/agents/adding-tools` and `/docs/agents/mcp-guide` into `/docs/agents/using-tools-and-mcp`
- Added a new `Tools & MCP` sidebar section with pages for Mastra tools + MCP
- Deleted `/docs/integrations` and redirected to `/docs/tools-mcp/mcp-overview`
- Set sidebar sections for Tools, Memory, and old Workflows to be collapsed by default so at a glance you can see Agents, tools, memory, and workflows all at once.


Diff:
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 155545bd137..44cb9a18ef9 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -164,11 +164,21 @@ export default withGT(
         destination: "/docs/agents/adding-tools",
         permanent: true,
       },
+      {
+        source: "/docs/agents/adding-tools",
+        destination: "/docs/agents/using-tools-and-mcp",
+        permanent: true,
+      },
       {
         source: "/docs/agents/02a-mcp-guide",
         destination: "/docs/agents/mcp-guide",
         permanent: true,
       },
+      {
+        source: "/docs/agents/mcp-guide",
+        destination: "/docs/agents/using-tools-and-mcp",
+        permanent: true,
+      },
       {
         source: "/docs/agents/03-adding-voice",
         destination: "/docs/agents/adding-voice",
@@ -360,6 +370,11 @@ export default withGT(
         destination: "/docs/integrations",
         permanent: true,
       },
+      {
+        source: "/docs/integrations",
+        destination: "/docs/tools-mcp/mcp-overview",
+        permanent: true,
+      },
       {
         source: "/docs/evals/01-supported-evals",
         destination: "/docs/evals/overview",
diff --git a/docs/src/content/en/docs/_meta.ts b/docs/src/content/en/docs/_meta.ts
index 15da3c43165..46187207c44 100644
--- a/docs/src/content/en/docs/_meta.ts
+++ b/docs/src/content/en/docs/_meta.ts
@@ -1,48 +1,20 @@
 const meta = {
   index: "Introduction",
-  "getting-started": {
-    title: "Getting Started",
-  },
-  frameworks: {
-    title: "Frameworks",
-  },
-  agents: {
-    title: "Agents",
-  },
-  memory: {
-    title: "Memory",
-  },
-  workflows: {
-    title: "Workflows",
-  },
-  "workflows-vnext": {
-    title: "Workflows (vNext)",
-  },
-  rag: {
-    title: "RAG",
-  },
-  "local-dev": {
-    title: "Local Dev",
-  },
-  deployment: {
-    title: "Deployment",
-  },
-  "mastra-cloud": {
-    title: "Mastra Cloud",
-  },
-  observability: {
-    title: "Observability",
-  },
-  evals: {
-    title: "Evals",
-  },
-  storage: {
-    title: "Storage",
-  },
-  voice: {
-    title: "Voice",
-  },
-  integrations: "Integrations",
+  "getting-started": { title: "Getting Started" },
+  agents: { title: "Agents" },
+  "tools-mcp": { title: "Tools & MCP", theme: { collapsed: true } },
+  memory: { title: "Memory", theme: { collapsed: true } },
+  workflows: { title: "Workflows", theme: { collapsed: true } },
+  "workflows-vnext": { title: "Workflows (vNext)" },
+  rag: { title: "RAG" },
+  "local-dev": { title: "Local Dev" },
+  deployment: { title: "Deployment" },
+  "mastra-cloud": { title: "Mastra Cloud" },
+  observability: { title: "Observability" },
+  evals: { title: "Evals" },
+  frameworks: { title: "Frameworks" },
+  storage: { title: "Storage" },
+  voice: { title: "Voice" },
   community: "Community",
 };
 
diff --git a/docs/src/content/en/docs/agents/_meta.ts b/docs/src/content/en/docs/agents/_meta.ts
index 10aad8b485c..0b91afffa2d 100644
--- a/docs/src/content/en/docs/agents/_meta.ts
+++ b/docs/src/content/en/docs/agents/_meta.ts
@@ -1,8 +1,7 @@
 const meta = {
   overview: "Overview",
   "agent-memory": "Agent Memory",
-  "adding-tools": "Adding Tools",
-  "mcp-guide": "Using MCP",
+  "using-tools-and-mcp": "Tools and MCP",
   "adding-voice": "Adding Voice",
   "runtime-variables": "Runtime Context",
 };
diff --git a/docs/src/content/en/docs/agents/adding-tools.mdx b/docs/src/content/en/docs/agents/adding-tools.mdx
deleted file mode 100644
index 81b38543477..00000000000
--- a/docs/src/content/en/docs/agents/adding-tools.mdx
+++ /dev/null
@@ -1,288 +0,0 @@
----
-title: "Agent Tool Selection | Agent Documentation | Mastra"
-description: Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.
----
-
-# Agent Tool Selection
-
-Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.
-
-## Creating Tools
-
-In this section, we'll walk through the process of creating a tool that can be used by your agents. Let's create a simple tool that fetches current weather information for a given city.
-
-```typescript filename="src/mastra/tools/weatherInfo.ts" copy
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-const getWeatherInfo = async (city: string) => {
-  // Replace with an actual API call to a weather service
-  const data = await fetch(`https://api.example.com/weather?city=${city}`).then(
-    (r) => r.json(),
-  );
-  return data;
-};
-
-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 } }) => {
-    console.log("Using tool to fetch weather information for", city);
-    return await getWeatherInfo(city);
-  },
-});
-```
-
-## Adding Tools to an Agent
-
-Now we'll add the tool to an agent. We'll create an agent that can answer questions about the weather and configure it to use our `weatherInfo` tool.
-
-```typescript filename="src/mastra/agents/weatherAgent.ts"
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-import * as tools from "../tools/weatherInfo";
-
-export const weatherAgent = new Agent<typeof tools>({
-  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: tools.weatherInfo,
-  },
-});
-```
-
-## Registering the Agent
-
-We need to initialize Mastra with our agent.
-
-```typescript filename="src/index.ts"
-import { Mastra } from "@mastra/core";
-import { weatherAgent } from "./agents/weatherAgent";
-
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-});
-```
-
-This registers your agent with Mastra, making it available for use.
-
-## Abort Signals
-
-The abort signals from `generate` and `stream` (text generation) are forwarded to the tool execution. You can access them in the second parameter of the execute function and e.g. abort long-running computations or forward them to fetch calls inside tools.
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-const agent = new Agent({
-  name: "Weather agent",
-  tools: {
-    weather: createTool({
-      id: "Get Weather Information",
-      description: "Get the weather in a location",
-      inputSchema: z.object({ location: z.string() }),
-      execute: async ({ context: { location } }, { abortSignal }) => {
-        return fetch(
-          `https://api.weatherapi.com/v1/current.json?q=${location}`,
-          { signal: abortSignal }, // forward the abort signal to fetch
-        );
-      },
-    }),
-  },
-});
-
-const result = await agent.generate("What is the weather in San Francisco?", {
-  abortSignal: myAbortSignal, // signal that will be forwarded to tools
-});
-```
-
-## Injecting Request/User-Specific Variables
-
-We support dependency injection for tools and workflows. You can pass a runtimeContext directly to your `generate` or `stream` function calls, or inject it using [server middleware](/docs/deployment/server#Middleware).
-
-Here's an example where we change the temperature scale between Fahrenheit and Celsius:
-
-```typescript filename="src/agents/weather-agent.ts"
-import { Agent } from "@mastra/core/agent";
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const agent = new Agent({
-  name: "Weather agent",
-  tools: {
-    weather: createTool({
-      id: "Get Weather Information",
-      description: "Get the weather in a location",
-      inputSchema: z.object({ location: z.string() }),
-      execute: async ({ context: { location }, runtimeContext }) => {
-        const scale = runtimeContext.get("temperature-scale");
-
-        const result = await fetch(
-          `https://api.weatherapi.com/v1/current.json?q=${location}`,
-        );
-
-        const json = await result.json();
-
-        return {
-          temperature: scale === "celsius" ? json.temp_c : json.temp_f,
-        };
-      },
-    }),
-  },
-});
-```
-
-```typescript
-import { agent } from "./agents/weather";
-
-type MyRuntimeContext = {"temperature-scale", "celsius" | "farenheit"}
-
-const runtimeContext = new RuntimeContext<MyRuntimeContext>();
-runtimeContext.set("temperature-scale", "celsius");
-
-const result = await agent.generate("What is the weather in San Francisco?", {
-  runtimeContext,
-});
-```
-
-## Debugging Tools
-
-You can test tools using Vitest or any other testing framework. Writing unit tests for your tools ensures they behave as expected and helps catch errors early.
-
-## Calling an Agent with a Tool
-
-Now we can call the agent, and it will use the tool to fetch the weather information.
-
-## Example: Interacting with the Agent
-
-```typescript filename="src/index.ts"
-import { mastra } from "./index";
-
-async function main() {
-  const agent = mastra.getAgent("weatherAgent");
-  const response = await agent.generate(
-    "What's the weather like in New York City today?",
-  );
-
-  console.log(response.text);
-}
-
-main();
-```
-
-The agent will use the `weatherInfo` tool to get the current weather in New York City and respond accordingly.
-
-## Vercel AI SDK Tool Format
-
-Mastra supports tools created using the Vercel AI SDK format. You can import and use these tools directly:
-
-```typescript filename="src/mastra/tools/vercelTool.ts" copy
-import { tool } from "ai";
-import { z } from "zod";
-
-export const weatherInfo = tool({
-  description: "Fetches the current weather information for a given city",
-  parameters: z.object({
-    city: z.string().describe("The city to get weather for"),
-  }),
-  execute: async ({ city }) => {
-    // Replace with actual API call
-    const data = await fetch(`https://api.example.com/weather?city=${city}`);
-    return data.json();
-  },
-});
-```
-
-You can use Vercel tools alongside Mastra tools in your agents:
-
-```typescript filename="src/mastra/agents/weatherAgent.ts"
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-import { weatherInfo } from "../tools/vercelTool";
-import * as mastraTools from "../tools/mastraTools";
-
-export const weatherAgent = new Agent({
-  name: "Weather Agent",
-  instructions:
-    "You are a helpful assistant that provides weather information.",
-  model: openai("gpt-4"),
-  tools: {
-    weatherInfo, // Vercel tool
-    ...mastraTools, // Mastra tools
-  },
-});
-```
-
-Both tool formats will work seamlessly within your agent's workflow.
-
-## Tool Design Best Practices
-
-When creating tools for your agents, following these guidelines will help ensure reliable and intuitive tool usage:
-
-### Tool Descriptions
-
-Your tool's main description should focus on its purpose and value:
-
-- Keep descriptions simple and focused on **what** the tool does
-- Emphasize the tool's primary use case
-- Avoid implementation details in the main description
-- Focus on helping the agent understand **when** to use the tool
-
-```typescript
-createTool({
-  id: "documentSearch",
-  description:
-    "Access the knowledge base to find information needed to answer user questions",
-  // ... rest of tool configuration
-});
-```
-
-### Parameter Schemas
-
-Technical details belong in the parameter schemas, where they help the agent use the tool correctly:
-
-- Make parameters self-documenting with clear descriptions
-- Include default values and their implications
-- Provide examples where helpful
-- Describe the impact of different parameter choices
-
-```typescript
-inputSchema: z.object({
-  query: z.string().describe("The search query to find relevant information"),
-  limit: z.number().describe(
-    "Number of results to return. Higher values provide more context, lower values focus on best matches"
-  ),
-  options: z.string().describe(
-    "Optional configuration. Example: '{'filter': 'category=news'}'"
-  ),
-}),
-```
-
-### Agent Interaction Patterns
-
-Tools are more likely to be used effectively when:
-
-- Queries or tasks are complex enough to clearly require tool assistance
-- Agent instructions provide clear guidance on tool usage
-- Parameter requirements are well-documented in the schema
-- The tool's purpose aligns with the query's needs
-
-### Common Pitfalls
-
-- Overloading the main description with technical details
-- Mixing implementation details with usage guidance
-- Unclear parameter descriptions or missing examples
-
-Following these practices helps ensure your tools are discoverable and usable by agents while maintaining clean separation between purpose (main description) and implementation details (parameter schemas).
-
-## Model Context Protocol (MCP) Tools
-
-Mastra also supports tools from MCP-compatible servers through the `@mastra/mcp` package. MCP provides a standardized way for AI models to discover and interact with external tools and resources. This makes it easy to integrate third-party tools into your agents without writing custom integrations.
-
-For detailed information about using MCP tools, including configuration options and best practices, see our [MCP guide](/docs/agents/mcp-guide).
diff --git a/docs/src/content/en/docs/agents/mcp-guide.mdx b/docs/src/content/en/docs/agents/mcp-guide.mdx
deleted file mode 100644
index 839c338dac0..00000000000
--- a/docs/src/content/en/docs/agents/mcp-guide.mdx
+++ /dev/null
@@ -1,286 +0,0 @@
----
-title: "Using MCP With Mastra | Agents | Mastra Docs"
-description: "Use MCP in Mastra to integrate third party tools and resources in your AI agents."
----
-
-# Using MCP With Mastra
-
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is a standardized way for AI models to discover and interact with external tools and resources.
-
-## Overview
-
-MCP in Mastra provides a standardized way to connect to tool servers. It supports Stdio and HTTP (uses Streamable HTTP, falls back to SSE).
-
-## Installation
-
-Using pnpm:
-
-```bash
-pnpm add @mastra/mcp@latest
-```
-
-Using npm:
-
-```bash copy
-npm install @mastra/mcp@latest
-```
-
-## Using MCP in Your Code
-
-The `MCPClient` class provides a way to manage multiple tool servers in your Mastra applications without managing multiple MCP clients. The `MastraMCPClient` used internally by `MCPConfiguration` now automatically detects the transport type based on your server configuration:
-
--   If you provide a `command`, it uses the Stdio transport.
--   If you provide a `url`, it first attempts to use the Streamable HTTP transport and falls back to the legacy SSE transport if the initial connection fails.
-
-Here's an example configuration:
-
-```typescript
-import { MCPClient } from "@mastra/mcp";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-
-const mcp = new MCPClient({
-  servers: {
-    // Stdio example
-    sequential: {
-      command: "npx",
-      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-    },
-    // HTTP example (will try Streamable HTTP first, then fallback to SSE)
-    weather: {
-      url: new URL("http://localhost:8080/mcp"), // Use the base URL for Streamable HTTP
-      requestInit: {
-        headers: {
-          Authorization: "Bearer your-token",
-        },
-      },
-    },
-  },
-});
-```
-
-### Tools vs Toolsets
-
-The `MCPClient` class provides two ways to access MCP tools, each suited for different use cases:
-
-#### Using Tools (`getTools()`)
-
-Use this approach when:
-
-- You have a single MCP connection
-- The tools are used by a single user/context
-- Tool configuration (API keys, credentials) remains constant
-- You want to initialize an Agent with a fixed set of tools
-
-```typescript
-const agent = new Agent({
-  name: "CLI Assistant",
-  instructions: "You help users with CLI tasks",
-  model: openai("gpt-4o-mini"),
-  tools: await mcp.getTools(), // Tools are fixed at agent creation
-});
-```
-
-#### Using Toolsets (`getToolsets()`)
-
-Use this approach when:
-
-- You need per-request tool configuration
-- Tools need different credentials per user
-- Running in a multi-user environment (web app, API, etc)
-- Tool configuration needs to change dynamically
-
-```typescript
-const mcp = new MCPClient({
-  servers: {
-    example: {
-      command: "npx",
-      args: ["-y", "@example/fakemcp"],
-      env: {
-        API_KEY: "your-api-key",
-      },
-    },
-  },
-});
-
-// Get the current toolsets configured for this user
-const toolsets = await mcp.getToolsets();
-
-// Use the agent with user-specific tool configurations
-const response = await agent.stream(
-  "What's new in Mastra and how's the weather?",
-  {
-    toolsets,
-  },
-);
-```
-
-## MCP Registries
-
-MCP servers can be accessed through registries that provide curated collections of tools.
-We've curated an [MCP Registry Registry](https://mastra.ai/mcp-registry-registry) to help you find the best places to source MCP servers, but here's how you can use tools from some of our favorites:
-
-### mcp.run Registry
-
-[mcp.run](https://www.mcp.run/) makes it easy for you to call pre-authenticated, secure MCP Servers. The tools from mcp.run are free, and entirely managed, so your agent only needs a SSE URL and can use any tools a user has installed. MCP Servers are grouped into [Profiles](https://docs.mcp.run/user-guide/manage-profiles), and accessed with a unique SSE URL.
-
-For each Profile, you can copy/paste unique, signed URLs into your `MCPClient` like this:
-
-```typescript
-const mcp = new MCPClient({
-  servers: {
-    marketing: {
-      url: new URL(process.env.MCP_RUN_SSE_URL!),
-    },
-  },
-});
-```
-
-> Important: Each SSE URL on on [mcp.run](https://mcp.run) contains a unique signature, that should be treated like a password. It's best to read your SSE URL as an environment variable and manage it outside of your application code.
-
-```bash filename=".env" copy
-MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
-```
-
-### Composio.dev Registry
-
-[Composio.dev](https://composio.dev) provides a registry of [SSE-based MCP servers](https://mcp.composio.dev) that can be easily integrated with Mastra. The SSE URL that's generated for Cursor is compatible with Mastra - you can use it directly in your configuration:
-
-```typescript
-const mcp = new MCPClient({
-  servers: {
-    googleSheets: {
-      url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
-    },
-    gmail: {
-      url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
-    },
-  },
-});
-```
-
-When using Composio-provided tools, you can authenticate with services (like Google Sheets or Gmail) directly through conversation with your agent. The tools include authentication capabilities that guide you through the process while chatting.
-
-Note: The Composio.dev integration is best suited for single-user scenarios like personal automation, as the SSE URL is tied to your account and can't be used for multiple users. Each URL represents a single account's authentication context.
-
-### Smithery.ai Registry
-
-[Smithery.ai](https://smithery.ai) provides a registry of MCP servers that you can easily use with Mastra:
-
-```typescript
-// Unix/Mac
-const mcp = new MCPClient({
-  servers: {
-    sequentialThinking: {
-      command: "npx",
-      args: [
-        "-y",
-        "@smithery/cli@latest",
-        "run",
-        "@smithery-ai/server-sequential-thinking",
-        "--config",
-        "{}",
-      ],
-    },
-  },
-});
-
-// Windows
-const mcp = new MCPClient({
-  servers: {
-    sequentialThinking: {
-      command: "cmd",
-      args: [
-        "/c",
-        "npx",
-        "-y",
-        "@smithery/cli@latest",
-        "run",
-        "@smithery-ai/server-sequential-thinking",
-        "--config",
-        "{}",
-      ],
-    },
-  },
-});
-```
-
-This example is adapted from the Claude integration example in the Smithery documentation.
-
-## Excluding Tools in Your MCP Server
-
-The tools from your MCP server are returned as a plain JavaScript object when you call `await mcp.getTools()` or `await mcp.getToolsets()`. This means you can easily filter or exclude tools before passing them to your agent.
-
-### Excluding Tools Examples
-
-Suppose your MCP server exposes three tools: `weather`, `stockPrice`, and `news`, but you want to exclude the `news` tool from your agent. You can do this by filtering the tools object:
-
-```typescript
-import { MCPClient } from "@mastra/mcp";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-
-const mcp = new MCPClient({
-  servers: {
-    myServer: {
-      command: "npx",
-      args: ["tsx", "my-mcp-server.ts"],
-    },
-  },
-});
-
-// Get all tools from the MCP server
-const allTools = await mcp.getTools();
-
-// Exclude the 'news' tool (tool names are namespaced as 'serverName_toolName')
-const filteredTools = Object.fromEntries(
-  Object.entries(allTools).filter(([toolName]) => toolName !== "myServer_news")
-);
-
-// Pass only the filtered tools to your agent
-const agent = new Agent({
-  name: "Selective Agent",
-  instructions: "You can access only selected tools.",
-  model: openai("gpt-4"),
-  tools: filteredTools,
-});
-```
-
-You can use any logic in the `.filter()` function to exclude tools by name, type, or any other property. This approach works the same way for `getToolsets()` if you want to filter toolsets dynamically per request.
-
-Another approach is to destructure the tools you want to use, or exclude the tools you do not want.
-
-```typescript
-// Remove the undesired tool from the destructed object
-const { myServer_news, ...filteredTools } = await mcp.getTools();
-
-// Pass only the filtered tools to your agent
-const agent = new Agent({
-  name: "Selective Agent",
-  instructions: "You can access only selected tools.",
-  model: openai("gpt-4"),
-  tools: filteredTools,
-});
-```
-
-```typescript
-// Select the desired tools from the destructed object
-const { myServer_weather, myServer_stockPrice } = await mcp.getTools();
-
-// Pass only the filtered tools to your agent
-const agent = new Agent({
-  name: "Selective Agent",
-  instructions: "You can access only selected tools.",
-  model: openai("gpt-4"),
-  tools: { myServer_weather, myServer_stockPrice },
-});
-```
-
-## Using the Mastra Documentation Server
-
-Looking to use Mastra's MCP documentation server in your IDE? Check out our [MCP Documentation Server guide](/docs/getting-started/mcp-docs-server) to get started.
-
-## Next Steps
-
-- Learn more about [MCPClient](/reference/tools/mcp-client)
-- Check out our [example projects](/examples) that use MCP
diff --git a/docs/src/content/en/docs/agents/overview.mdx b/docs/src/content/en/docs/agents/overview.mdx
index 898b08b16ee..c320f9bf4f6 100644
--- a/docs/src/content/en/docs/agents/overview.mdx
+++ b/docs/src/content/en/docs/agents/overview.mdx
@@ -299,5 +299,5 @@ curl -X POST http://localhost:4111/api/agents/myAgent/generate \
 ## Next Steps
 
 - Learn about Agent Memory in the [Agent Memory](./agent-memory.mdx) guide.
-- Learn about Agent Tools in the [Agent Tools](./adding-tools.mdx) guide.
+- Learn about Agent Tools in the [Agent Tools and MCP](./using-tools-and-mcp.mdx) guide.
 - See an example agent in the [Chef Michel](../../guides/guide/chef-michel.mdx) example.
diff --git a/docs/src/content/en/docs/agents/using-tools-and-mcp.mdx b/docs/src/content/en/docs/agents/using-tools-and-mcp.mdx
new file mode 100644
index 00000000000..02407b84557
--- /dev/null
+++ b/docs/src/content/en/docs/agents/using-tools-and-mcp.mdx
@@ -0,0 +1,109 @@
+---
+title: "Using Tools with Agents | Agents | Mastra Docs"
+description: Learn how to create tools, add them to Mastra agents, and integrate tools from MCP servers.
+---
+
+# 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:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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](/docs/tools-mcp/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.
+
+```typescript filename="src/mastra/agents/weatherAgent.ts" {3,11}
+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)](https://modelcontextprotocol.io/introduction) 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](/docs/tools-mcp/mcp-overview).
+
+### Installation
+
+First, install the Mastra MCP package:
+
+```bash npm2yarn copy
+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](https://mastra.ai/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.
+
+```typescript filename="src/mastra/mcp.ts" {1,7-16}
+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:
+
+```typescript filename="src/mastra/agents/mcpAgent.ts" {7}
+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](/docs/tools-mcp/mcp-overview).
diff --git a/docs/src/content/en/docs/integrations/_meta.ts b/docs/src/content/en/docs/integrations/_meta.ts
deleted file mode 100644
index e8469caaac2..00000000000
--- a/docs/src/content/en/docs/integrations/_meta.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Meta } from "nextra";
-
-const meta: Meta = {
-  index: {
-    title: "Overview",
-  },
-};
-
-export default meta;
diff --git a/docs/src/content/en/docs/integrations/index.mdx b/docs/src/content/en/docs/integrations/index.mdx
deleted file mode 100644
index 52b27d8106d..00000000000
--- a/docs/src/content/en/docs/integrations/index.mdx
+++ /dev/null
@@ -1,213 +0,0 @@
----
-title: "Using Mastra Integrations | Mastra Local Development Docs"
-description: Documentation for Mastra integrations, which are auto-generated, type-safe API clients for third-party services.
----
-
-# Using Mastra Integrations
-
-Integrations in Mastra are auto-generated, type-safe API clients for third-party services. They can be used as tools for agents or as steps in workflows.
-
-## Installing an Integration
-
-Mastra's default integrations are packaged as individually installable npm modules. You can add an integration to your project by installing it via npm and importing it into your Mastra configuration.
-
-### Example: Adding the GitHub Integration
-
-1. **Install the Integration Package**
-
-To install the GitHub integration, run:
-
-```bash copy
-npm install @mastra/github@latest
-```
-
-2. **Add the Integration to Your Project**
-
-Create a new file for your integrations (e.g., `src/mastra/integrations/index.ts`) and import the integration:
-
-```typescript filename="src/mastra/integrations/index.ts" showLineNumbers copy
-import { GithubIntegration } from "@mastra/github";
-
-export const github = new GithubIntegration({
-  config: {
-    PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PAT!,
-  },
-});
-```
-
-Make sure to replace `process.env.GITHUB_PAT!` with your actual GitHub Personal Access Token or ensure that the environment variable is properly set.
-
-3. **Use the Integration in Tools or Workflows**
-
-You can now use the integration when defining tools for your agents or in workflows.
-
-```typescript filename="src/mastra/tools/index.ts" showLineNumbers copy
-import { createTool } from "@mastra/core";
-import { z } from "zod";
-import { github } from "../integrations";
-
-export const getMainBranchRef = createTool({
-  id: "getMainBranchRef",
-  description: "Fetch the main branch reference from a GitHub repository",
-  inputSchema: z.object({
-    owner: z.string(),
-    repo: z.string(),
-  }),
-  outputSchema: z.object({
-    ref: z.string().optional(),
-  }),
-  execute: async ({ context }) => {
-    const client = await github.getApiClient();
-
-    const mainRef = await client.gitGetRef({
-      path: {
-        owner: context.owner,
-        repo: context.repo,
-        ref: "heads/main",
-      },
-    });
-
-    return { ref: mainRef.data?.ref };
-  },
-});
-```
-
-In the example above:
-
-- We import the `github` integration.
-- We define a tool called `getMainBranchRef` that uses the GitHub API client to fetch the reference of the main branch of a repository.
-- The tool accepts `owner` and `repo` as inputs and returns the reference string.
-
-## Using Integrations in Agents
-
-Once you've defined tools that utilize integrations, you can include these tools in your agents.
-
-```typescript filename="src/mastra/agents/index.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { getMainBranchRef } from "../tools";
-
-export const codeReviewAgent = new Agent({
-  name: "Code Review Agent",
-  instructions:
-    "An agent that reviews code repositories and provides feedback.",
-  model: openai("gpt-4o-mini"),
-  tools: {
-    getMainBranchRef,
-    // other tools...
-  },
-});
-```
-
-In this setup:
-
-- We create an agent named `Code Review Agent`.
-- We include the `getMainBranchRef` tool in the agent's available tools.
-- The agent can now use this tool to interact with GitHub repositories during conversations.
-
-## Environment Configuration
-
-Ensure that any required API keys or tokens for your integrations are properly set in your environment variables. For example, with the GitHub integration, you need to set your GitHub Personal Access Token:
-
-```bash
-GITHUB_PAT=your_personal_access_token
-```
-
-Consider using a `.env` file or another secure method to manage sensitive credentials.
-
-### Example: Adding the Mem0 Integration
-
-In this example you'll learn how to use the [Mem0](https://mem0.ai) platform to add long-term memory capabilities to an agent via tool-use.
-This memory integration can work alongside Mastra's own [agent memory features](https://mastra.ai/docs/agents/agent-memory).
-Mem0 enables your agent to memorize and later remember facts per-user across all interactions with that user, while Mastra's memory works per-thread. Using the two in conjunction will allow Mem0 to store long term memories across conversations/interactions, while Mastra's memory will maintain linear conversation history in individual conversations.
-
-1. **Install the Integration Package**
-
-To install the Mem0 integration, run:
-
-```bash copy
-npm install @mastra/mem0@latest
-```
-
-2. **Add the Integration to Your Project**
-
-Create a new file for your integrations (e.g., `src/mastra/integrations/index.ts`) and import the integration:
-
-```typescript filename="src/mastra/integrations/index.ts" showLineNumbers copy
-import { Mem0Integration } from "@mastra/mem0";
-
-export const mem0 = new Mem0Integration({
-  config: {
-    apiKey: process.env.MEM0_API_KEY!,
-    userId: "alice",
-  },
-});
-```
-
-3. **Use the Integration in Tools or Workflows**
-
-You can now use the integration when defining tools for your agents or in workflows.
-
-```typescript filename="src/mastra/tools/index.ts" showLineNumbers copy
-import { createTool } from "@mastra/core";
-import { z } from "zod";
-import { mem0 } from "../integrations";
-
-export const mem0RememberTool = createTool({
-  id: "Mem0-remember",
-  description:
-    "Remember your agent memories that you've previously saved using the Mem0-memorize tool.",
-  inputSchema: z.object({
-    question: z
-      .string()
-      .describe("Question used to look up the answer in saved memories."),
-  }),
-  outputSchema: z.object({
-    answer: z.string().describe("Remembered answer"),
-  }),
-  execute: async ({ context }) => {
-    console.log(`Searching memory "${context.question}"`);
-    const memory = await mem0.searchMemory(context.question);
-    console.log(`\nFound memory "${memory}"\n`);
-
-    return {
-      answer: memory,
-    };
-  },
-});
-
-export const mem0MemorizeTool = createTool({
-  id: "Mem0-memorize",
-  description:
-    "Save information to mem0 so you can remember it later using the Mem0-remember tool.",
-  inputSchema: z.object({
-    statement: z.string().describe("A statement to save into memory"),
-  }),
-  execute: async ({ context }) => {
-    console.log(`\nCreating memory "${context.statement}"\n`);
-    // to reduce latency memories can be saved async without blocking tool execution
-    void mem0.createMemory(context.statement).then(() => {
-      console.log(`\nMemory "${context.statement}" saved.\n`);
-    });
-    return { success: true };
-  },
-});
-```
-
-In the example above:
-
-- We import the `@mastra/mem0` integration.
-- We define two tools that uses the Mem0 API client to create new memories and recall previously saved memories.
-- The tool accepts `question` as an input and returns the memory as a string.
-
-## Available Integrations
-
-Mastra provides several built-in integrations; primarily API-key based integrations that do not require OAuth. Some available integrations including Github, Stripe, Resend, Firecrawl, and more.
-
-Check [Mastra's codebase](https://github.com/mastra-ai/mastra/tree/main/integrations) or [npm packages](https://www.npmjs.com/search?q=%22%40mastra%22) for a full list of available integrations.
-
-## Conclusion
-
-Integrations in Mastra enable your AI agents and workflows to interact with external services seamlessly. By installing and configuring integrations, you can extend the capabilities of your application to include operations such as fetching data from APIs, sending messages, or managing resources in third-party systems.
-
-Remember to consult the documentation of each integration for specific usage details and to adhere to best practices for security and type safety.
diff --git a/docs/src/content/en/docs/tools-mcp/_meta.ts b/docs/src/content/en/docs/tools-mcp/_meta.ts
new file mode 100644
index 00000000000..8310c9329f1
--- /dev/null
+++ b/docs/src/content/en/docs/tools-mcp/_meta.ts
@@ -0,0 +1,8 @@
+const meta = {
+  overview: "Overview",
+  "mcp-overview": "MCP Overview",
+  "dynamic-context": "Dynamic Tool Context",
+  "advanced-usage": "Advanced Usage",
+};
+
+export default meta;
diff --git a/docs/src/content/en/docs/tools-mcp/advanced-usage.mdx b/docs/src/content/en/docs/tools-mcp/advanced-usage.mdx
new file mode 100644
index 00000000000..33db3a3c191
--- /dev/null
+++ b/docs/src/content/en/docs/tools-mcp/advanced-usage.mdx
@@ -0,0 +1,129 @@
+---
+title: "Advanced Tool Usage | Tools & MCP | Mastra Docs"
+description: This page covers advanced features for Mastra tools, including abort signals and compatibility with the Vercel AI SDK tool format.
+---
+
+# Advanced Tool Usage
+
+This page covers more advanced techniques and features related to using tools in Mastra.
+
+## Abort Signals
+
+When you initiate an agent interaction using `generate()` or `stream()`, you can provide an `AbortSignal`. Mastra automatically forwards this signal to any tool executions that occur during that interaction.
+
+This allows you to cancel long-running operations within your tools, such as network requests or intensive computations, if the parent agent call is aborted.
+
+You access the `abortSignal` in the second parameter of the tool's `execute` function.
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const longRunningTool = createTool({
+  id: "long-computation",
+  description: "Performs a potentially long computation",
+  inputSchema: z.object({ /* ... */ }),
+  execute: async ({ context }, { abortSignal }) => {
+    // Example: Forwarding signal to fetch
+    const response = await fetch("https://api.example.com/data", {
+      signal: abortSignal, // Pass the signal here
+    });
+
+    if (abortSignal?.aborted) {
+      console.log("Tool execution aborted.");
+      throw new Error("Aborted");
+    }
+
+    // Example: Checking signal during a loop
+    for (let i = 0; i < 1000000; i++) {
+      if (abortSignal?.aborted) {
+        console.log("Tool execution aborted during loop.");
+        throw new Error("Aborted");
+      }
+      // ... perform computation step ...
+    }
+
+    const data = await response.json();
+    return { result: data };
+  },\n});
+```
+
+To use this, provide an `AbortController`'s signal when calling the agent:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+// Assume 'agent' is an Agent instance with longRunningTool configured
+
+const controller = new AbortController();
+
+// Start the agent call
+const promise = agent.generate("Perform the long computation.", {
+  abortSignal: controller.signal,
+});
+
+// Sometime later, if needed:
+// controller.abort();
+
+try {
+  const result = await promise;
+  console.log(result.text);
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log("Agent generation was aborted.");
+  } else {
+    console.error("An error occurred:", error);
+  }
+}
+```
+
+## AI SDK Tool Format
+
+Mastra maintains compatibility with the tool format used by the Vercel AI SDK (`ai` package). You can define tools using the `tool` function from the `ai` package and use them directly within your Mastra agents alongside tools created with Mastra's `createTool`.
+
+First, ensure you have the `ai` package installed:
+
+```bash npm2yarn copy
+npm install ai
+```
+
+Here's an example of a tool defined using the Vercel AI SDK format:
+
+```typescript filename="src/mastra/tools/vercelWeatherTool.ts" copy
+import { tool } from "ai";
+import { z } from "zod";
+
+export const vercelWeatherTool = tool({
+  description: "Fetches current weather using Vercel AI SDK format",
+  parameters: z.object({
+    city: z.string().describe("The city to get weather for"),
+  }),
+  execute: async ({ city }) => {
+    console.log(`Fetching weather for ${city} (Vercel format tool)`);
+    // Replace with actual API call
+    const data = await fetch(`https://api.example.com/weather?city=${city}`);
+    return data.json();
+  },
+});
+```
+
+You can then add this tool to your Mastra agent just like any other tool:
+
+```typescript filename="src/mastra/agents/mixedToolsAgent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK tool
+import { mastraTool } from "../tools/mastraTool"; // Mastra createTool tool
+
+export const mixedToolsAgent = new Agent({
+  name: "Mixed Tools Agent",
+  instructions:
+    "You can use tools defined in different formats.",
+  model: openai("gpt-4o-mini"),
+  tools: {
+    weatherVercel: vercelWeatherTool,
+    someMastraTool: mastraTool,
+  },
+});
+```
+
+Mastra supports both tool formats, allowing you to mix and match as needed.
diff --git a/docs/src/content/en/docs/tools-mcp/dynamic-context.mdx b/docs/src/content/en/docs/tools-mcp/dynamic-context.mdx
new file mode 100644
index 00000000000..c45e3ab0e43
--- /dev/null
+++ b/docs/src/content/en/docs/tools-mcp/dynamic-context.mdx
@@ -0,0 +1,126 @@
+---
+title: "Dynamic Tool Context | Tools & MCP | Mastra Docs"
+description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to tools.
+---
+
+import { Callout } from "nextra/components";
+
+# Dynamic Tool Context
+
+Mastra provides `RuntimeContext`, a system based on dependency injection, that allows you to pass dynamic, request-specific configuration to your tools during execution. This is useful when a tool's behavior needs to change based on user identity, request headers, or other runtime factors, without altering the tool's core code.
+
+<Callout>
+  **Note:** `RuntimeContext` is primarily used for passing data *into* tool executions. It's distinct from agent memory, which handles conversation history and state persistence across multiple calls.
+</Callout>
+
+## Basic Usage
+
+To use `RuntimeContext`, first define a type structure for your dynamic configuration. Then, create an instance of `RuntimeContext` typed with your definition and set the desired values. Finally, include the `runtimeContext` instance in the options object when calling `agent.generate()` or `agent.stream()`.
+
+```typescript
+import { RuntimeContext } from "@mastra/core/di";
+// Assume 'agent' is an already defined Mastra Agent instance
+
+// Define the context type
+type WeatherRuntimeContext = {
+  "temperature-scale": "celsius" | "fahrenheit";
+};
+
+// Instantiate RuntimeContext and set values
+const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();
+runtimeContext.set("temperature-scale", "celsius");
+
+// Pass to agent call
+const response = await agent.generate("What's the weather like today?", {
+  runtimeContext, // Pass the context here
+});
+
+console.log(response.text);
+```
+
+## Accessing Context in Tools
+
+Tools receive the `runtimeContext` as part of the second argument to their `execute` function. You can then use the `.get()` method to retrieve values.
+
+```typescript filename="src/mastra/tools/weather-tool.ts"
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+// Assume WeatherRuntimeContext is defined as above and accessible here
+
+// Dummy fetch function
+async function fetchWeather(
+  location: string,
+  options: { temperatureUnit: "celsius" | "fahrenheit" }
+): Promise<any> {
+  console.log(`Fetching weather for ${location} in ${options.temperatureUnit}`);
+  // Replace with actual API call
+  return { temperature: options.temperatureUnit === "celsius" ? 20 : 68 };
+}
+
+export const weatherTool = createTool({
+  id: "getWeather",
+  description: "Get the current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("The location to get weather for"),
+  }),
+  // The tool's execute function receives runtimeContext
+  execute: async ({ context, runtimeContext }) => {
+    // Type-safe access to runtimeContext variables
+    const temperatureUnit = runtimeContext.get("temperature-scale");
+
+    // Use the context value in the tool logic
+    const weather = await fetchWeather(context.location, {
+      temperatureUnit,
+    });
+
+    return { result: `The temperature is ${weather.temperature}°${temperatureUnit === "celsius" ? "C" : "F"}` };
+  },
+});
+```
+
+When the agent uses `weatherTool`, the `temperature-scale` value set in the `runtimeContext` during the `agent.generate()` call will be available inside the tool's `execute` function.
+
+## Using with Server Middleware
+
+In server environments (like Express or Next.js), you can use middleware to automatically populate `RuntimeContext` based on incoming request data, such as headers or user sessions.
+
+Here's an example using Mastra's built-in server middleware support (which uses Hono internally) to set the temperature scale based on the Cloudflare `CF-IPCountry` header:
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { RuntimeContext } from "@mastra/core/di";
+import { weatherAgent } from "./agents/weather"; // Assume agent is defined elsewhere
+
+// Define RuntimeContext type
+type WeatherRuntimeContext = {
+  "temperature-scale": "celsius" | "fahrenheit";
+};
+
+export const mastra = new Mastra({
+  agents: {
+    weather: weatherAgent,
+  },
+  server: {
+    middleware: [
+      async (c, next) => {
+        // Get the RuntimeContext instance
+        const runtimeContext = c.get<RuntimeContext<WeatherRuntimeContext>>("runtimeContext");
+
+        // Get country code from request header
+        const country = c.req.header("CF-IPCountry");
+
+        // Set temperature scale based on country
+        runtimeContext.set(
+          "temperature-scale",
+          country === "US" ? "fahrenheit" : "celsius",
+        );
+
+        // Continue request processing
+        await next();
+      },
+    ],
+  },
+});
+```
+
+With this middleware in place, any agent call handled by this Mastra server instance will automatically have the `temperature-scale` set in its `RuntimeContext` based on the user's inferred country, and tools like `weatherTool` will use it accordingly.
diff --git a/docs/src/content/en/docs/tools-mcp/mcp-overview.mdx b/docs/src/content/en/docs/tools-mcp/mcp-overview.mdx
new file mode 100644
index 00000000000..e776617db4a
--- /dev/null
+++ b/docs/src/content/en/docs/tools-mcp/mcp-overview.mdx
@@ -0,0 +1,224 @@
+---
+title: "MCP Overview | Tools & MCP | Mastra Docs"
+description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+---
+
+import { Tabs } from "nextra/components";
+
+# MCP Overview
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard designed to let AI models discover and interact with external tools and resources. Think of it as a universal plugin system for AI agents, allowing them to use tools regardless of the language they were written in or where they are hosted.
+
+Mastra uses MCP to connect agents to external tool servers.
+
+## Use third-party tools with an MCP Client
+
+Mastra provides the `MCPClient` class to manage connections to one or more MCP servers and access their tools.
+
+### Installation
+
+If you haven't already, install the Mastra MCP package:
+
+```bash npm2yarn copy
+npm install @mastra/mcp@latest
+```
+
+### Configuring `MCPClient`
+
+You configure `MCPClient` with a map of servers you want to connect to. It supports connections via subprocess (Stdio) or HTTP (Streamable HTTP with SSE fallback).
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    // Stdio example
+    sequential: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    },
+    // HTTP example
+    weather: {
+      url: new URL("http://localhost:8080/mcp"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+For detailed configuration options, see the [`MCPClient` reference documentation](/reference/tools/mcp-client).
+
+### Static vs Dynamic Tool Configurations
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature          | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
+| :--------------- | :-------------------------------------------- | :---------------------------------------------------- |
+| **Use Case**     | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app)         |
+| **Configuration**| Fixed at agent initialization                 | Per-request, dynamic                                |
+| **Credentials**  | Shared across all uses                        | Can vary per user/request                             |
+| **Agent Setup**  | Tools added in `Agent` constructor            | Tools passed in `generate()` or `stream()` options  |
+
+*   **Static Configuration (`getTools()`):** Fetches all tools from all configured servers. Best when the tool configuration (like API keys) is static and shared across all users or requests. You typically call this once and pass the result to the `tools` property when defining your `Agent`.
+    [Reference: `getTools()`](/reference/tools/mcp-client#gettools)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... mcp client setup
+
+    const agent = new Agent({
+      // ... other agent config
+      tools: await mcp.getTools(),
+    });
+    ```
+
+*   **Dynamic Configuration (`getToolsets()`):** Designed for scenarios where configuration might change per request or per user (e.g., different API keys for different tenants in a multi-user application). You pass the result of `getToolsets()` to the `toolsets` option in the agent's `generate()` or `stream()` method.
+    [Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... agent setup without tools initially
+
+    async function handleRequest(userPrompt: string, userApiKey: string) {
+      const userMcp = new MCPClient({ /* config with userApiKey */ });
+      const toolsets = await userMcp.getToolsets();
+
+      const response = await agent.stream(userPrompt, {
+        toolsets, // Pass dynamic toolsets
+      });
+      // ... handle response
+      await userMcp.disconnect();
+    }
+    ```
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here’s how to connect to some popular ones using `MCPClient`:
+
+<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai"]}>
+  <Tabs.Tab>
+    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        marketing: { // Example profile name
+          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+        },
+      },
+    });
+    ```
+
+    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+    > ```bash filename=".env"
+    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+    > ```
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        googleSheets: {
+          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+        },
+        gmail: {
+          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+        },
+      },
+    });
+    ```
+
+    Authentication with services like Google Sheets often happens interactively through the agent conversation.
+
+    *Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications.*
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+    ```typescript
+    // Unix/Mac
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "npx",
+          args: [
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },
+    });
+    ```
+
+    ```typescript
+    // Windows
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "cmd",
+          args: [
+            "/c",
+            "npx",
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },
+    });
+    ```
+
+  </Tabs.Tab>
+</Tabs>
+
+## Share your tools with an MCP server
+
+If you have created your own Mastra tools, you can expose them to any MCP-compatible client using Mastra's `MCPServer` class.
+
+This allows others to use your tools without needing direct access to your codebase.
+
+### Using `MCPServer`
+
+You initialize `MCPServer` with a name, version, and the Mastra tools you want to share.
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import { weatherTool } from "./tools"; // Your Mastra tool
+
+const server = new MCPServer({
+  name: "My Weather Server",
+  version: "1.0.0",
+  tools: { weatherTool }, // Provide your tool(s) here
+});
+
+// Start the server (e.g., using stdio for a CLI tool)
+// await server.startStdio();
+
+// Or integrate with an HTTP server using startSSE()
+// See MCPServer reference for details
+```
+
+For detailed usage and examples, see the [`MCPServer` reference documentation](/reference/tools/mcp-server).
diff --git a/docs/src/content/en/docs/tools-mcp/overview.mdx b/docs/src/content/en/docs/tools-mcp/overview.mdx
new file mode 100644
index 00000000000..3668df92c21
--- /dev/null
+++ b/docs/src/content/en/docs/tools-mcp/overview.mdx
@@ -0,0 +1,55 @@
+---
+title: "Tools Overview | Tools & MCP | Mastra Docs"
+description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
+---
+
+# Tools Overview
+
+Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
+
+Each tool typically defines:
+
+- **Inputs:** What information the tool needs to run (defined with an `inputSchema`, often using Zod).
+- **Outputs:** The structure of the data the tool returns (defined with an `outputSchema`).
+- **Execution Logic:** The code that performs the tool's action.
+- **Description:** Text that helps the agent understand what the tool does and when to use it.
+
+## Creating Tools
+
+In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const getWeatherInfo = async (city: string) => {
+  // Replace with an actual API call to a weather service
+  console.log(`Fetching weather for ${city}...`);
+  // Example data structure
+  return { temperature: 20, conditions: "Sunny" };
+};
+
+export const weatherTool = createTool({
+  id: "Get Weather Information",
+  description: `Fetches the current weather information for a given city`,
+  inputSchema: z.object({
+    city: z.string().describe("City name"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async ({ context: { city } }) => {
+    console.log("Using tool to fetch weather information for", city);
+    return await getWeatherInfo(city);
+  },
+});
+```
+
+This example defines a `weatherTool` with an input schema for the city, an output schema for the weather data, and an `execute` function that contains the tool's logic.
+
+When creating tools, keep tool descriptions simple and focused on **what** the tool does and **when** to use it, emphasizing its primary use case. Technical details belong in the parameter schemas, guiding the agent on _how_ to use the tool correctly with descriptive names, clear descriptions, and explanations of default values.
+
+## Adding Tools to an Agent
+
+To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools and MCP with Agents](/docs/agents/using-tools-and-mcp#add-tools-to-an-agent).
diff --git a/docs/src/content/en/reference/tools/_meta.ts b/docs/src/content/en/reference/tools/_meta.ts
index 552b738ba14..64ede288961 100644
--- a/docs/src/content/en/reference/tools/_meta.ts
+++ b/docs/src/content/en/reference/tools/_meta.ts
@@ -1,10 +1,14 @@
 const meta = {
+  "create-tool": "createTool()",
+  client: {
+    // deprecated MastraMCPClient
+    display: "hidden",
+  },
+  "mcp-client": "MCPClient",
+  "mcp-server": "MCPServer",
   "document-chunker-tool": "createDocumentChunkerTool()",
   "graph-rag-tool": "createGraphRAGTool()",
   "vector-query-tool": "createVectorQueryTool()",
-  client: "MastraMCPClient",
-  "mcp-client": "MCPClient",
-  "mcp-server": "MCPServer",
 };
 
 export default meta;
diff --git a/docs/src/content/en/reference/tools/create-tool.mdx b/docs/src/content/en/reference/tools/create-tool.mdx
new file mode 100644
index 00000000000..1a6af7ee758
--- /dev/null
+++ b/docs/src/content/en/reference/tools/create-tool.mdx
@@ -0,0 +1,104 @@
+---
+title: "Reference: createTool() | Tools | Mastra Docs"
+description: Documentation for the createTool function in Mastra, used to define custom tools for agents.
+---
+
+# createTool()
+
+The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
+
+## Basic Usage
+
+Here is a basic example of creating a tool that fetches weather information:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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
+  },
+});
+```
+
+## Parameters
+
+The `createTool()` function accepts an object with the following parameters:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "A unique identifier for the tool.",
+      isOptional: false,
+    },
+    {
+      name: "description",
+      type: "string",
+      description:
+        "A description of what the tool does. This is used by the agent to decide when to use the tool.",
+      isOptional: false,
+    },
+    {
+      name: "inputSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the expected input parameters for the tool's `execute` function.",
+      isOptional: true,
+    },
+    {
+      name: "outputSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the expected output structure of the tool's `execute` function.",
+      isOptional: true,
+    },
+    {
+      name: "execute",
+      type: "function",
+      description:
+        "The function that contains the tool's logic. It receives an object with `context` (the parsed input based on `inputSchema`), `runtimeContext`, and an object containing `abortSignal`.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+The `createTool()` function returns a `Tool` object.
+
+<PropertiesTable
+  content={[
+    {
+      name: "Tool",
+      type: "object",
+      description:
+        "An object representing the defined tool, ready to be added to an agent.",
+    },
+  ]}
+/>
+
+## Tool Details
+
+The `Tool` object returned by `createTool()` has the following key properties:
+
+- **ID**: The unique identifier provided in the `id` parameter.
+- **Description**: The description provided in the `description` parameter.
+- **Parameters**: Derived from the `inputSchema`, defining the structure of inputs the tool expects.
+- **Execute Function**: The logic defined in the `execute` parameter, which is called when the agent decides to use the tool.
+
+## Related
+
+- [Tools Overview](/docs/tools-mcp/overview)
+- [Using Tools with Agents](/docs/agents/using-tools-and-mcp)
+- [Dynamic Tool Context](/docs/tools-mcp/dynamic-context)
+- [Advanced Tool Usage](/docs/tools-mcp/advanced-usage)
diff --git a/docs/src/content/en/reference/tools/mcp-client.mdx b/docs/src/content/en/reference/tools/mcp-client.mdx
index 6a4623e7c5b..50f2f37501d 100644
--- a/docs/src/content/en/reference/tools/mcp-client.mdx
+++ b/docs/src/content/en/reference/tools/mcp-client.mdx
@@ -5,7 +5,9 @@ description: API Reference for MCPClient - A class for managing multiple Model C
 
 # MCPClient
 
-The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides convenient access to tools across all configured servers.
+The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
+
+This class replaces the deprecated [`MastraMCPClient`](/reference/tools/client).
 
 ## Constructor
 


Reviews:
user: login: greptile-apps[bot]
body: 
## PR Summary

Major documentation restructuring that consolidates tools and Model Context Protocol (MCP) documentation into a more organized structure, with improved navigation and content organization.

- Created new `/docs/tools-mcp/` section with comprehensive guides for tools, MCP integration, and advanced usage
- Combined `/docs/agents/adding-tools` and `/docs/agents/mcp-guide` into single `/docs/agents/using-tools-and-mcp` guide
- Added collapsible sidebar sections for Tools & MCP, Memory, and Workflows to improve navigation
- Added detailed reference documentation for `createTool()` function and updated MCPClient docs with resource management info
- Redirected `/docs/integrations` content to `/docs/tools-mcp/mcp-overview` for better content organization

<sub>💡 (3/5) Reply to the bot's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>

<sub>16 file(s) reviewed, 13 comment(s)</sub>
<sub>[Edit PR Review Bot Settings](https://app.greptile.com/review/github) | [Greptile](https://greptile.com?utm_source=greptile_expert&utm_medium=github&utm_campaign=code_reviews&utm_content=mastra_4016)</sub>
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-02T17:56:47Z
user: login: calcsam
body: LGTM!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-02T18:56:38Z

Review comments:
diff_hunk: @@ -1,8 +1,7 @@
 const meta = {
   overview: "Overview",
   "agent-memory": "Agent Memory",
-  "adding-tools": "Adding Tools",
-  "mcp-guide": "Using MCP",
+  "using-tools-and-mcp": "Tools and MCP",
path: docs/src/content/en/docs/agents/_meta.ts
user: login: greptile-apps[bot]
body: style: Consider using 'Using Tools and MCP' instead of 'Tools and MCP' for consistency with other action-oriented menu items like 'Adding Voice'
created_at: 2025-05-02T17:54:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+---
+title: "Using Tools with Agents | Agents | Mastra Docs"
+description: Learn how to create tools, add them to Mastra agents, and integrate tools from MCP servers.
+---
+
+# 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:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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.e.g., API call)
path: docs/src/content/en/docs/agents/using-tools-and-mcp.mdx
user: login: greptile-apps[bot]
body: syntax: 'e.e.g.' contains a typo - should be 'e.g.'

```suggestion
    // Tool logic here (e.g., API call)
```
created_at: 2025-05-02T17:55:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+---
+title: "Using Tools with Agents | Agents | Mastra Docs"
+description: Learn how to create tools, add them to Mastra agents, and integrate tools from MCP servers.
+---
+
+# 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:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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.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](/docs/tools-mcp/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.
+
+```typescript filename="src/mastra/agents/weatherAgent.ts" {3,11}
+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)](https://modelcontextprotocol.io/introduction) 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](/docs/tools-mcp/mcp-overview).
+
+### Installation
+
+First, install the Mastra MCP package:
+
+```bash npm2yarn copy
+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](https://mastra.ai/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.
+
+```typescript filename="src/mastra/mcp.ts" {1,7-16}
+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",
path: docs/src/content/en/docs/agents/using-tools-and-mcp.mdx
user: login: greptile-apps[bot]
body: style: Using '/Users/username/Downloads' as an example path is not cross-platform compatible. Consider using a more generic path example
created_at: 2025-05-02T17:55:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+---
+title: "Advanced Tool Usage | Tools & MCP | Mastra Docs"
+description: This page covers advanced features for Mastra tools, including abort signals and compatibility with the Vercel AI SDK tool format.
+---
+
+# Advanced Tool Usage
+
+This page covers more advanced techniques and features related to using tools in Mastra.
+
+## Abort Signals
+
+When you initiate an agent interaction using `generate()` or `stream()`, you can provide an `AbortSignal`. Mastra automatically forwards this signal to any tool executions that occur during that interaction.
+
+This allows you to cancel long-running operations within your tools, such as network requests or intensive computations, if the parent agent call is aborted.
+
+You access the `abortSignal` in the second parameter of the tool's `execute` function.
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const longRunningTool = createTool({
+  id: "long-computation",
+  description: "Performs a potentially long computation",
+  inputSchema: z.object({ /* ... */ }),
+  execute: async ({ context }, { abortSignal }) => {
+    // Example: Forwarding signal to fetch
+    const response = await fetch("https://api.example.com/data", {
+      signal: abortSignal, // Pass the signal here
+    });
+
+    if (abortSignal?.aborted) {
+      console.log("Tool execution aborted.");
+      throw new Error("Aborted");
+    }
+
+    // Example: Checking signal during a loop
+    for (let i = 0; i < 1000000; i++) {
+      if (abortSignal?.aborted) {
+        console.log("Tool execution aborted during loop.");
+        throw new Error("Aborted");
+      }
+      // ... perform computation step ...
+    }
+
+    const data = await response.json();
+    return { result: data };
+  },\n});
+```
+
+To use this, provide an `AbortController`'s signal when calling the agent:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+// Assume 'agent' is an Agent instance with longRunningTool configured
+
+const controller = new AbortController();
+
+// Start the agent call
+const promise = agent.generate("Perform the long computation.", {
+  abortSignal: controller.signal,
+});
+
+// Sometime later, if needed:
+// controller.abort();
+
+try {
+  const result = await promise;
+  console.log(result.text);
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log("Agent generation was aborted.");
+  } else {
+    console.error("An error occurred:", error);
+  }
+}
+```
+
+## AI SDK Tool Format
+
+Mastra maintains compatibility with the tool format used by the Vercel AI SDK (`ai` package). You can define tools using the `tool` function from the `ai` package and use them directly within your Mastra agents alongside tools created with Mastra's `createTool`.
+
+First, ensure you have the `ai` package installed:
+
+```bash npm2yarn copy
+npm install ai
+```
+
+Here's an example of a tool defined using the Vercel AI SDK format:
+
+```typescript filename="src/mastra/tools/vercelWeatherTool.ts" copy
+import { tool } from "ai";
+import { z } from "zod";
+
+export const vercelWeatherTool = tool({
+  description: "Fetches current weather using Vercel AI SDK format",
+  parameters: z.object({
+    city: z.string().describe("The city to get weather for"),
+  }),
+  execute: async ({ city }) => {
+    console.log(`Fetching weather for ${city} (Vercel format tool)`);
+    // Replace with actual API call
+    const data = await fetch(`https://api.example.com/weather?city=${city}`);
+    return data.json();
+  },
+});
+```
+
+You can then add this tool to your Mastra agent just like any other tool:
+
+```typescript filename="src/mastra/agents/mixedToolsAgent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
path: docs/src/content/en/docs/tools-mcp/advanced-usage.mdx
user: login: greptile-apps[bot]
body: logic: Package name should be @mastra/openai instead of @ai-sdk/openai
created_at: 2025-05-02T17:55:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,221 @@
+---
+title: "MCP Overview | Tools & MCP | Mastra Docs"
+description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+---
+
+import { Tabs } from "nextra/components";
+
+# MCP Overview
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard designed to let AI models discover and interact with external tools and resources. Think of it as a universal plugin system for AI agents, allowing them to use tools regardless of the language they were written in or where they are hosted.
+
+Mastra uses MCP to connect agents to external tool servers.
+
+## Use third-party tools with an MCP Client
+
+Mastra provides the `MCPClient` class to manage connections to one or more MCP servers and access their tools.
+
+### Installation
+
+If you haven't already, install the Mastra MCP package:
+
+```bash npm2yarn copy
+npm install @mastra/mcp@latest
+```
+
+### Configuring `MCPClient`
+
+You configure `MCPClient` with a map of servers you want to connect to. It supports connections via subprocess (Stdio) or HTTP (Streamable HTTP with SSE fallback).
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    // Stdio example
+    sequential: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    },
+    // HTTP example
+    weather: {
+      url: new URL("http://localhost:8080/mcp"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+For detailed configuration options, see the [`MCPClient` reference documentation](/reference/tools/mcp-client).
+
+### Static vs Dynamic Tool Configurations
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature          | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
+| :--------------- | :-------------------------------------------- | :---------------------------------------------------- |
+| **Use Case**     | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app)         |
+| **Configuration**| Fixed at agent initialization                 | Per-request, dynamic                                |
+| **Credentials**  | Shared across all uses                        | Can vary per user/request                             |
+| **Agent Setup**  | Tools added in `Agent` constructor            | Tools passed in `generate()` or `stream()` options  |
+
+*   **Static Configuration (`getTools()`):** Fetches all tools from all configured servers. Best when the tool configuration (like API keys) is static and shared across all users or requests. You typically call this once and pass the result to the `tools` property when defining your `Agent`.
+    [Reference: `getTools()`](/reference/tools/mcp-client#gettools)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... mcp client setup
+
+    const agent = new Agent({
+      // ... other agent config
+      tools: await mcp.getTools(),
+    });
+    ```
+
+*   **Dynamic Configuration (`getToolsets()`):** Designed for scenarios where configuration might change per request or per user (e.g., different API keys for different tenants in a multi-user application). You pass the result of `getToolsets()` to the `toolsets` option in the agent's `generate()` or `stream()` method.
+    [Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... agent setup without tools initially
+
+    async function handleRequest(userPrompt: string, userApiKey: string) {
+      const userMcp = new MCPClient({ /* config with userApiKey */ });
+      const toolsets = await userMcp.getToolsets();
+
+      const response = await agent.stream(userPrompt, {
+        toolsets, // Pass dynamic toolsets
+      });
+      // ... handle response
+      await userMcp.disconnect();
+    }
+    ```
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here’s how to connect to some popular ones using `MCPClient`:
+
+<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai"]}>
+  <Tabs.Tab>
+    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        marketing: { // Example profile name
+          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+        },
+      },
+    });
+    ```
+
+    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+    > ```bash filename=".env"
+    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+    > ```
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        googleSheets: {
+          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+        },
+        gmail: {
+          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+        },
+      },\n    });
path: docs/src/content/en/docs/tools-mcp/mcp-overview.mdx
user: login: greptile-apps[bot]
body: syntax: Extra escape character '\n' in the code block

```suggestion
      },
    });
```
created_at: 2025-05-02T17:55:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,221 @@
+---
+title: "MCP Overview | Tools & MCP | Mastra Docs"
+description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+---
+
+import { Tabs } from "nextra/components";
+
+# MCP Overview
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard designed to let AI models discover and interact with external tools and resources. Think of it as a universal plugin system for AI agents, allowing them to use tools regardless of the language they were written in or where they are hosted.
+
+Mastra uses MCP to connect agents to external tool servers.
+
+## Use third-party tools with an MCP Client
+
+Mastra provides the `MCPClient` class to manage connections to one or more MCP servers and access their tools.
+
+### Installation
+
+If you haven't already, install the Mastra MCP package:
+
+```bash npm2yarn copy
+npm install @mastra/mcp@latest
+```
+
+### Configuring `MCPClient`
+
+You configure `MCPClient` with a map of servers you want to connect to. It supports connections via subprocess (Stdio) or HTTP (Streamable HTTP with SSE fallback).
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    // Stdio example
+    sequential: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    },
+    // HTTP example
+    weather: {
+      url: new URL("http://localhost:8080/mcp"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+For detailed configuration options, see the [`MCPClient` reference documentation](/reference/tools/mcp-client).
+
+### Static vs Dynamic Tool Configurations
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature          | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
+| :--------------- | :-------------------------------------------- | :---------------------------------------------------- |
+| **Use Case**     | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app)         |
+| **Configuration**| Fixed at agent initialization                 | Per-request, dynamic                                |
+| **Credentials**  | Shared across all uses                        | Can vary per user/request                             |
+| **Agent Setup**  | Tools added in `Agent` constructor            | Tools passed in `generate()` or `stream()` options  |
+
+*   **Static Configuration (`getTools()`):** Fetches all tools from all configured servers. Best when the tool configuration (like API keys) is static and shared across all users or requests. You typically call this once and pass the result to the `tools` property when defining your `Agent`.
+    [Reference: `getTools()`](/reference/tools/mcp-client#gettools)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... mcp client setup
+
+    const agent = new Agent({
+      // ... other agent config
+      tools: await mcp.getTools(),
+    });
+    ```
+
+*   **Dynamic Configuration (`getToolsets()`):** Designed for scenarios where configuration might change per request or per user (e.g., different API keys for different tenants in a multi-user application). You pass the result of `getToolsets()` to the `toolsets` option in the agent's `generate()` or `stream()` method.
+    [Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... agent setup without tools initially
+
+    async function handleRequest(userPrompt: string, userApiKey: string) {
+      const userMcp = new MCPClient({ /* config with userApiKey */ });
+      const toolsets = await userMcp.getToolsets();
+
+      const response = await agent.stream(userPrompt, {
+        toolsets, // Pass dynamic toolsets
+      });
+      // ... handle response
+      await userMcp.disconnect();
+    }
+    ```
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here’s how to connect to some popular ones using `MCPClient`:
+
+<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai"]}>
+  <Tabs.Tab>
+    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        marketing: { // Example profile name
+          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+        },
+      },
+    });
+    ```
+
+    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+    > ```bash filename=".env"
+    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+    > ```
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        googleSheets: {
+          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+        },
+        gmail: {
+          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+        },
+      },\n    });
+    ```
+
+    Authentication with services like Google Sheets often happens interactively through the agent conversation.
+
+    *Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications.*
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+    ```typescript
+    // Unix/Mac
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "npx",
+          args: [
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },\n    });
path: docs/src/content/en/docs/tools-mcp/mcp-overview.mdx
user: login: greptile-apps[bot]
body: syntax: Extra escape character '\n' in the code block

```suggestion
      },
    });
```
created_at: 2025-05-02T17:55:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,221 @@
+---
+title: "MCP Overview | Tools & MCP | Mastra Docs"
+description: Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+---
+
+import { Tabs } from "nextra/components";
+
+# MCP Overview
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard designed to let AI models discover and interact with external tools and resources. Think of it as a universal plugin system for AI agents, allowing them to use tools regardless of the language they were written in or where they are hosted.
+
+Mastra uses MCP to connect agents to external tool servers.
+
+## Use third-party tools with an MCP Client
+
+Mastra provides the `MCPClient` class to manage connections to one or more MCP servers and access their tools.
+
+### Installation
+
+If you haven't already, install the Mastra MCP package:
+
+```bash npm2yarn copy
+npm install @mastra/mcp@latest
+```
+
+### Configuring `MCPClient`
+
+You configure `MCPClient` with a map of servers you want to connect to. It supports connections via subprocess (Stdio) or HTTP (Streamable HTTP with SSE fallback).
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcp = new MCPClient({
+  servers: {
+    // Stdio example
+    sequential: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    },
+    // HTTP example
+    weather: {
+      url: new URL("http://localhost:8080/mcp"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+For detailed configuration options, see the [`MCPClient` reference documentation](/reference/tools/mcp-client).
+
+### Static vs Dynamic Tool Configurations
+
+`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+
+| Feature          | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
+| :--------------- | :-------------------------------------------- | :---------------------------------------------------- |
+| **Use Case**     | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app)         |
+| **Configuration**| Fixed at agent initialization                 | Per-request, dynamic                                |
+| **Credentials**  | Shared across all uses                        | Can vary per user/request                             |
+| **Agent Setup**  | Tools added in `Agent` constructor            | Tools passed in `generate()` or `stream()` options  |
+
+*   **Static Configuration (`getTools()`):** Fetches all tools from all configured servers. Best when the tool configuration (like API keys) is static and shared across all users or requests. You typically call this once and pass the result to the `tools` property when defining your `Agent`.
+    [Reference: `getTools()`](/reference/tools/mcp-client#gettools)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... mcp client setup
+
+    const agent = new Agent({
+      // ... other agent config
+      tools: await mcp.getTools(),
+    });
+    ```
+
+*   **Dynamic Configuration (`getToolsets()`):** Designed for scenarios where configuration might change per request or per user (e.g., different API keys for different tenants in a multi-user application). You pass the result of `getToolsets()` to the `toolsets` option in the agent's `generate()` or `stream()` method.
+    [Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
+
+    ```typescript
+    import { Agent } from "@mastra/core/agent";
+    // ... agent setup without tools initially
+
+    async function handleRequest(userPrompt: string, userApiKey: string) {
+      const userMcp = new MCPClient({ /* config with userApiKey */ });
+      const toolsets = await userMcp.getToolsets();
+
+      const response = await agent.stream(userPrompt, {
+        toolsets, // Pass dynamic toolsets
+      });
+      // ... handle response
+      await userMcp.disconnect();
+    }
+    ```
+
+## Connecting to an MCP registry
+
+MCP servers can be discovered through registries. Here’s how to connect to some popular ones using `MCPClient`:
+
+<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai"]}>
+  <Tabs.Tab>
+    [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        marketing: { // Example profile name
+          url: new URL(process.env.MCP_RUN_SSE_URL!), // Get URL from mcp.run profile
+        },
+      },
+    });
+    ```
+
+    > **Important:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
+    > ```bash filename=".env"
+    > MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
+    > ```
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Composio.dev](https://composio.dev) offers a registry of [SSE-based MCP servers](https://mcp.composio.dev). You can use the SSE URL generated for tools like Cursor directly.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        googleSheets: {
+          url: new URL("https://mcp.composio.dev/googlesheets/[private-url-path]"),
+        },
+        gmail: {
+          url: new URL("https://mcp.composio.dev/gmail/[private-url-path]"),
+        },
+      },\n    });
+    ```
+
+    Authentication with services like Google Sheets often happens interactively through the agent conversation.
+
+    *Note: Composio URLs are typically tied to a single user account, making them best suited for personal automation rather than multi-tenant applications.*
+
+  </Tabs.Tab>
+  <Tabs.Tab>
+    [Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+
+    ```typescript
+    // Unix/Mac
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        sequentialThinking: {
+          command: "npx",
+          args: [
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },\n    });
+    ```
+
+    ```typescript
+    // Windows
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        command: "cmd",
+        args: [
+            "/c",
+            "npx",
+            "-y",
+            "@smithery/cli@latest",
+            "run",
+            "@smithery-ai/server-sequential-thinking",
+            "--config",
+            "{}",
+          ],
+        },
+      },
+    });
path: docs/src/content/en/docs/tools-mcp/mcp-overview.mdx
user: login: greptile-apps[bot]
body: logic: Windows example has incorrect server configuration structure - 'command' and 'args' are nested one level too deep

```suggestion
    const mcp = new MCPClient({
      servers: {
        sequentialThinking: {
          command: "cmd",
          args: [
            "/c",
            "npx",
            "-y",
            "@smithery/cli@latest",
            "run",
            "@smithery-ai/server-sequential-thinking",
            "--config",
            "{}",
          ],
        },
      },
    });
```
created_at: 2025-05-02T17:55:48Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,126 @@
+---
+title: "Dynamic Tool Context | Tools & MCP | Mastra Docs"
+description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to tools.
+---
+
+import { Callout } from "nextra/components";
+
+# Dynamic Tool Context
+
+Mastra provides `RuntimeContext`, a system based on dependency injection, that allows you to pass dynamic, request-specific configuration to your tools during execution. This is useful when a tool's behavior needs to change based on user identity, request headers, or other runtime factors, without altering the tool's core code.
+
+<Callout>
+  **Note:** `RuntimeContext` is primarily used for passing data *into* tool executions. It's distinct from agent memory, which handles conversation history and state persistence across multiple calls.
+</Callout>
+
+## Basic Usage
+
+To use `RuntimeContext`, first define a type structure for your dynamic configuration. Then, create an instance of `RuntimeContext` typed with your definition and set the desired values. Finally, include the `runtimeContext` instance in the options object when calling `agent.generate()` or `agent.stream()`.
+
+```typescript
+import { RuntimeContext } from "@mastra/core/di";
+// Assume 'agent' is an already defined Mastra Agent instance
+
+// Define the context type
+type WeatherRuntimeContext = {
+  "temperature-scale": "celsius" | "fahrenheit";
+};
+
+// Instantiate RuntimeContext and set values
+const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();
+runtimeContext.set("temperature-scale", "celsius");
+
+// Pass to agent call
+const response = await agent.generate("What's the weather like today?", {
+  runtimeContext, // Pass the context here
+});
+
+console.log(response.text);
+```
+
+## Accessing Context in Tools
+
+Tools receive the `runtimeContext` as part of the second argument to their `execute` function. You can then use the `.get()` method to retrieve values.
+
+```typescript filename="src/mastra/tools/weather-tool.ts"
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+// Assume WeatherRuntimeContext is defined as above and accessible here
+
+// Dummy fetch function
+async function fetchWeather(
+  location: string,
+  options: { temperatureUnit: "celsius" | "fahrenheit" }
+): Promise<any> {
+  console.log(`Fetching weather for ${location} in ${options.temperatureUnit}`);
+  // Replace with actual API call
+  return { temperature: options.temperatureUnit === "celsius" ? 20 : 68 };
+}
+
+export const weatherTool = createTool({
+  id: "getWeather",
+  description: "Get the current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("The location to get weather for"),
+  }),
+  // The tool's execute function receives runtimeContext
+  execute: async ({ context, runtimeContext }) => {
path: docs/src/content/en/docs/tools-mcp/dynamic-context.mdx
user: login: greptile-apps[bot]
body: style: The execute function's type signature is missing the second parameter that contains runtimeContext. Should show the full type signature for clarity.
created_at: 2025-05-02T17:55:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,55 @@
+---
+title: "Tools Overview | Tools & MCP | Mastra Docs"
+description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
+---
+
+# Tools Overview
+
+Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
+
+Each tool typically defines:
+
+- **Inputs:** What information the tool needs to run (defined with an `inputSchema`, often using Zod).
+- **Outputs:** The structure of the data the tool returns (defined with an `outputSchema`).
+- **Execution Logic:** The code that performs the tool's action.
+- **Description:** Text that helps the agent understand what the tool does and when to use it.
+
+## Creating Tools
+
+In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const getWeatherInfo = async (city: string) => {
+  // Replace with an actual API call to a weather service
+  console.log(`Fetching weather for ${city}...`);
+  // Example data structure
+  return { temperature: 20, conditions: "Sunny" };
+};
+
+export const weatherTool = createTool({
+  id: "Get Weather Information",
+  description: `Fetches the current weather information for a given city`,
path: docs/src/content/en/docs/tools-mcp/overview.mdx
user: login: greptile-apps[bot]
body: style: Tool ID contains spaces which could cause issues with some MCP servers. Consider using kebab-case like 'get-weather-information' instead.
created_at: 2025-05-02T17:55:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,55 @@
+---
+title: "Tools Overview | Tools & MCP | Mastra Docs"
+description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
+---
+
+# Tools Overview
+
+Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
+
+Each tool typically defines:
+
+- **Inputs:** What information the tool needs to run (defined with an `inputSchema`, often using Zod).
+- **Outputs:** The structure of the data the tool returns (defined with an `outputSchema`).
+- **Execution Logic:** The code that performs the tool's action.
+- **Description:** Text that helps the agent understand what the tool does and when to use it.
+
+## Creating Tools
+
+In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const getWeatherInfo = async (city: string) => {
+  // Replace with an actual API call to a weather service
+  console.log(`Fetching weather for ${city}...`);
+  // Example data structure
+  return { temperature: 20, conditions: "Sunny" };
+};
+
+export const weatherTool = createTool({
+  id: "Get Weather Information",
+  description: `Fetches the current weather information for a given city`,
+  inputSchema: z.object({
+    city: z.string().describe("City name"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async ({ context: { city } }) => {
+    console.log("Using tool to fetch weather information for", city);
+    return await getWeatherInfo(city);
+  },
path: docs/src/content/en/docs/tools-mcp/overview.mdx
user: login: greptile-apps[bot]
body: style: Tool's execute function returns data from getWeatherInfo directly without validating against outputSchema. Consider adding runtime validation.

```suggestion
  execute: async ({ context: { city } }) => {
    console.log("Using tool to fetch weather information for", city);
    const result = await getWeatherInfo(city);
    return outputSchema.parse(result);
  },
```
created_at: 2025-05-02T17:55:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,55 @@
+---
+title: "Tools Overview | Tools & MCP | Mastra Docs"
+description: Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
+---
+
+# Tools Overview
+
+Tools are functions that agents can execute to perform specific tasks or access external information. They extend an agent's capabilities beyond simple text generation, allowing interaction with APIs, databases, or other systems.
+
+Each tool typically defines:
+
+- **Inputs:** What information the tool needs to run (defined with an `inputSchema`, often using Zod).
+- **Outputs:** The structure of the data the tool returns (defined with an `outputSchema`).
+- **Execution Logic:** The code that performs the tool's action.
+- **Description:** Text that helps the agent understand what the tool does and when to use it.
+
+## Creating Tools
+
+In Mastra, you create tools using the [`createTool`](/reference/tools/create-tool) function from the `@mastra/core/tools` package.
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const getWeatherInfo = async (city: string) => {
+  // Replace with an actual API call to a weather service
+  console.log(`Fetching weather for ${city}...`);
+  // Example data structure
+  return { temperature: 20, conditions: "Sunny" };
+};
+
+export const weatherTool = createTool({
+  id: "Get Weather Information",
+  description: `Fetches the current weather information for a given city`,
+  inputSchema: z.object({
+    city: z.string().describe("City name"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async ({ context: { city } }) => {
+    console.log("Using tool to fetch weather information for", city);
+    return await getWeatherInfo(city);
+  },
+});
+```
+
+This example defines a `weatherTool` with an input schema for the city, an output schema for the weather data, and an `execute` function that contains the tool's logic.
+
+When creating tools, keep tool descriptions simple and focused on **what** the tool does and **when** to use it, emphasizing its primary use case. Technical details belong in the parameter schemas, guiding the agent on _how_ to use the tool correctly with descriptive names, clear descriptions, and explanations of default values.
+
+## Adding tools to agent
path: docs/src/content/en/docs/tools-mcp/overview.mdx
user: login: greptile-apps[bot]
body: style: Section heading 'Adding tools to agent' should be title case to match other headings: 'Adding Tools to Agent'
created_at: 2025-05-02T17:55:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,104 @@
+---
+title: "Reference: createTool() | Tools | Mastra Docs"
+description: Documentation for the createTool function in Mastra, used to define custom tools for agents.
+---
+
+# createTool()
+
+The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
+
+## Basic Usage
+
+Here is a basic example of creating a tool that fetches weather information:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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.e.g., API call)
path: docs/src/content/en/reference/tools/create-tool.mdx
user: login: greptile-apps[bot]
body: syntax: 'e.e.g.' contains a typo, should be 'e.g.'

```suggestion
    // Tool logic here (e.g., API call)
```
created_at: 2025-05-02T17:56:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,104 @@
+---
+title: "Reference: createTool() | Tools | Mastra Docs"
+description: Documentation for the createTool function in Mastra, used to define custom tools for agents.
+---
+
+# createTool()
+
+The `createTool()` function is used to define custom tools that your Mastra agents can execute. Tools extend an agent's capabilities by allowing it to interact with external systems, perform calculations, or access specific data.
+
+## Basic Usage
+
+Here is a basic example of creating a tool that fetches weather information:
+
+```typescript filename="src/mastra/tools/weatherInfo.ts" copy
+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`,
path: docs/src/content/en/reference/tools/create-tool.mdx
user: login: greptile-apps[bot]
body: style: Consider adding descriptions to the schema fields using .describe() to help the agent better understand parameter usage
created_at: 2025-05-02T17:56:19Z
author_association: CONTRIBUTOR

PR comments:
user: login: codesandbox[bot]
created_at: 2025-05-02T00:05:36Z
body: #### Review or Edit in CodeSandbox

Open the branch in <a href="https://codesandbox.io/p/github/mastra-ai/mastra/docs/tools-mcp?mode=review&utm_source=gh_app">Web Editor</a> &bull; <a href="https://codesandbox.io/p/vscode?owner=mastra-ai&repo=mastra&branch=docs/tools-mcp&utm_source=gh_app">VS Code</a> &bull; <a href="https://codesandbox.io/p/vscode?owner=mastra-ai&repo=mastra&branch=docs/tools-mcp&insiders=true&utm_source=gh_app">Insiders</a><br>
Open <a href="https://codesandbox.io/p/devtool/preview/mastra-ai/mastra/docs/tools-mcp?task=preview&port=51423&redirect=true&utm_source=gh_app">Preview</a>

<!-- open-in-codesandbox:complete -->

author_association: NONE
user: login: changeset-bot[bot]
created_at: 2025-05-02T00:05:38Z
body: ###  ⚠️  No Changeset found

Latest commit: b67ec5371576f49cb5c9f1171cc9735288dcf074

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a changeset.**

<details><summary>This PR includes no changesets</summary>

  When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

</details>

[Click here to learn what changesets are, and how to add one](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).

[Click here if you're a maintainer who wants to add a changeset to this PR](https://github.com/mastra-ai/mastra/new/docs/tools-mcp?filename=.changeset/quiet-students-divide.md&value=---%0A%0A---%0A%0Adocs%3A%20Tools%20and%20MCP%0A)


author_association: NONE
user: login: vercel[bot]
created_at: 2025-05-02T00:05:38Z
body: [vc]: #mnF75s7RC3jFPNePStTryszswbYp5ExSE41dswjaU5o=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJtYXN0cmEtZG9jcyIsInJvb3REaXJlY3RvcnkiOiJkb2NzIiwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2tlcGxlci1hYjFiZjVhYi9tYXN0cmEtZG9jcy82TE1xWUxmVDZ4S05EQUwyZ05GSEx0RFFlZzZ2IiwicHJldmlld1VybCI6Im1hc3RyYS1kb2NzLWdpdC1kb2NzLXRvb2xzLW1jcC1rZXBsZXItYWIxYmY1YWIudmVyY2VsLmFwcCIsIm5leHRDb21taXRTdGF0dXMiOiJERVBMT1lFRCIsImxpdmVGZWVkYmFjayI6eyJyZXNvbHZlZCI6MCwidW5yZXNvbHZlZCI6MCwidG90YWwiOjAsImxpbmsiOiJtYXN0cmEtZG9jcy1naXQtZG9jcy10b29scy1tY3Ata2VwbGVyLWFiMWJmNWFiLnZlcmNlbC5hcHAifX0seyJuYW1lIjoib3BlbmFwaS1zcGVjLXdyaXRlciIsInJvb3REaXJlY3RvcnkiOiJleGFtcGxlcy9vcGVuYXBpLXNwZWMtd3JpdGVyIiwibGl2ZUZlZWRiYWNrIjp7InJlc29sdmVkIjowLCJ1bnJlc29sdmVkIjowLCJ0b3RhbCI6MCwibGluayI6Im9wZW5hcGktc3BlYy13cml0ZXItZ2l0LWRvY3MtdG9vbHMtbWNwLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIn0sImluc3BlY3RvclVybCI6Imh0dHBzOi8vdmVyY2VsLmNvbS9rZXBsZXItYWIxYmY1YWIvb3BlbmFwaS1zcGVjLXdyaXRlci81NTJSSzh0RjV2TnFEMWtGaHl1M3VNcFBFWExIIiwicHJldmlld1VybCI6Im9wZW5hcGktc3BlYy13cml0ZXItZ2l0LWRvY3MtdG9vbHMtbWNwLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIn0seyJuYW1lIjoidHJhdmVsLWFpIiwicm9vdERpcmVjdG9yeSI6ImV4YW1wbGVzL3RyYXZlbC1hcHAiLCJsaXZlRmVlZGJhY2siOnsicmVzb2x2ZWQiOjAsInVucmVzb2x2ZWQiOjAsInRvdGFsIjowLCJsaW5rIjoidHJhdmVsLWFpLWdpdC1kb2NzLXRvb2xzLW1jcC1rZXBsZXItYWIxYmY1YWIudmVyY2VsLmFwcCJ9LCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20va2VwbGVyLWFiMWJmNWFiL3RyYXZlbC1haS80c3luNWRrZHhOSjRGSEJIbk1MeXpWS1RwVVpmIiwicHJldmlld1VybCI6InRyYXZlbC1haS1naXQtZG9jcy10b29scy1tY3Ata2VwbGVyLWFiMWJmNWFiLnZlcmNlbC5hcHAiLCJuZXh0Q29tbWl0U3RhdHVzIjoiREVQTE9ZRUQifSx7Im5hbWUiOiJhc3Npc3RhbnQtdWkiLCJyb290RGlyZWN0b3J5IjoiZXhhbXBsZXMvYXNzaXN0YW50LXVpIiwibGl2ZUZlZWRiYWNrIjp7InJlc29sdmVkIjowLCJ1bnJlc29sdmVkIjowLCJ0b3RhbCI6MCwibGluayI6ImFzc2lzdGFudC11aS1naXQtZG9jcy10b29scy1tY3Ata2VwbGVyLWFiMWJmNWFiLnZlcmNlbC5hcHAifSwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2tlcGxlci1hYjFiZjVhYi9hc3Npc3RhbnQtdWkvOVdQU2g3OGpqWVJTaUJra0dBRHNVOHUxWW9CVCIsInByZXZpZXdVcmwiOiJhc3Npc3RhbnQtdWktZ2l0LWRvY3MtdG9vbHMtbWNwLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIn1dfQ==
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)

| Name | Status | Preview | Comments | Updated (UTC) |
| :--- | :----- | :------ | :------- | :------ |
| **assistant-ui** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/assistant-ui/9WPSh78jjYRSiBkkGADsU8u1YoBT)) | [Visit Preview](https://assistant-ui-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/assistant-ui-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 2, 2025 8:16pm |
| **mastra-docs** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/mastra-docs/6LMqYLfT6xKNDAL2gNFHLtDQeg6v)) | [Visit Preview](https://mastra-docs-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/mastra-docs-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 2, 2025 8:16pm |
| **openapi-spec-writer** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/openapi-spec-writer/552RK8tF5vNqD1kFhyu3uMpPEXLH)) | [Visit Preview](https://openapi-spec-writer-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/openapi-spec-writer-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 2, 2025 8:16pm |
| **travel-ai** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/travel-ai/4syn5dkdxNJ4FHBHnMLyzVKTpUZf)) | [Visit Preview](https://travel-ai-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/travel-ai-git-docs-tools-mcp-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 2, 2025 8:16pm |





author_association: NONE