@mastra/mcp 0.4.1-alpha.1 → 0.4.1-alpha.3

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/mcp@0.4.1-alpha.1 build /home/runner/work/mastra/mastra/packages/mcp
+> @mastra/mcp@0.4.1-alpha.3 build /home/runner/work/mastra/mastra/packages/mcp
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.4.0
 TSC Build start
-TSC ⚡️ Build success in 16950ms
+TSC ⚡️ Build success in 16742ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.2
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.2
 Writing package typings: /home/runner/work/mastra/mastra/packages/mcp/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 13984ms
+DTS ⚡️ Build success in 13642ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js 199.82 KB
-ESM ⚡️ Build success in 4421ms
-CJS dist/index.cjs 200.48 KB
-CJS ⚡️ Build success in 4424ms
+CJS dist/index.cjs 203.57 KB
+CJS ⚡️ Build success in 2723ms
+ESM dist/index.js 202.88 KB
+ESM ⚡️ Build success in 2724ms

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/mcp
 
+## 0.4.1-alpha.3
+
+### Patch Changes
+
+- ba1f4f3: Added Streamable HTTP MCP support to MCPConfiguration and MastraMCPClient
+- Updated dependencies [6262bd5]
+  - @mastra/core@0.9.1-alpha.3
+
+## 0.4.1-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [405b63d]
+- Updated dependencies [61e92f5]
+- Updated dependencies [c71013a]
+  - @mastra/core@0.9.1-alpha.2
+
 ## 0.4.1-alpha.1
 
 ### Patch Changes

package/README.md

@@ -5,68 +5,70 @@ Model Context Protocol (MCP) client implementation for Mastra, providing seamles
 ## Installation
 
 ```bash
-npm install @mastra/mcp
+npm install @mastra/mcp@latest
 ```
 
 ## Overview
 
 The `@mastra/mcp` package provides a client implementation for the Model Context Protocol (MCP), enabling Mastra to communicate with MCP-compatible AI models and tools. It wraps the official `@modelcontextprotocol/sdk` and provides Mastra-specific functionality.
 
+The client 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 (protocol version 2025-03-26) and falls back to the legacy SSE transport (protocol version 2024-11-05) if the initial connection fails.
+
 ## Usage
 
 ```typescript
 import { MastraMCPClient } from '@mastra/mcp';
 
-// Create a client with stdio server
+// Create a client with a Stdio server
 const stdioClient = new MastraMCPClient({
   name: 'my-stdio-client',
   version: '1.0.0', // optional
   server: {
     command: 'your-mcp-server-command',
     args: ['--your', 'args'],
+    env: { API_KEY: 'your-api-key' }, // optional environment variables
   },
   capabilities: {}, // optional ClientCapabilities
+  timeout: 60000, // optional timeout for tool calls in milliseconds
 });
 
-// Or create a client with SSE server
-const sseClient = new MastraMCPClient({
-  name: 'my-sse-client',
+// Create a client with an HTTP server (tries Streamable HTTP, falls back to SSE)
+const httpClient = new MastraMCPClient({
+  name: 'my-http-client',
   version: '1.0.0',
   server: {
-    url: new URL('https://your-mcp-server.com/sse'),
+    url: new URL('https://your-mcp-server.com/mcp'), // Use the base URL for Streamable HTTP
     requestInit: {
+      // Optional fetch request configuration
       headers: { Authorization: 'Bearer your-token' },
     },
+    // eventSourceInit is only needed for custom headers with the legacy SSE fallback
     eventSourceInit: {
-      fetch(input: Request | URL | string, init?: RequestInit) {
-        const headers = new Headers(init?.headers || {});
-        headers.set('Authorization', 'Bearer your-token');
-        return fetch(input, {
-          ...init,
-          headers,
-        });
-      },
+      /* ... */
     },
   },
   timeout: 60000, // optional timeout for tool calls in milliseconds
 });
 
-// Connect to the MCP server
-await client.connect();
+// Connect to the MCP server (using one of the clients above)
+await httpClient.connect();
 
 // List available resources
-const resources = await client.resources();
+const resources = await httpClient.resources();
 
 // Get available tools
-const tools = await client.tools();
+const tools = await httpClient.tools();
 
 // Disconnect when done
-await client.disconnect();
+await httpClient.disconnect();
 ```
 
 ## Managing Multiple MCP Servers
 
-For applications that need to interact with multiple MCP servers, the `MCPConfiguration` class provides a convenient way to manage multiple server connections and their tools:
+For applications that need to interact with multiple MCP servers, the `MCPConfiguration` class provides a convenient way to manage multiple server connections and their tools. It also uses the automatic transport detection based on the `server` configuration:
 
 ```typescript
 import { MCPConfiguration } from '@mastra/mcp';
@@ -81,9 +83,13 @@ const mcp = new MCPConfiguration({
         API_KEY: 'your-api-key',
       },
     },
-    // SSE-based server
+    // HTTP-based server (tries Streamable HTTP, falls back to SSE)
     weather: {
-      url: new URL('http://localhost:8080/sse'),
+      url: new URL('http://localhost:8080/mcp'), // Use the base URL for Streamable HTTP
+      requestInit: {
+        // Optional fetch request configuration
+        headers: { 'X-Api-Key': 'weather-key' },
+      },
     },
   },
 });
@@ -118,14 +124,15 @@ const mcp = new MCPConfiguration({
       command: 'npx',
       args: ['tsx', 'weather-mcp.ts'],
       // Attach the logger to this specific server
-      log: weatherLogger,
+      logger: weatherLogger, // Use 'logger' key
     },
 
     stockPriceService: {
       command: 'npx',
       args: ['tsx', 'stock-mcp.ts'],
       // Different logger for this service
-      log: logMessage => {
+      logger: logMessage => {
+        // Use 'logger' key
         // Just log errors and critical events for this service
         if (['error', 'critical', 'alert', 'emergency'].includes(logMessage.level)) {
           console.error(`Stock service ${logMessage.level}: ${logMessage.message}`);
@@ -157,9 +164,11 @@ The `LoggingLevel` type is directly imported from the MCP SDK, ensuring compatib
 You can create reusable logger factories for common patterns:
 
 ```typescript
+import fs from 'node:fs';
+
 // File logger factory with color coded output for different severity levels
-const createFileLogger = filePath => {
-  return logMessage => {
+const createFileLogger = (filePath: string) => {
+  return (logMessage: LogMessage) => {
     // Format the message based on level
     const prefix =
       logMessage.level === 'emergency' ? '!!! EMERGENCY !!! ' : logMessage.level === 'alert' ? '! ALERT ! ' : '';
@@ -178,7 +187,7 @@ const mcp = new MCPConfiguration({
     weatherService: {
       command: 'npx',
       args: ['tsx', 'weather-mcp.ts'],
-      log: createFileLogger('./logs/weather.log'),
+      logger: createFileLogger('./logs/weather.log'), // Use 'logger' key
     },
   },
 });
@@ -200,6 +209,9 @@ Use this when:
 - You want to initialize an Agent with a fixed set of tools
 
 ```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
 const agent = new Agent({
   name: 'CLI Assistant',
   instructions: 'You help users with CLI tasks',
@@ -234,22 +246,16 @@ const mcp = new MCPConfiguration({
       },
     },
     weather: {
-      url: new URL('http://localhost:8080/sse'),
+      url: new URL('http://localhost:8080/mcp'), // Use the base URL for Streamable HTTP
       requestInit: {
         headers: {
           // These would be different per user
           Authorization: 'Bearer user-1-token',
         },
       },
+      // eventSourceInit is only needed for custom headers with the legacy SSE fallback
       eventSourceInit: {
-        fetch(input: Request | URL | string, init?: RequestInit) {
-          const headers = new Headers(init?.headers || {});
-          headers.set('Authorization', 'Bearer user-1-token');
-          return fetch(input, {
-            ...init,
-            headers,
-          });
-        },
+        /* ... */
       },
     },
   },
@@ -273,19 +279,19 @@ The `MCPConfiguration` class automatically:
 - Handles connection lifecycle and cleanup
 - Provides both flat and grouped access to tools
 
-## SSE Authentication and Headers
+## SSE Authentication and Headers (Legacy Fallback)
 
-When using SSE (Server-Sent Events) connections with authentication or custom headers, you need to configure headers in a specific way. The standard `requestInit` headers won't work alone because SSE connections use the browser's `EventSource` API, which doesn't support custom headers directly.
+When the client falls back to using the legacy SSE (Server-Sent Events) transport and you need to include authentication or custom headers, you need to configure headers in a specific way. The standard `requestInit` headers won't work alone because SSE connections using the browser's `EventSource` API don't support custom headers directly.
 
 The `eventSourceInit` configuration allows you to customize the underlying fetch request used for the SSE connection, ensuring your authentication headers are properly included.
 
-To properly include authentication headers or other custom headers in SSE connections, you need to use both `requestInit` and `eventSourceInit`:
+To properly include authentication headers or other custom headers in SSE connections when using the legacy fallback, you need to use both `requestInit` and `eventSourceInit`:
 
 ```typescript
 const sseClient = new MastraMCPClient({
   name: 'authenticated-sse-client',
   server: {
-    url: new URL('https://your-mcp-server.com/sse'),
+    url: new URL('https://your-mcp-server.com/sse'), // Note the typical /sse path for legacy servers
     // requestInit alone isn't enough for SSE connections
     requestInit: {
       headers: { Authorization: 'Bearer your-token' },
@@ -311,38 +317,58 @@ This configuration ensures that:
 2. The connection can be established with the required credentials
 3. Subsequent messages can be received through the authenticated connection
 
-## Configuration
-
-### Required Parameters
-
-- `name`: Name of the MCP client instance
-- `server`: Either a StdioServerParameters or SSEClientParameters object:
-
-  #### StdioServerParameters
+```typescript
+const sseClient = new MastraMCPClient({
+  name: 'authenticated-sse-client',
+  server: {
+    url: new URL('https://your-mcp-server.com/sse'), // Note the typical /sse path for legacy servers
+    // requestInit alone isn't enough for SSE connections
+    requestInit: {
+      headers: { Authorization: 'Bearer your-token' },
+    },
+    // eventSourceInit is required to include headers in the SSE connection
+    eventSourceInit: {
+      fetch(input: Request | URL | string, init?: RequestInit) {
+        const headers = new Headers(init?.headers || {});
+        headers.set('Authorization', 'Bearer your-token');
+        return fetch(input, {
+          ...init,
+          headers,
+        });
+      },
+    },
+  },
+});
+```
 
-  - `command`: Command to start the MCP server
-  - `args`: Array of command arguments
+## Configuration (`MastraMCPServerDefinition`)
 
-  #### SSEClientParameters
+The `server` parameter for both `MastraMCPClient` and `MCPConfiguration` uses the `MastraMCPServerDefinition` type. The client automatically detects the transport type based on the provided parameters:
 
-  - `url`: URL instance pointing to the SSE server
-  - `requestInit`: Optional fetch request configuration
-  - `eventSourceInit`: Optional EventSource configuration
+- If `command` is provided, it uses the Stdio transport.
+- If `url` is provided, it first attempts to use the Streamable HTTP transport and falls back to the legacy SSE transport if the initial connection fails.
 
-### Optional Parameters
+Here are the available options within `MastraMCPServerDefinition`:
 
-- `version`: Client version (default: '1.0.0')
-- `capabilities`: ClientCapabilities object for specifying supported features
-- `log`: Function that receives and processes log messages
+- **`command`**: (Optional, string) For Stdio servers: The command to execute.
+- **`args`**: (Optional, string[]) For Stdio servers: Arguments to pass to the command.
+- **`env`**: (Optional, Record<string, string>) For Stdio servers: Environment variables to set for the command.
+- **`url`**: (Optional, URL) For HTTP servers (Streamable HTTP or SSE): The URL of the server.
+- **`requestInit`**: (Optional, RequestInit) For HTTP servers: Request configuration for the fetch API. Used for the initial Streamable HTTP connection attempt and subsequent POST requests. Also used for the initial SSE connection attempt.
+- **`eventSourceInit`**: (Optional, EventSourceInit) **Only** for the legacy SSE fallback: Custom fetch configuration for SSE connections. Required when using custom headers with SSE.
+- **`logger`**: (Optional, LogHandler) Optional additional handler for logging.
+- **`timeout`**: (Optional, number) Server-specific timeout in milliseconds, overriding the global client/configuration timeout.
+- **`capabilities`**: (Optional, ClientCapabilities) Server-specific capabilities configuration.
+- **`enableServerLogs`**: (Optional, boolean, default: `true`) Whether to enable logging for this server.
 
 ## Features
 
 - Standard MCP client implementation
 - Automatic tool conversion to Mastra format
 - Resource discovery and management
-- Multiple transport layers:
-  - Stdio-based for local servers
-  - SSE-based for remote servers
+- Multiple transport layers with automatic detection:
+  - Stdio-based for local servers (`command`)
+  - HTTP-based for remote servers (`url`): Tries Streamable HTTP first, falls back to legacy SSE.
 - Per-server logging capability using all standard MCP log levels
 - Automatic error handling and logging
 - Tool execution with context
@@ -391,5 +417,8 @@ The client includes comprehensive error handling:
 
 ## Related Links
 
-- [Model Context Protocol Specification](https://github.com/modelcontextprotocol/spec)
-- [@modelcontextprotocol/sdk Documentation](https://github.com/modelcontextprotocol/sdk)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification)
+- [@modelcontextprotocol/sdk Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Mastra Docs: Using MCP With Mastra](/docs/agents/mcp-guide)
+- [Mastra Docs: MCPConfiguration Reference](/reference/tools/mcp-configuration)
+- [Mastra Docs: MastraMCPClient Reference](/reference/tools/client)

package/dist/_tsup-dts-rollup.d.cts

@@ -5,13 +5,20 @@ import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { Tool } from '@mastra/core/tools';
 import { ToolExecutionContext } from '@mastra/core';
 import type { ToolsInput } from '@mastra/core/agent';
 import { z } from 'zod';
 
+declare type BaseServerOptions = {
+    logger?: LogHandler;
+    timeout?: number;
+    capabilities?: ClientCapabilities;
+    enableServerLogs?: boolean;
+};
+
 declare type ConvertedTool = {
     name: string;
     description?: string;
@@ -22,6 +29,17 @@ declare type ConvertedTool = {
 
 export declare function createLogger(server?: Server): Logger;
 
+declare type HttpServerDefinition = BaseServerOptions & {
+    url: URL;
+    command?: never;
+    args?: never;
+    env?: never;
+    requestInit?: StreamableHTTPClientTransportOptions['requestInit'];
+    eventSourceInit?: SSEClientTransportOptions['eventSourceInit'];
+    reconnectionOptions?: StreamableHTTPClientTransportOptions['reconnectionOptions'];
+    sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
+};
+
 export declare interface Logger {
     info: (message: string, data?: any) => Promise<void>;
     warning: (message: string, data?: any) => Promise<void>;
@@ -50,11 +68,12 @@ export { LogMessage as LogMessage_alias_1 }
 
 declare class MastraMCPClient extends MastraBase {
     name: string;
-    private transport;
     private client;
     private readonly timeout;
     private logHandler?;
     private enableServerLogs?;
+    private serverConfig;
+    private transport?;
     constructor({ name, version, server, capabilities, timeout, }: {
         name: string;
         server: MastraMCPServerDefinition;
@@ -70,8 +89,15 @@ declare class MastraMCPClient extends MastraBase {
      */
     private log;
     private setupLogging;
+    private connectStdio;
+    private connectHttp;
     private isConnected;
     connect(): Promise<void>;
+    /**
+     * Get the current session ID if using the Streamable HTTP transport.
+     * Returns undefined if not connected or not using Streamable HTTP.
+     */
+    get sessionId(): string | undefined;
     disconnect(): Promise<void>;
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
     tools(): Promise<Record<string, any>>;
@@ -79,12 +105,7 @@ declare class MastraMCPClient extends MastraBase {
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
-declare type MastraMCPServerDefinition = (StdioServerParameters | SSEClientParameters) & {
-    logger?: LogHandler;
-    timeout?: number;
-    capabilities?: ClientCapabilities;
-    enableServerLogs?: boolean;
-};
+declare type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefinition;
 export { MastraMCPServerDefinition }
 export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
 
@@ -98,6 +119,11 @@ declare class MCPConfiguration extends MastraBase {
     disconnect(): Promise<void>;
     getTools(): Promise<Record<string, any>>;
     getToolsets(): Promise<Record<string, Record<string, any>>>;
+    /**
+     * Get the current session IDs for all connected MCP clients using the Streamable HTTP transport.
+     * Returns an object mapping server names to their session IDs.
+     */
+    get sessionIds(): Record<string, string>;
     private mcpClientsById;
     private getConnectedClient;
     private eachClientTools;
@@ -228,9 +254,16 @@ export declare const server_alias_1: Server<{
     } | undefined;
 }>;
 
-declare type SSEClientParameters = {
-    url: URL;
-} & SSEClientTransportOptions;
+declare type StdioServerDefinition = BaseServerOptions & {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: never;
+    requestInit?: never;
+    eventSourceInit?: never;
+    reconnectionOptions?: never;
+    sessionId?: never;
+};
 
 export declare const weatherTool: Tool<z.ZodObject<{
 location: z.ZodString;

package/dist/_tsup-dts-rollup.d.ts

@@ -5,13 +5,20 @@ import type { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { Tool } from '@mastra/core/tools';
 import { ToolExecutionContext } from '@mastra/core';
 import type { ToolsInput } from '@mastra/core/agent';
 import { z } from 'zod';
 
+declare type BaseServerOptions = {
+    logger?: LogHandler;
+    timeout?: number;
+    capabilities?: ClientCapabilities;
+    enableServerLogs?: boolean;
+};
+
 declare type ConvertedTool = {
     name: string;
     description?: string;
@@ -22,6 +29,17 @@ declare type ConvertedTool = {
 
 export declare function createLogger(server?: Server): Logger;
 
+declare type HttpServerDefinition = BaseServerOptions & {
+    url: URL;
+    command?: never;
+    args?: never;
+    env?: never;
+    requestInit?: StreamableHTTPClientTransportOptions['requestInit'];
+    eventSourceInit?: SSEClientTransportOptions['eventSourceInit'];
+    reconnectionOptions?: StreamableHTTPClientTransportOptions['reconnectionOptions'];
+    sessionId?: StreamableHTTPClientTransportOptions['sessionId'];
+};
+
 export declare interface Logger {
     info: (message: string, data?: any) => Promise<void>;
     warning: (message: string, data?: any) => Promise<void>;
@@ -50,11 +68,12 @@ export { LogMessage as LogMessage_alias_1 }
 
 declare class MastraMCPClient extends MastraBase {
     name: string;
-    private transport;
     private client;
     private readonly timeout;
     private logHandler?;
     private enableServerLogs?;
+    private serverConfig;
+    private transport?;
     constructor({ name, version, server, capabilities, timeout, }: {
         name: string;
         server: MastraMCPServerDefinition;
@@ -70,8 +89,15 @@ declare class MastraMCPClient extends MastraBase {
      */
     private log;
     private setupLogging;
+    private connectStdio;
+    private connectHttp;
     private isConnected;
     connect(): Promise<void>;
+    /**
+     * Get the current session ID if using the Streamable HTTP transport.
+     * Returns undefined if not connected or not using Streamable HTTP.
+     */
+    get sessionId(): string | undefined;
     disconnect(): Promise<void>;
     resources(): Promise<ReturnType<Protocol<any, any, any>['request']>>;
     tools(): Promise<Record<string, any>>;
@@ -79,12 +105,7 @@ declare class MastraMCPClient extends MastraBase {
 export { MastraMCPClient }
 export { MastraMCPClient as MastraMCPClient_alias_1 }
 
-declare type MastraMCPServerDefinition = (StdioServerParameters | SSEClientParameters) & {
-    logger?: LogHandler;
-    timeout?: number;
-    capabilities?: ClientCapabilities;
-    enableServerLogs?: boolean;
-};
+declare type MastraMCPServerDefinition = StdioServerDefinition | HttpServerDefinition;
 export { MastraMCPServerDefinition }
 export { MastraMCPServerDefinition as MastraMCPServerDefinition_alias_1 }
 
@@ -98,6 +119,11 @@ declare class MCPConfiguration extends MastraBase {
     disconnect(): Promise<void>;
     getTools(): Promise<Record<string, any>>;
     getToolsets(): Promise<Record<string, Record<string, any>>>;
+    /**
+     * Get the current session IDs for all connected MCP clients using the Streamable HTTP transport.
+     * Returns an object mapping server names to their session IDs.
+     */
+    get sessionIds(): Record<string, string>;
     private mcpClientsById;
     private getConnectedClient;
     private eachClientTools;
@@ -228,9 +254,16 @@ export declare const server_alias_1: Server<{
     } | undefined;
 }>;
 
-declare type SSEClientParameters = {
-    url: URL;
-} & SSEClientTransportOptions;
+declare type StdioServerDefinition = BaseServerOptions & {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: never;
+    requestInit?: never;
+    eventSourceInit?: never;
+    reconnectionOptions?: never;
+    sessionId?: never;
+};
 
 export declare const weatherTool: Tool<z.ZodObject<{
 location: z.ZodString;