@mastra/mcp 1.15.1 → 1.16.0-alpha.0

package/dist/docs/references/docs-mcp-overview.md

@@ -2,18 +2,13 @@
 
 # MCP overview
 
-Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It's a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
+Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources.
 
-Mastra can also be used to author MCP servers, exposing agents, tools, and other structured resources via the MCP interface. These can then be accessed by any system or agent that supports the protocol.
+Use [`MCPClient`](https://mastra.ai/reference/tools/mcp-client) to connect to MCP servers. Use [`MCPServer`](https://mastra.ai/reference/tools/mcp-server) to expose Mastra agents, tools, workflows, prompts, and resources to other MCP-compatible systems.
 
-Mastra currently supports two MCP classes:
+## Connect to MCP servers
 
-1. `MCPClient`: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
-2. `MCPServer`: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP-compatible clients.
-
-## Get started
-
-To use MCP, install the required dependency:
+Install the MCP package:
 
 **npm**:
 
@@ -39,382 +34,338 @@ yarn add @mastra/mcp@latest
 bun add @mastra/mcp@latest
 ```
 
-## Configuring `MCPClient`
-
-The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
+Configure each server with a local command or remote URL:
 
 ```typescript
 import { MCPClient } from '@mastra/mcp'
 
-export const testMcpClient = new MCPClient({
-  id: 'test-mcp-client',
+export const mcpClient = new MCPClient({
+  id: 'my-mcp-client',
   servers: {
     wikipedia: {
       command: 'npx',
       args: ['-y', 'wikipedia-mcp'],
     },
     weather: {
-      url: new URL(
-        `https://server.smithery.ai/@smithery-ai/national-weather-service/mcp?api_key=${process.env.SMITHERY_API_KEY}`,
-      ),
+      url: new URL('https://weather.example.com/mcp'),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer ${process.env.WEATHER_API_KEY}`,
+        },
+      },
     },
   },
 })
 ```
 
-Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
-
-> **Authentication:** For connecting to OAuth-protected MCP servers, including completing the browser-based authorization flow with `authenticate()`, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
-
-## Using `MCPClient` with an agent
+> **Authentication:** For OAuth-protected servers, use `authenticate()` to complete the browser-based authorization flow. Visit [OAuth authentication](https://mastra.ai/reference/tools/mcp-client) for configuration details.
 
-To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
+Pass tools from the configured servers to an agent:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { testMcpClient } from '../mcp/test-mcp-client'
+import { mcpClient } from '../mcp/client'
 
-export const testAgent = new Agent({
-  id: 'test-agent',
-  name: 'Test Agent',
-  description: 'You are a helpful AI assistant',
+export const assistant = new Agent({
+  id: 'assistant',
+  name: 'Assistant',
   instructions: `
-      You are a helpful assistant that has access to the following MCP Servers.
-      - Wikipedia MCP Server
-      - US National Weather Service
-
-      Answer questions using the information you find using the MCP Servers.`,
+    Use the available MCP tools to answer questions.
+    Include the source of any information you retrieve.
+  `,
   model: 'openai/gpt-5.6-sol',
-  tools: await testMcpClient.listTools(),
+  tools: await mcpClient.listTools(),
 })
 ```
 
-Visit [Agent Class](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+### Static and runtime tools
+
+Choose how to load tools based on whether the server configuration changes between requests:
+
+|             | Static tools                       | Runtime toolsets                         |
+| ----------- | ---------------------------------- | ---------------------------------------- |
+| Method      | `await mcpClient.listTools()`      | `await mcpClient.listToolsets()`         |
+| Use case    | Shared, fixed configuration        | Per-user or per-request configuration    |
+| Credentials | Shared by all requests             | Can vary between requests                |
+| Agent API   | `tools` in the `Agent` constructor | `toolsets` in `generate()` or `stream()` |
+
+The preceding agent example uses static tools. For runtime credentials, create a client for the request and pass its toolsets when calling the agent:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+import { mastra } from './mastra'
+
+export async function handleRequest(prompt: string, apiKey: string) {
+  const userMcpClient = new MCPClient({
+    servers: {
+      weather: {
+        url: new URL('https://weather.example.com/mcp'),
+        requestInit: {
+          headers: { Authorization: `Bearer ${apiKey}` },
+        },
+      },
+    },
+  })
+
+  const agent = mastra.getAgent('assistant')
+  const response = await agent.generate(prompt, {
+    toolsets: await userMcpClient.listToolsets(),
+  })
+
+  await userMcpClient.disconnect()
+  return response.text
+}
+```
+
+Visit [`listTools()`](https://mastra.ai/reference/tools/mcp-client) and [`listToolsets()`](https://mastra.ai/reference/tools/mcp-client) for their full APIs.
 
-## Tool approval
+### Tool approval
 
-You can require human approval before MCP tools are executed by setting `requireToolApproval` on a server definition. This integrates with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.
+Set `requireToolApproval` on a server to require approval for all its tools:
 
 ```typescript
-export const mcp = new MCPClient({
+const mcpClient = new MCPClient({
   servers: {
     github: {
-      url: new URL('http://localhost:3000/mcp'),
+      url: new URL('https://github.example.com/mcp'),
       requireToolApproval: true,
     },
   },
 })
 ```
 
-You can also pass a function to decide per runtime-call. See the [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for the full API.
-
-## Configuring `MCPServer`
-
-To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
+You can also provide a function that decides based on the tool name, arguments, or annotations:
 
 ```typescript
-import { MCPServer } from '@mastra/mcp'
-
-import { testAgent } from '../agents/test-agent'
-import { testWorkflow } from '../workflows/test-workflow'
-import { testTool } from '../tools/test-tool'
-
-export const testMcpServer = new MCPServer({
-  id: 'test-mcp-server',
-  name: 'Test Server',
-  version: '1.0.0',
-  agents: { testAgent },
-  tools: { testTool },
-  workflows: { testWorkflow },
-})
+requireToolApproval: ({ toolName }) => toolName.startsWith('delete_')
 ```
 
-Visit [MCPServer](https://mastra.ai/reference/tools/mcp-server) for a full list of configuration options.
+Treat tool annotations from servers you don't control as untrusted hints. Visit [tool approval](https://mastra.ai/reference/tools/mcp-client) for the callback context and security guidance.
 
-> **Authentication:** To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/tools/mcp-server) section.
+### Security
 
-## Registering an `MCPServer`
+MCP servers run code and return content on your agent's behalf, so configure them with the same care as any other external dependency:
 
-To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
+- **Stdio subprocess environment**: subprocesses inherit only the MCP SDK's curated environment whitelist (for example `PATH` and `HOME` on POSIX), not the full parent environment. Set `inheritDefaultEnv: false` on a server to pass only the variables you list in `env`.
+- **Outbound host restriction**: when HTTP server URLs come from untrusted configuration, set `allowedHosts` to restrict which hosts the client will contact. On the default fetch path this also blocks redirect hops before they're sent; a custom `fetch` gets its final response URL validated after the request runs, so it must enforce redirect policy itself when preventing outbound contact is required.
+- **Tool response trust**: tool results are untrusted model input. Use [input and output processors](https://mastra.ai/docs/agents/processors) to inspect or sanitize content before it reaches the model, and `requireToolApproval` to gate sensitive tools.
 
-```typescript
-import { Mastra } from '@mastra/core/mastra'
+Visit the [MCPClient security reference](https://mastra.ai/reference/tools/mcp-client) for enforcement details of each option.
 
-import { testMcpServer } from './mcp/test-mcp-server'
+### MCP registries
 
-export const mastra = new Mastra({
-  mcpServers: { testMcpServer },
-})
-```
+Registries provide hosted or packaged MCP servers. The client configuration above works with registry endpoints and commands.
 
-## Static and runtime tools
+| Registry                                        | Connection        | Notes                                         |
+| ----------------------------------------------- | ----------------- | --------------------------------------------- |
+| [Klavis AI](https://klavis.ai)                  | Hosted HTTP       | Enterprise authentication and managed servers |
+| [mcp.run](https://www.mcp.run/)                 | Signed SSE URL    | Treat the profile URL as a secret             |
+| [Composio](https://mcp.composio.dev)            | Hosted SSE URL    | URLs are often tied to one user account       |
+| [Smithery](https://smithery.ai)                 | CLI or hosted URL | Run local packages through `npx`              |
+| [Apify](https://mcp.apify.com)                  | Hosted HTTP       | Authenticate with an Apify API token          |
+| [Ampersand](https://docs.withampersand.com/mcp) | SSE or stdio      | Connect to configured SaaS integrations       |
 
-`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
+Store signed URLs, API keys, and tokens in environment variables. Follow the registry's documentation to obtain the endpoint, command, and credentials for each server.
 
-| Feature           | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`)   |
-| ----------------- | ---------------------------------------------- | ---------------------------------------------------- |
-| **Use Case**      | Single-user, static config (e.g., CLI tool)    | Multi-user, runtime config (e.g., SaaS app)          |
-| **Configuration** | Fixed at agent initialization                  | Per-request, runtime                                 |
-| **Credentials**   | Shared across all uses                         | Can vary per user/request                            |
-| **Agent Setup**   | Tools added in `Agent` constructor             | Tools passed in `.generate()` or `.stream()` options |
+## Expose a Mastra MCP server
 
-### Static tools
-
-Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent. Visit [listTools()](https://mastra.ai/reference/tools/mcp-client) for more information.
+Create an `MCPServer` to expose Mastra primitives to external MCP clients:
 
 ```typescript
-import { Agent } from '@mastra/core/agent'
-
-import { testMcpClient } from '../mcp/test-mcp-client'
+import { MCPServer } from '@mastra/mcp'
+import { assistant } from '../agents/assistant'
+import { weatherTool } from '../tools/weather'
+import { weatherWorkflow } from '../workflows/weather'
 
-export const testAgent = new Agent({
-  id: 'test-agent',
-  tools: await testMcpClient.listTools(),
+export const mcpServer = new MCPServer({
+  id: 'my-mcp-server',
+  name: 'My MCP Server',
+  version: '1.0.0',
+  agents: { assistant },
+  tools: { weatherTool },
+  workflows: { weatherWorkflow },
 })
 ```
 
-### Dynamic tools
-
-Use the `.listToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
+Register the server on the main `Mastra` instance:
 
 ```typescript
-import { MCPClient } from '@mastra/mcp'
-import { mastra } from './mastra'
-
-async function handleRequest(userPrompt: string, userApiKey: string) {
-  const userMcp = new MCPClient({
-    servers: {
-      weather: {
-        url: new URL('http://localhost:8080/mcp'),
-        requestInit: {
-          headers: {
-            Authorization: `Bearer ${userApiKey}`,
-          },
-        },
-      },
-    },
-  })
-
-  const agent = mastra.getAgent('testAgent')
+import { Mastra } from '@mastra/core/mastra'
+import { mcpServer } from './mcp/server'
 
-  const response = await agent.generate(userPrompt, {
-    toolsets: await userMcp.listToolsets(),
-  })
+export const mastra = new Mastra({
+  mcpServers: { mcpServer },
+})
+```
 
-  await userMcp.disconnect()
+> **Authentication:** Protect HTTP MCP servers with OAuth middleware. Visit [OAuth protection](https://mastra.ai/reference/tools/mcp-server) for setup instructions.
 
-  return Response.json({
-    data: response.text,
-  })
-}
-```
+Visit the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for prompts, resources, transports, and other server options.
 
-Visit [listToolsets()](https://mastra.ai/reference/tools/mcp-client) for more information.
+## Build MCP Apps
 
-## Connecting to an MCP registry
+The [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) lets MCP tools serve interactive HTML interfaces through `ui://` resources. Mastra Studio renders these apps in sandboxed iframes on tool pages and in agent chat.
 
-MCP servers can be discovered through registries. Here's how to connect to some popular ones using `MCPClient`:
+Use an MCP App when a tool result benefits from interaction, such as a form, calculator, color picker, or data visualization.
 
-**Klavis AI**:
+### Define an app resource
 
-[Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `_meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
 
 ```typescript
-import { MCPClient } from '@mastra/mcp'
+import { MCPServer } from '@mastra/mcp'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const calculatorTool = createTool({
+  id: 'calculatorWithUI',
+  description: 'Calculate the sum of two numbers',
+  inputSchema: z.object({
+    num1: z.number(),
+    num2: z.number(),
+  }),
+  execute: async ({ num1, num2 }) => ({
+    content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
+    structuredContent: { result: num1 + num2 },
+  }),
+})
 
-const mcp = new MCPClient({
-  servers: {
-    salesforce: {
-      url: new URL(
-        'https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}',
-      ),
-    },
-    hubspot: {
-      url: new URL('https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}'),
+calculatorTool._meta = {
+  ui: { resourceUri: 'ui://calculator/main' },
+}
+
+export const calculatorMcpServer = new MCPServer({
+  id: 'calculator-app-server',
+  name: 'Calculator App Server',
+  version: '1.0.0',
+  tools: { calculatorTool },
+  appResources: {
+    'ui://calculator/main': {
+      name: 'Calculator',
+      htmlPath: './src/mastra/mcp/calculator.html',
     },
   },
 })
 ```
 
-Klavis AI offers enterprise-grade authentication and security for production deployments.
+The model sees `content`, while the app receives `structuredContent`. Visit [`appResources`](https://mastra.ai/reference/tools/mcp-server) for inline HTML, file paths, metadata, and content security policy options.
 
-For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+### Connect the app to Studio
 
-**mcp.run**:
+Use the `App` class from `@modelcontextprotocol/ext-apps` inside the HTML resource. Register event handlers before calling `connect()`:
 
-[mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
+```html
+<!doctype html>
+<html>
+  <body>
+    <p id="result">Waiting for input</p>
+    <button id="recalculate">Recalculate</button>
 
-```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
-    },
-  },
-})
-```
+    <script type="module">
+      import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'
 
-> **Requirement:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
->
-> ```bash
-> MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
-> ```
+      const app = new App({ name: 'Calculator', version: '1.0.0' })
+      let toolInput
 
-**Composio.dev**:
+      app.ontoolinput = params => {
+        toolInput = params.arguments
+      }
 
-[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.
+      document.querySelector('#recalculate').addEventListener('click', async () => {
+        const result = await app.callServerTool({
+          name: 'calculatorWithUI',
+          arguments: toolInput,
+        })
+        document.querySelector('#result').textContent = JSON.stringify(result)
 
-```typescript
-import { MCPClient } from '@mastra/mcp'
+        await app.sendMessage({
+          role: 'user',
+          content: [{ type: 'text', text: 'Explain the recalculated result.' }],
+        })
+      })
 
-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]'),
-    },
-  },
-})
+      await app.connect()
+    </script>
+  </body>
+</html>
 ```
 
-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._
+The guest-side APIs serve different parts of the interaction:
 
-**Smithery.ai**:
+| API                    | Purpose                                               |
+| ---------------------- | ----------------------------------------------------- |
+| `app.ontoolinput`      | Receive the arguments from the host tool call         |
+| `app.callServerTool()` | Call an MCP tool from inside the iframe               |
+| `app.sendMessage()`    | Add a user message to chat and start a new model turn |
+| `app.connect()`        | Connect to the host after registering event handlers  |
 
-[Smithery.ai](https://smithery.ai) provides a registry accessible via their CLI.
+The interaction follows this sequence:
 
-```typescript
-// Unix/Mac
-import { MCPClient } from '@mastra/mcp'
+1. The agent calls the tool.
+2. The tool returns model-facing `content` and UI-facing `structuredContent`.
+3. Studio renders the associated app resource.
+4. The app receives tool input and can call server tools or send chat messages.
 
-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: 'npx',
-      args: [
-        '-y',
-        '@smithery/cli@latest',
-        'run',
-        '@smithery-ai/server-sequential-thinking',
-        '--config',
-        '{}',
-      ],
-    },
-  },
-})
-```
+Visit the external [`App` API reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) for all guest-side methods and lifecycle hooks.
 
-**Apify**:
+### Register MCP Apps
 
-[Apify](https://apify.com) is the largest marketplace of tools for AI, with thousands of ready-made [Actors](https://apify.com/store) to extract real-time data from any website, track competitors, generate leads, analyze sentiment, or orchestrate your apps. Connect your agent through the [Apify MCP Server](https://mcp.apify.com).
+For a local app, pass the tool to an agent and register its MCP server on `Mastra`:
 
 ```typescript
-import { MCPClient } from '@mastra/mcp'
+import { Agent } from '@mastra/core/agent'
+import { Mastra } from '@mastra/core/mastra'
+import { calculatorMcpServer, calculatorTool } from './mcp/calculator'
+
+const calculatorAgent = new Agent({
+  id: 'calculator-agent',
+  name: 'Calculator Agent',
+  instructions: 'Use the calculator tool for arithmetic.',
+  model: 'openai/gpt-5-mini',
+  tools: { calculatorTool },
+})
 
-export const mcp = new MCPClient({
-  servers: {
-    apify: {
-      url: new URL('https://mcp.apify.com'),
-      requestInit: {
-        headers: {
-          Authorization: `Bearer ${process.env.APIFY_TOKEN}`,
-        },
-      },
-    },
-  },
+export const mastra = new Mastra({
+  agents: { calculatorAgent },
+  mcpServers: { calculatorMcpServer },
 })
 ```
 
-Get your API token from the [Apify Console](https://console.apify.com/settings/integrations) and store it as `APIFY_TOKEN` in your environment.
+For an external MCP server that implements MCP Apps, load its tools with `MCPClient.listTools()` and register its proxy so Studio can resolve the remote app resources:
 
-To pick specific Actors and tools, use the [Apify MCP server configurator](https://mcp.apify.com) and copy the generated URL.
-
-**Ampersand**:
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Mastra } from '@mastra/core/mastra'
+import { mcpClient } from './mcp/client'
 
-[Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.
+const tools = await mcpClient.listTools()
+const mcpServers = mcpClient.toMCPServerProxies()
 
-```typescript
-// MCPClient with Ampersand MCP Server using SSE
-export const mcp = new MCPClient({
-  servers: {
-    '@amp-labs/mcp-server': {
-      url: `https://mcp.withampersand.com/v1/sse?${new URLSearchParams({
-        apiKey: process.env.AMPERSAND_API_KEY,
-        project: process.env.AMPERSAND_PROJECT_ID,
-        integrationName: process.env.AMPERSAND_INTEGRATION_NAME,
-        groupRef: process.env.AMPERSAND_GROUP_REF,
-      })}`,
-    },
-  },
+const agent = new Agent({
+  id: 'remote-app-agent',
+  name: 'Remote App Agent',
+  instructions: 'Use the available remote tools.',
+  model: 'openai/gpt-5-mini',
+  tools,
 })
-```
 
-```typescript
-// If you prefer to run the MCP server locally:
-import { MCPClient } from '@mastra/mcp'
-
-// MCPClient with Ampersand MCP Server using stdio transport
-export const mcp = new MCPClient({
-  servers: {
-    '@amp-labs/mcp-server': {
-      command: 'npx',
-      args: [
-        '-y',
-        '@amp-labs/mcp-server@latest',
-        '--transport',
-        'stdio',
-        '--project',
-        process.env.AMPERSAND_PROJECT_ID,
-        '--integrationName',
-        process.env.AMPERSAND_INTEGRATION_NAME,
-        '--groupRef',
-        process.env.AMPERSAND_GROUP_REF, // optional
-      ],
-      env: {
-        AMPERSAND_API_KEY: process.env.AMPERSAND_API_KEY,
-      },
-    },
-  },
+export const mastra = new Mastra({
+  agents: { agent },
+  mcpServers,
 })
 ```
 
-As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so you can [directly import Ampersand tools](https://docs.withampersand.com/ai-sdk#use-with-mastra) for your agent to access.
+Tools loaded through `listTools()` include a `serverId` in `_meta.ui`, allowing Studio to resolve each app resource without scanning every server. Visit [`toMCPServerProxies()`](https://mastra.ai/reference/tools/mcp-client) for proxy configuration details.
+
+### Sandbox security
 
-## MCP Apps
+Mastra Studio uses [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client) to load app HTML through a sandbox proxy and communicate over JSON-RPC with `postMessage`.
 
-MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio, both on tool detail pages and inline in agent chat. The app iframe can call server tools and inject messages into the conversation. Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for setup instructions and the app bridge API.
+App iframes allow scripts, forms, and popups. They can't access the parent page's DOM, cookies, or storage. The host controls all communication with the guest app.
 
-## Related
+## Next steps
 
-- [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps)
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
-- [MCPClient](https://mastra.ai/reference/tools/mcp-client)
-- [MCPServer](https://mastra.ai/reference/tools/mcp-server)
+- [Use tools with agents](https://mastra.ai/docs/agents/using-tools)
+- [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client)
+- [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
+- [MCP Apps extension specification](https://github.com/modelcontextprotocol/ext-apps)