@mastra/mcp 1.15.1 → 1.16.0-alpha.1

package/dist/client/url-policy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Minimal structural view of a fetch response. Both the platform `Response`
+ * and the eventsource package's `FetchLikeResponse` (used for a caller-supplied
+ * `eventSourceInit.fetch`) satisfy it.
+ */
+type ResponseLike = {
+    readonly url: string;
+    readonly body?: unknown;
+};
+/**
+ * Assert that the URL's host is in the allowlist.
+ *
+ * Matching is exact and case-insensitive against `URL.host` (hostname plus
+ * port when the URL carries a non-default port — WHATWG URL elides default
+ * ports, so `https://x.com:443` has host `x.com`). No wildcards. An empty
+ * allowlist denies every host. The URL scheme is not checked.
+ *
+ * @returns the parsed URL, for callers that need it.
+ * @throws {MastraError} `MCP_CLIENT_HOST_NOT_ALLOWED` when the host is not allowed.
+ */
+export declare function assertHostAllowed(url: string | URL, allowedHosts: readonly string[], detail?: string): URL;
+/**
+ * Post-hoc validation for responses produced by a caller-supplied fetch.
+ *
+ * A custom fetch may auto-follow redirects, so the final URL can differ from
+ * the (already validated) request URL. When `response.url` lands on a
+ * disallowed host the response is discarded by throwing — the outbound hop
+ * already happened, but the data never reaches the caller or the model.
+ *
+ * Limitation (fail-open by design): a hand-built or proxied `Response` with an
+ * empty `response.url` skips this check, because custom fetch implementations
+ * legitimately construct such responses.
+ */
+export declare function assertResponseHostAllowed<R extends ResponseLike>(response: R, allowedHosts: readonly string[]): R;
+export declare function isUrlPolicyError(error: unknown): boolean;
+/**
+ * Wrap a caller-supplied fetch with the allowedHosts policy: the request URL is
+ * validated before the wrapped fetch runs, and the response is validated
+ * post-hoc via {@link assertResponseHostAllowed}.
+ *
+ * Variadic over the trailing arguments deliberately: the same wrapper serves
+ * the 3-arg `MastraFetchLike` (url, init, requestContext) and the 2-arg
+ * eventsource stream fetch (url, init).
+ */
+export declare function wrapFetchWithHostPolicy<Args extends [url: string | URL, ...rest: any[]], R extends ResponseLike>(fetchImpl: (...args: Args) => Promise<R>, allowedHosts: readonly string[]): (...args: Args) => Promise<R>;
+/**
+ * Fetch with manual redirect handling so every redirect hop is validated
+ * against the allowlist BEFORE the hop request is sent. Platform fetch follows
+ * redirects transparently, which would bypass a per-call host check.
+ *
+ * Semantics follow platform conventions:
+ * - `Location` is resolved against the current hop's URL (relative Locations are legal).
+ * - 303 switches the method to GET and drops the body; 301/302 on POST do the same.
+ * - 307/308 preserve method and body; a non-replayable body (anything other
+ *   than a string) throws rather than silently re-sending an empty body.
+ * - 301/302 on non-POST methods preserve the method and body, matching
+ *   platform behavior.
+ * - The `Authorization` header is not carried across hops to a different
+ *   origin (scheme, host, or port change), matching the WHATWG Fetch
+ *   credential-stripping rule — same host over a downgraded scheme still
+ *   drops the header.
+ * - A redirect status with no `Location` header throws.
+ * - More than {@link MAX_REDIRECT_HOPS} hops throws.
+ */
+export declare function fetchFollowingAllowedRedirects(fetchImpl: (url: string | URL, init?: RequestInit) => Promise<Response>, url: string | URL, init: RequestInit | undefined, allowedHosts: readonly string[]): Promise<Response>;
+export {};
+//# sourceMappingURL=url-policy.d.ts.map

package/dist/client/url-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-policy.d.ts","sourceRoot":"","sources":["../../src/client/url-policy.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,KAAK,YAAY,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgDtE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,MAAM,SAA8B,GACnC,GAAG,CAML;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAcjH;AAmBD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,SAAS,YAAY,EAC9G,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACxC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAM/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,EACvE,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAoEnB"}

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mcp
 description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mcp"
-  version: "1.15.1"
+  version: "1.16.0-alpha.1"
 ---
 
 ## When to use
@@ -16,8 +16,8 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [MCP Apps](references/docs-mcp-mcp-apps.md) - Serve interactive HTML UIs from MCP tools using the MCP Apps extension.
-- [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient and connect to registries, plus share your own tools using MCPServer.
+- [Connections overview](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
+- [MCP overview](references/docs-mcp-overview.md) - Connect Mastra agents to external MCP servers, expose Mastra tools through MCPServer, and build interactive MCP Apps for Studio.
 - [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
 
 ### Reference

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.15.1",
+  "version": "1.16.0-alpha.1",
   "package": "@mastra/mcp",
   "exports": {},
   "modules": {}

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

@@ -0,0 +1,94 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Connections overview
+
+Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
+
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+
+## When to use connections
+
+Use connections when you need to:
+
+- Delegate work to an agent running in another service or runtime.
+- Run a coding agent against a project workspace.
+- Add a provider-native agent without replacing its SDK runtime or agent loop.
+- Connect agents to external tools and resources or publish Mastra capabilities to other systems.
+
+## Get started
+
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+
+**A2A**:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/.well-known/agent-card.json',
+})
+
+const result = await agent.generate('Summarize the latest report')
+console.log(result.text)
+```
+
+**ACP**:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+const agent = new AcpAgent({
+  id: 'coding-agent',
+  description: 'Inspects and edits code',
+  command: 'claude',
+  args: ['--acp'],
+  persistSession: false,
+})
+
+const result = await agent.generate('Review this project')
+console.log(result.text)
+```
+
+**SDK agents**:
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const agent = new OpenAISDKAgent({
+  id: 'openai-agent',
+  description: 'Answers project questions',
+  sdkOptions: {
+    name: 'Project assistant',
+    model: 'gpt-5',
+  },
+})
+
+const result = await agent.generate('Explain agent loops in one sentence')
+console.log(result.text)
+```
+
+**MCP**:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const client = new MCPClient({
+  id: 'wikipedia-client',
+  servers: {
+    wikipedia: {
+      command: 'npx',
+      args: ['-y', 'wikipedia-mcp'],
+    },
+  },
+})
+
+try {
+  const tools = await client.listTools()
+  console.log(Object.keys(tools))
+} finally {
+  await client.disconnect()
+}
+```