chore (ai/mcp): add assertCapability method to experimental MCP client (#6047)

<!--
Welcome to contributing to AI SDK! We're excited to see your changes.

We suggest you read the following contributing guide we've created
before submitting:

https://github.com/vercel/ai/blob/main/CONTRIBUTING.md
-->

## Background

Splits up #5972 into package changes
and updates to examples.

## Summary

Moves capabilities validation downstream to the request level instead of
the method level.

This PR adds a new private `assertCapability` method called at the
request level. This means our custom, lightweight client defaults strict
mode to true for tool listing and tool calling.

## Verification

<!--
For features & bugfixes.
Please explain how you *manually* verified that the change works
end-to-end as expected (independent of automated tests).
Remove the section if it's not needed (e.g. for docs).
-->

## Tasks

<!--
This task list is intended to help you keep track of what you need to
do.
Feel free to add tasks and remove unnecessary tasks as needed.

Please check if the PR fulfills the following requirements:
-->

- [x] Tests have been added / updated (for bug fixes / features)
- [ ] Documentation has been added / updated (for bug fixes / features)
- [x] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)
- [x] Formatting issues have been fixed (run `pnpm prettier-fix` in the
project root)

## Future Work

<!--
Feel free to mention things not covered by this PR that can be done in
future PRs.
Remove the section if it's not needed.
 -->

## Related Issues

<!--
List related issues here, e.g. "Fixes #1234".
Remove the section if it's not needed.
-->

Author: iteratetograceness

.changeset/sour-mails-cheer.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+chore (ai/mcp): add `assertCapability` method to experimental MCP client

packages/ai/core/tool/mcp/mcp-client.ts

@@ -61,9 +61,13 @@ export async function createMCPClient(
  * Tool parameters are automatically inferred from the server's JSON schema
  * if not explicitly provided in the tools configuration
  *
+ * This client is meant to be used to communicate with a single server. To communicate and fetch tools across multiple servers, it's recommended to create a new client instance per server.
+ *
  * Not supported:
  * - Client options (e.g. sampling, roots) as they are not needed for tool conversion
  * - Accepting notifications
+ * - Session management (when passing a sessionId to an instance of the Streamable HTTP transport)
+ * - Resumable SSE streams
  */
 class MCPClient {
   private transport: MCPTransport;
@@ -163,6 +167,25 @@ class MCPClient {
     this.onClose();
   }
 
+  private assertCapability(method: string): void {
+    switch (method) {
+      case 'initialize':
+        break;
+      case 'tools/list':
+      case 'tools/call':
+        if (!this.serverCapabilities.tools) {
+          throw new MCPClientError({
+            message: `Server does not support tools`,
+          });
+        }
+        break;
+      default:
+        throw new MCPClientError({
+          message: `Unsupported method: ${method}`,
+        });
+    }
+  }
+
   private async request<T extends ZodType<object>>({
     request,
     resultSchema,
@@ -181,6 +204,8 @@ class MCPClient {
         );
       }
 
+      this.assertCapability(request.method);
+
       const signal = options?.signal;
       signal?.throwIfAborted();
 
@@ -214,7 +239,7 @@ class MCPClient {
           resolve(result);
         } catch (error) {
           const parseError = new MCPClientError({
-            message: 'Failed to parse server initialization result',
+            message: 'Failed to parse server response',
             cause: error,
           });
           reject(parseError);
@@ -235,12 +260,6 @@ class MCPClient {
     params?: PaginatedRequest['params'];
     options?: RequestOptions;
   } = {}): Promise<ListToolsResult> {
-    if (!this.serverCapabilities.tools) {
-      throw new MCPClientError({
-        message: `Server does not support tools`,
-      });
-    }
-
     try {
       return this.request({
         request: { method: 'tools/list', params },
@@ -261,12 +280,6 @@ class MCPClient {
     args: Record<string, unknown>;
     options?: ToolExecutionOptions;
   }): Promise<CallToolResult> {
-    if (!this.serverCapabilities.tools) {
-      throw new MCPClientError({
-        message: `Server does not support tools`,
-      });
-    }
-
     try {
       return this.request({
         request: { method: 'tools/call', params: { name, arguments: args } },

packages/ai/core/tool/mcp/mock-mcp-transport.ts

@@ -82,6 +82,17 @@ export class MockMCPTransport implements MCPTransport {
 
       if (message.method === 'tools/list') {
         await delay(10);
+        if (this.tools.length === 0) {
+          this.onmessage?.({
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32000,
+              message: 'Method not supported',
+            },
+          });
+          return;
+        }
         this.onmessage?.({
           jsonrpc: '2.0',
           id: message.id,