chore (docs): restructure MCP setup examples (#5356)

Author: lgrammel

content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -637,54 +637,74 @@ This enables your AI applications to discover and use tools across various servi
 
 Create an MCP client using either:
 
-- `stdio`: Uses standard input and output streams for communication, ideal for local tool servers running on the same machine (like CLI tools or local services)
 - `SSE` (Server-Sent Events): Uses HTTP-based real-time communication, better suited for remote servers that need to send data over the network
+- `stdio`: Uses standard input and output streams for communication, ideal for local tool servers running on the same machine (like CLI tools or local services)
 - Custom transport: Bring your own transport by implementing the `MCPTransport` interface
 
+#### SSE Transport
+
+The SSE can be configured using a simple object with a `type` and `url` property:
+
 ```typescript
 import { experimental_createMCPClient as createMCPClient } from 'ai';
-import { Experimental_StdioMCPTransport as StdioMCPTransport } from 'ai/mcp-stdio';
-
-// Example of using MCP with stdio
-const mcpClient = await createMCPClient({
-  transport: new StdioMCPTransport({
-    command: 'node',
-    args: ['src/stdio/dist/server.js'],
-  }),
-});
 
-// Example of using MCP with SSE
 const mcpClient = await createMCPClient({
   transport: {
     type: 'sse',
     url: 'https://my-server.com/sse',
 
-    // optional: configure HTTP headers
+    // optional: configure HTTP headers, e.g. for authentication
     headers: {
-      example: 'header',
+      Authorization: 'Bearer my-api-key',
     },
   },
 });
+```
 
-// Example of using a custom transport
-const transport = new MyCustomTransport({
-  // ...
+#### Stdio Transport
+
+The Stdio transport requires importing the `StdioMCPTransport` class from the `ai/mcp-stdio` package:
+
+```typescript
+import { experimental_createMCPClient as createMCPClient } from 'ai';
+import { Experimental_StdioMCPTransport as StdioMCPTransport } from 'ai/mcp-stdio';
+
+const mcpClient = await createMCPClient({
+  transport: new StdioMCPTransport({
+    command: 'node',
+    args: ['src/stdio/dist/server.js'],
+  }),
 });
+```
+
+#### Custom Transport
+
+You can also bring your own transport by implementing the `MCPTransport` interface:
+
+```typescript
+import { MCPTransport, createMCPClient } from 'ai';
+
 const mcpClient = await createMCPClient({
-  transport,
+  transport: new MyCustomTransport({
+    // ...
+  }),
 });
 ```
 
+#### Closing the MCP Client
+
 After initialization, always close the MCP client when you're done to prevent resource leaks. Use try/finally or cleanup functions in your framework:
 
 ```typescript
-  try {
-    const mcpClient = await experimental_createMCPClient({...});
-    const tools = await mcpClient.tools();
-    // use tools...
-  } finally {
-    await mcpClient?.close();
-  }
+let mcpClient: MCPClient | undefined;
+try {
+  mcpClient = await experimental_createMCPClient({
+    // ...
+  });
+  // ...
+} finally {
+  await mcpClient?.close();
+}
 ```
 
 ### Using MCP Tools