@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/agents/mcp-guide.mdx

@@ -0,0 +1,215 @@
+---
+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 and supports both stdio and SSE-based connections.
+
+## Installation
+
+Using pnpm:
+
+```bash
+pnpm add @mastra/mcp@latest
+```
+
+Using npm:
+
+```bash
+npm install @mastra/mcp@latest
+```
+
+## Using MCP in Your Code
+
+The `MCPConfiguration` class provides a way to manage multiple tool servers in your Mastra applications without managing multiple MCP clients. You can configure both stdio-based and SSE-based servers:
+
+```typescript
+import { MCPConfiguration } from "@mastra/mcp";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const mcp = new MCPConfiguration({
+  servers: {
+    // stdio example
+    sequential: {
+      name: "sequential-thinking",
+      server: {
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      },
+    },
+    // SSE example
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+    },
+  },
+});
+```
+
+### Tools vs Toolsets
+
+The `MCPConfiguration` 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 MCPConfiguration({
+  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](/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 `MCPConfiguration` like this:
+
+```typescript
+const mcp = new MCPConfiguration({
+  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 MCPConfiguration({
+  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 MCPConfiguration({
+  servers: {
+    sequentialThinking: {
+      command: "npx",
+      args: [
+        "-y",
+        "@smithery/cli@latest",
+        "run",
+        "@smithery-ai/server-sequential-thinking",
+        "--config",
+        "{}",
+      ],
+    },
+  },
+});
+
+// Windows
+const mcp = new MCPConfiguration({
+  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.
+
+## 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 [MCPConfiguration](/reference/tools/mcp-configuration)
+- Check out our [example projects](/examples) that use MCP

package/.docs/raw/agents/overview.mdx

@@ -0,0 +1,303 @@
+---
+title: "Creating and Calling Agents | Agent Documentation | Mastra"
+description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
+---
+
+# Creating and Calling Agents
+
+Agents in Mastra are systems where the language model can autonomously decide on a sequence of actions to perform tasks. They have access to tools, workflows, and synced data, enabling them to perform complex tasks and interact with external systems. Agents can invoke your custom functions, utilize third-party APIs through integrations, and access knowledge bases you have built.
+
+Agents are like employees who can be used for ongoing projects. They have names, persistent memory, consistent model configurations, and instructions across calls, as well as a set of enabled tools.
+
+## 1. Creating an Agent
+
+To create an agent in Mastra, you use the `Agent` class and define its properties:
+
+```ts showLineNumbers filename="src/mastra/agents/index.ts" copy
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+export const myAgent = new Agent({
+  name: "My Agent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o-mini"),
+});
+```
+
+**Note:** Ensure that you have set the necessary environment variables, such as your OpenAI API key, in your `.env` file:
+
+```.env filename=".env" copy
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Also, make sure you have the `@mastra/core` package installed:
+
+```bash npm2yarn copy
+npm install @mastra/core
+```
+
+### Registering the Agent
+
+Register your agent with Mastra to enable logging and access to configured tools and integrations:
+
+```ts showLineNumbers filename="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { myAgent } from "./agents";
+
+export const mastra = new Mastra({
+  agents: { myAgent },
+});
+```
+
+## 2. Generating and streaming text
+
+### Generating text
+
+Use the `.generate()` method to have your agent produce text responses:
+
+```ts showLineNumbers filename="src/mastra/index.ts" copy
+const response = await myAgent.generate([
+  { role: "user", content: "Hello, how can you assist me today?" },
+]);
+
+console.log("Agent:", response.text);
+```
+
+For more details about the generate method and its options, see the [generate reference documentation](/reference/agents/generate).
+
+### Streaming responses
+
+For more real-time responses, you can stream the agent's response:
+
+```ts showLineNumbers filename="src/mastra/index.ts" copy
+const stream = await myAgent.stream([
+  { role: "user", content: "Tell me a story." },
+]);
+
+console.log("Agent:");
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+For more details about streaming responses, see the [stream reference documentation](/reference/agents/stream).
+
+## 3. Structured Output
+
+Agents can return structured data by providing a JSON Schema or using a Zod schema.
+
+### Using JSON Schema
+
+```typescript
+const schema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    keywords: { type: "array", items: { type: "string" } },
+  },
+  additionalProperties: false,
+  required: ["summary", "keywords"],
+};
+
+const response = await myAgent.generate(
+  [
+    {
+      role: "user",
+      content:
+        "Please provide a summary and keywords for the following text: ...",
+    },
+  ],
+  {
+    output: schema,
+  },
+);
+
+console.log("Structured Output:", response.object);
+```
+
+### Using Zod
+
+You can also use Zod schemas for type-safe structured outputs.
+
+First, install Zod:
+
+```bash npm2yarn copy
+npm install zod
+```
+
+Then, define a Zod schema and use it with the agent:
+
+```ts showLineNumbers filename="src/mastra/index.ts" copy
+import { z } from "zod";
+
+// Define the Zod schema
+const schema = z.object({
+  summary: z.string(),
+  keywords: z.array(z.string()),
+});
+
+// Use the schema with the agent
+const response = await myAgent.generate(
+  [
+    {
+      role: "user",
+      content:
+        "Please provide a summary and keywords for the following text: ...",
+    },
+  ],
+  {
+    output: schema,
+  },
+);
+
+console.log("Structured Output:", response.object);
+```
+
+### Using Tools
+
+If you need to generate structured output alongside tool calls, you'll need to use the `experimental_output` property instead of `output`. Here's how:
+
+```typescript
+const schema = z.object({
+  summary: z.string(),
+  keywords: z.array(z.string()),
+});
+
+const response = await myAgent.generate(
+  [
+    {
+      role: "user",
+      content:
+        "Please analyze this repository and provide a summary and keywords...",
+    },
+  ],
+  {
+    // Use experimental_output to enable both structured output and tool calls
+    experimental_output: schema,
+  },
+);
+
+console.log("Structured Output:", response.object);
+```
+
+<br />
+
+This allows you to have strong typing and validation for the structured data returned by the agent.
+
+## 4. Multi-step Tool use Agents
+
+Agents can be enhanced with tools - functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. For details on creating and configuring tools, see the [Adding Tools documentation](/docs/agents/adding-tools).
+
+### Using maxSteps
+
+The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make, particularly important when using tool calls. By default, it is set to 1 to prevent infinite loops in case of misconfigured tools. You can increase this limit based on your use case:
+
+```ts showLineNumbers filename="src/mastra/agents/index.ts" copy
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import * as mathjs from "mathjs";
+import { z } from "zod";
+
+export const myAgent = new Agent({
+  name: "My Agent",
+  instructions: "You are a helpful assistant that can solve math problems.",
+  model: openai("gpt-4o-mini"),
+  tools: {
+    calculate: {
+      description: "Calculator for mathematical expressions",
+      schema: z.object({ expression: z.string() }),
+      execute: async ({ expression }) => mathjs.evaluate(expression),
+    },
+  },
+});
+
+const response = await myAgent.generate(
+  [
+    {
+      role: "user",
+      content:
+        "If a taxi driver earns $9461 per hour and works 12 hours a day, how much does they earn in one day?",
+    },
+  ],
+  {
+    maxSteps: 5, // Allow up to 5 tool usage steps
+  },
+);
+```
+
+### Using onStepFinish
+
+You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
+`onStepFinish` is only available when streaming or generating text without structured output.
+
+```ts showLineNumbers filename="src/mastra/agents/index.ts" copy
+const response = await myAgent.generate(
+  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
+  {
+    maxSteps: 5,
+    onStepFinish: ({ text, toolCalls, toolResults }) => {
+      console.log("Step completed:", { text, toolCalls, toolResults });
+    },
+  },
+);
+```
+
+### Using onFinish
+
+The `onFinish` callback is available when streaming responses and provides detailed information about the completed interaction. It is called after the LLM has finished generating its response and all tool executions have completed.
+This callback receives the final response text, execution steps, token usage statistics, and other metadata that can be useful for monitoring and logging:
+
+```ts showLineNumbers filename="src/mastra/agents/index.ts" copy
+const stream = await myAgent.stream(
+  [{ role: "user", content: "Calculate the taxi driver's daily earnings." }],
+  {
+    maxSteps: 5,
+    onFinish: ({
+      steps,
+      text,
+      finishReason, // 'complete', 'length', 'tool', etc.
+      usage, // token usage statistics
+      reasoningDetails, // additional context about the agent's decisions
+    }) => {
+      console.log("Stream complete:", {
+        totalSteps: steps.length,
+        finishReason,
+        usage,
+      });
+    },
+  },
+);
+```
+
+## 5. Running Agents
+
+Mastra provides a CLI command `mastra dev` to run your agents behind an API. By default, this looks for exported agents in files in the `src/mastra/agents` directory.
+
+### Starting the Server
+
+```bash
+mastra dev
+```
+
+This will start the server and make your agent available at `http://localhost:4111/api/agents/myAgent/generate`.
+
+### Interacting with the Agent
+
+You can interact with the agent using `curl` from the command line:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/myAgent/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      { "role": "user", "content": "Hello, how can you assist me today?" }
+    ]
+  }'
+```
+
+## 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.
+- See an example agent in the [Chef Michel](../guides/chef-michel.mdx) example.

package/.docs/raw/community/discord.mdx

@@ -0,0 +1,12 @@
+---
+title: "Discord Community and Bot | Documentation | Mastra"
+description: Information about the Mastra Discord community and MCP bot.
+---
+
+# Discord Community
+
+The Discord server has over 1000 members and serves as the main discussion forum for Mastra. The Mastra team monitors Discord during North American and European business hours, with community members active across other time zones.[Join the Discord server](https://discord.gg/BTYqqHKUrf).
+
+## Discord MCP Bot
+
+In addition to community members, we have an (experimental!) Discord bot that can also help answer questions. It uses [Model Context Protocol (MCP)](/docs/agents/mcp-guide). You can ask it a question with `/ask` (either in public channels or DMs) and clear history (in DMs only) with `/cleardm`.

package/.docs/raw/community/licensing.mdx

@@ -0,0 +1,63 @@
+---
+title: "Licensing"
+description: "Mastra License"
+---
+
+# License
+
+## Elastic License 2.0 (ELv2)
+
+Mastra is licensed under the Elastic License 2.0 (ELv2), a modern license designed to balance open-source principles with sustainable business practices.
+
+### What is Elastic License 2.0?
+
+The Elastic License 2.0 is a source-available license that grants users broad rights to use, modify, and distribute the software while including specific limitations to protect the project's sustainability. It allows:
+
+- Free use for most purposes
+- Viewing, modifying, and redistributing the source code
+- Creating and distributing derivative works
+- Commercial use within your organization
+
+The primary limitation is that you cannot provide Mastra as a hosted or managed service that offers users access to the substantial functionality of the software.
+
+### Why We Chose Elastic License 2.0
+
+We selected the Elastic License 2.0 for several important reasons:
+
+1. **Sustainability**: It enables us to maintain a healthy balance between openness and the ability to sustain long-term development.
+
+2. **Innovation Protection**: It ensures we can continue investing in innovation without concerns about our work being repackaged as competing services.
+
+3. **Community Focus**: It maintains the spirit of open source by allowing users to view, modify, and learn from our code while protecting our ability to support the community.
+
+4. **Business Clarity**: It provides clear guidelines for how Mastra can be used in commercial contexts.
+
+### Building Your Business with Mastra
+
+Despite the licensing restrictions, there are numerous ways to build successful businesses using Mastra:
+
+#### Allowed Business Models
+
+- **Building Applications**: Create and sell applications built with Mastra
+- **Offering Consulting Services**: Provide expertise, implementation, and customization services
+- **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
+- **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
+- **Training and Education**: Offer courses and educational materials about using Mastra effectively
+
+#### Examples of Compliant Usage
+
+- A company builds an AI-powered customer service application using Mastra and sells it to clients
+- A consulting firm offers implementation and customization services for Mastra
+- A developer creates specialized agents and tools with Mastra and licenses them to other businesses
+- A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
+
+#### What to Avoid
+
+The main restriction is that you cannot offer Mastra itself as a hosted service where users access its core functionality. This means:
+
+- Don't create a SaaS platform that is essentially Mastra with minimal modifications
+- Don't offer a managed Mastra service where customers are primarily paying to use Mastra's features
+
+### Questions About Licensing?
+
+If you have specific questions about how the Elastic License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting legitimate business use cases while protecting the sustainability of the project.