Feature/http streamable support (#364)

* add HTTP Streamable support

* docs update

* Add check script to package.json

- Add npm run check script that runs the core tests
- Simplifies CI/CD testing by providing standard check command

* Revert "Add check script to package.json"

This reverts commit be3aca9.

* updated  README and example to use HTTP streaming

* updated docs

* prettier fix

* removed client tests, fixed readme

Author: whoiskatrin

.changeset/modern-geckos-check.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+add HTTP Streamable support

examples/mcp-client/README.md

@@ -1,6 +1,13 @@
 # MCP Client Demo Using Agents
 
-A minimal example showing an `Agent` as an MCP client.
+A minimal example showing an `Agent` as an MCP client with support for both SSE and HTTP Streamable transports.
+
+## Transport Options
+
+The MCP client supports two transport types:
+
+- **HTTP Streamable** (recommended): Uses HTTP POST + SSE for better performance and reliability
+- **SSE (Server-Sent Events)**
 
 ## Instructions
 
@@ -15,8 +22,34 @@ Then, follow the steps below to setup the client:
 
 Tap "O + enter" to open the front end. It should list out all the tools, prompts, and resources available for each server added.
 
-## Troubleshooting
-
-### TypeError: Cannot read properties of undefined (reading 'connectionState')
-
-Clear the Local Storage cookies in your browser, then restart the client.
+## Transport Configuration
+
+The MCP client defaults to HTTP Streamable transport for better performance. You can specify transport type explicitly:
+
+```typescript
+// Using MCPClientManager directly
+const mcpClient = new MCPClientManager("my-app", "1.0.0");
+
+// HTTP Streamable transport (default, recommended)
+await mcpClient.connect(serverUrl, {
+  transport: {
+    type: "streamable-http",
+    authProvider: myAuthProvider
+  }
+});
+
+// SSE transport (legacy compatibility)
+await mcpClient.connect(serverUrl, {
+  transport: {
+    type: "sse",
+    authProvider: myAuthProvider
+  }
+});
+
+// Or using Agent.addMcpServer() (as shown in the example)
+export class MyAgent extends Agent<Env, never> {
+  async addServer(name: string, url: string, callbackHost: string) {
+    await this.addMcpServer(name, url, callbackHost);
+  }
+}
+```

examples/mcp/src/server.ts

@@ -49,6 +49,6 @@ export class MyMCP extends McpAgent<Env, State, {}> {
   }
 }
 
-export default MyMCP.mount("/sse", {
+export default MyMCP.serve("/mcp", {
   binding: "MyMCP"
 });

packages/agents/README.md

@@ -393,6 +393,111 @@ This creates:
 - Intuitive input handling
 - Easy conversation reset
 
+### 🔗 MCP (Model Context Protocol) Integration
+
+Agents can seamlessly integrate with the Model Context Protocol, allowing them to act as both MCP servers (providing tools to AI assistants) and MCP clients (using tools from other services).
+
+#### Creating an MCP Server
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpAgent } from "agents/mcp";
+import { z } from "zod";
+
+type Env = {
+  MyMCP: DurableObjectNamespace<MyMCP>;
+};
+
+type State = { counter: number };
+
+export class MyMCP extends McpAgent<Env, State, {}> {
+  server = new McpServer({
+    name: "Demo",
+    version: "1.0.0"
+  });
+
+  initialState: State = {
+    counter: 1
+  };
+
+  async init() {
+    this.server.resource("counter", "mcp://resource/counter", (uri) => {
+      return {
+        contents: [{ text: String(this.state.counter), uri: uri.href }]
+      };
+    });
+
+    this.server.tool(
+      "add",
+      "Add to the counter, stored in the MCP",
+      { a: z.number() },
+      async ({ a }) => {
+        this.setState({ ...this.state, counter: this.state.counter + a });
+
+        return {
+          content: [
+            {
+              text: String(`Added ${a}, total is now ${this.state.counter}`),
+              type: "text"
+            }
+          ]
+        };
+      }
+    );
+  }
+
+  onStateUpdate(state: State) {
+    console.log({ stateUpdate: state });
+  }
+}
+
+// HTTP Streamable transport (recommended)
+export default MyMCP.serve("/mcp", {
+  binding: "MyMCP"
+});
+
+// Or SSE transport for legacy compatibility
+// export default MyMCP.serveSSE("/mcp", { binding: "MyMCP" });
+```
+
+#### Using MCP Tools
+
+```typescript
+import { MCPClientManager } from "agents/mcp";
+
+const client = new MCPClientManager("my-app", "1.0.0");
+
+// Connect to an MCP server
+await client.connect("https://weather-service.com/mcp", {
+  transport: { type: "streamable-http" }
+});
+
+// Use tools from the server
+const weather = await client.callTool({
+  serverId: "weather-service",
+  name: "getWeather",
+  arguments: { location: "San Francisco" }
+});
+```
+
+#### AI SDK Integration
+
+```typescript
+import { generateText } from "ai";
+
+// Convert MCP tools for AI use
+const result = await generateText({
+  model: openai("gpt-4"),
+  tools: client.unstable_getAITools(),
+  prompt: "What's the weather in Tokyo?"
+});
+```
+
+**Transport Options:**
+
+- **HTTP Streamable**: Best performance, batch requests, session management
+- **SSE**: Simple setup, legacy compatibility
+
 ### 💬 The Path Forward
 
 We're developing new dimensions of agent capability:

packages/agents/src/mcp/client-connection.ts

@@ -1,5 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import {
   // type ClientCapabilities,
   type ListPromptsResult,
@@ -18,6 +19,15 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import type { AgentsOAuthProvider } from "./do-oauth-client-provider";
 import { SSEEdgeClientTransport } from "./sse-edge";
+import { StreamableHTTPEdgeClientTransport } from "./streamable-http-edge";
+
+export type MCPTransportOptions = (
+  | SSEClientTransportOptions
+  | StreamableHTTPClientTransportOptions
+) & {
+  authProvider?: AgentsOAuthProvider;
+  type?: "sse" | "streamable-http";
+};
 
 export class MCPClientConnection {
   client: Client;
@@ -38,9 +48,7 @@ export class MCPClientConnection {
     public url: URL,
     info: ConstructorParameters<typeof Client>[0],
     public options: {
-      transport: SSEClientTransportOptions & {
-        authProvider?: AgentsOAuthProvider;
-      };
+      transport: MCPTransportOptions;
       client: ConstructorParameters<typeof Client>[1];
     } = { client: {}, transport: {} }
   ) {
@@ -55,10 +63,17 @@ export class MCPClientConnection {
    */
   async init(code?: string) {
     try {
-      const transport = new SSEEdgeClientTransport(
-        this.url,
-        this.options.transport
-      );
+      const transportType = this.options.transport.type || "streamable-http";
+      const transport =
+        transportType === "streamable-http"
+          ? new StreamableHTTPEdgeClientTransport(
+              this.url,
+              this.options.transport as StreamableHTTPClientTransportOptions
+            )
+          : new SSEEdgeClientTransport(
+              this.url,
+              this.options.transport as SSEClientTransportOptions
+            );
 
       if (code) {
         await transport.finishAuth(code);

packages/agents/src/mcp/client.ts

@@ -1,5 +1,4 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import type { SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
 import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type {
   CallToolRequest,
@@ -14,8 +13,10 @@ import type {
 } from "@modelcontextprotocol/sdk/types.js";
 import { type ToolSet, jsonSchema } from "ai";
 import { nanoid } from "nanoid";
-import { MCPClientConnection } from "./client-connection";
-import type { AgentsOAuthProvider } from "./do-oauth-client-provider";
+import {
+  MCPClientConnection,
+  type MCPTransportOptions
+} from "./client-connection";
 
 /**
  * Utility class that aggregates multiple MCP clients into one
@@ -52,9 +53,7 @@ export class MCPClientManager {
         oauthCode?: string;
       };
       // we're overriding authProvider here because we want to be able to access the auth URL
-      transport?: SSEClientTransportOptions & {
-        authProvider?: AgentsOAuthProvider;
-      };
+      transport?: MCPTransportOptions;
       client?: ConstructorParameters<typeof Client>[1];
     } = {}
   ): Promise<{

packages/agents/src/mcp/index.ts

@@ -12,7 +12,7 @@ import {
   isJSONRPCResponse
 } from "@modelcontextprotocol/sdk/types.js";
 import type { Connection, WSMessage } from "../";
-import { Agent } from "../";
+import { Agent } from "../index";
 
 const MAXIMUM_MESSAGE_SIZE_BYTES = 4 * 1024 * 1024; // 4MB
 
@@ -1149,3 +1149,7 @@ export abstract class McpAgent<
     };
   }
 }
+
+// Export client transport classes
+export { SSEEdgeClientTransport } from "./sse-edge";
+export { StreamableHTTPEdgeClientTransport } from "./streamable-http-edge";

packages/agents/src/mcp/streamable-http-edge.ts

@@ -0,0 +1,63 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import {
+  StreamableHTTPClientTransport,
+  type StreamableHTTPClientTransportOptions
+} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+export class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTransport {
+  private authProvider: OAuthClientProvider | undefined;
+
+  /**
+   * Creates a new StreamableHTTPEdgeClientTransport, which overrides fetch to be compatible with the CF workers environment
+   */
+  constructor(url: URL, options: StreamableHTTPClientTransportOptions) {
+    const fetchOverride: typeof fetch = async (
+      fetchUrl: RequestInfo | URL,
+      fetchInit: RequestInit = {}
+    ) => {
+      // add auth headers
+      const headers = await this.authHeaders();
+      const workerOptions = {
+        ...fetchInit,
+        headers: {
+          ...options.requestInit?.headers,
+          ...fetchInit?.headers,
+          ...headers
+        }
+      };
+
+      // Remove unsupported properties
+      delete workerOptions.mode;
+
+      // Call the original fetch with fixed options
+      return (
+        // @ts-expect-error Custom fetch function for Cloudflare Workers compatibility
+        (options.requestInit?.fetch?.(
+          fetchUrl as URL | string,
+          workerOptions
+        ) as Promise<Response>) || fetch(fetchUrl, workerOptions)
+      );
+    };
+
+    super(url, {
+      ...options,
+      requestInit: {
+        ...options.requestInit,
+        // @ts-expect-error Custom fetch override for Cloudflare Workers
+        fetch: fetchOverride
+      }
+    });
+    this.authProvider = options.authProvider;
+  }
+
+  async authHeaders() {
+    if (this.authProvider) {
+      const tokens = await this.authProvider.tokens();
+      if (tokens) {
+        return {
+          Authorization: `Bearer ${tokens.access_token}`
+        };
+      }
+    }
+  }
+}