feat: MCP Tool Chain Support

README.md

@@ -604,6 +604,39 @@ const realtime = new OpenAIRealtimeProvider({
 });
 ```
 
+### MCP Tool Servers
+
+Connect your agent to any number of [Model Context Protocol](https://modelcontextprotocol.io/) servers. The SDK loads tool definitions from each server, namespaces them, and routes every invocation through MCP automatically.
+
+```tsx
+const realtime = new OpenAIRealtimeProvider({
+  apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY!,
+  mcpServers: [
+    {
+      id: "docs",
+      url: process.env.NEXT_PUBLIC_DOCS_MCP_URL!,
+      headers: {
+        Authorization: `Bearer ${process.env.NEXT_PUBLIC_DOCS_MCP_TOKEN!}`,
+      },
+      toolNamePrefix: "docs__", // optional (defaults to `${id}__`)
+    },
+    {
+      id: "inventory",
+      url: process.env.NEXT_PUBLIC_INVENTORY_MCP_URL!,
+    },
+  ],
+});
+```
+
+What you get for free:
+
+- Streamable HTTP transport management for each MCP server.
+- Automatic pagination to fetch every declared tool.
+- Guaranteed unique tool names via configurable prefixes so OpenAI can call them safely.
+- Tool outputs are converted into OpenAI function responses, keeping the realtime session in sync.
+
+You can mix MCP-provided tools with traditional `tools` functions to blend local logic and remote capabilities.
+
 ### Mock Provider (Development)
 
 Perfect for testing without API keys:

packages/core/src/types/realtime.ts

@@ -1,6 +1,48 @@
 import { RealtimeMessage, Conversation, ChatStatus } from './conversation';
 import { MouthState, PhonemeData } from './audio';
 
+/**
+ * Configuration for connecting to an MCP server
+ */
+export interface MCPServerConfig {
+  /**
+   * Unique identifier for the server. Used for tool name prefixing.
+   */
+  id: string;
+  /**
+   * Streamable HTTP endpoint for the MCP server.
+   */
+  url: string;
+  /**
+   * Future-proofing for additional transports. Currently only streamable-http is supported.
+   */
+  transport?: 'streamable-http';
+  /**
+   * Optional HTTP headers to send on every transport request (e.g., auth tokens).
+   */
+  headers?: Record<string, string>;
+  /**
+   * Client identity used when registering with the MCP server.
+   */
+  client?: {
+    name?: string;
+    version?: string;
+    /**
+     * Capabilities object forwarded directly to the MCP client.
+     */
+    capabilities?: Record<string, unknown>;
+  };
+  /**
+   * Optional prefix used when exposing server tools inside the realtime provider.
+   * Defaults to `${id}__`.
+   */
+  toolNamePrefix?: string | null;
+  /**
+   * Extra metadata for application-specific use.
+   */
+  metadata?: Record<string, string>;
+}
+
 /**
  * Tool definition for function calling
  */
@@ -31,6 +73,7 @@ export interface RealtimeConfig {
   instructions?: string;
   temperature?: number;
   tools?: RealtimeTool[];
+  mcpServers?: MCPServerConfig[];
   turnServers?: RTCIceServer[];
   speed?: number;
   enableLipSync?: boolean;
@@ -85,4 +128,4 @@ export interface RealtimeProvider extends RealtimeEvents {
   enableMicrophone(): void;
   disableMicrophone(): void;
   isMicrophoneEnabled(): boolean;
-}
+}

packages/providers/openai-realtime/README.md

@@ -312,6 +312,39 @@ const realtime = new OpenAIRealtimeProvider({
 realtime.registerFunction(weatherTool);
 ```
 
+### MCP Servers (Model Context Protocol)
+
+You can mount any number of MCP servers and expose their tools directly to OpenAI. Each server describes its tools via the MCP spec; the provider handles the rest (connections, pagination, name-spacing, execution, and returning results to the realtime session).
+
+```tsx
+const realtime = new OpenAIRealtimeProvider({
+  apiKey: process.env.OPENAI_API_KEY || "",
+  mcpServers: [
+    {
+      id: "docs",
+      url: process.env.DOCS_MCP_URL!,
+      headers: {
+        Authorization: `Bearer ${process.env.DOCS_MCP_TOKEN!}`,
+      },
+      toolNamePrefix: "docs__", // optional (defaults to `${id}__`)
+    },
+    {
+      id: "inventory",
+      url: process.env.INVENTORY_MCP_URL!,
+    },
+  ],
+});
+```
+
+`MCPServerConfig` options:
+
+- `id`: unique identifier. Also used as the default prefix for tools (`${id}__toolName`).
+- `url`: Streamable HTTP endpoint for the server (e.g., `https://.../mcp`).
+- `headers`: optional HTTP headers for auth.
+- `toolNamePrefix`: override the default prefix (set to `null` to keep original names).
+
+Remote tools are converted into OpenAI function definitions alongside any local `tools`, and responses are sent back through the MCP client automatically.
+
 ## 📱 Chat Status States
 
 The `chatStatus` property provides real-time feedback:
@@ -426,4 +459,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## 🚀 Contributing
 
-Contributions welcome! Please read our contributing guidelines and submit pull requests to our [GitHub repository](https://github.com/SolveServeSolution/khaveeai-sdk).
+Contributions welcome! Please read our contributing guidelines and submit pull requests to our [GitHub repository](https://github.com/SolveServeSolution/khaveeai-sdk).

packages/providers/openai-realtime/package.json

@@ -42,6 +42,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
     "@khaveeai/core": "^0.1.5",
     "uuid": "^13.0.0"
   },

packages/providers/openai-realtime/src/OpenAIRealtimeProvider.ts

@@ -12,6 +12,7 @@ import {
 } from "@khaveeai/core";
 import { v4 as uuidv4 } from "uuid";
 import { ToolExecutor } from "./ToolExecutor";
+import { MCPToolManager } from "./mcp/MCPToolManager";
 
 export class OpenAIRealtimeProvider implements RealtimeProvider {
   private config: RealtimeConfig;
@@ -20,6 +21,10 @@ export class OpenAIRealtimeProvider implements RealtimeProvider {
   private audioContext: AudioContext | null = null;
   private audioStream: MediaStream | null = null;
   private toolExecutor: ToolExecutor;
+  private manualTools: RealtimeTool[] = [];
+  private mcpTools: RealtimeTool[] = [];
+  private mcpManager?: MCPToolManager;
+  private mcpInitialization?: Promise<void>;
 
   // State
   public isConnected = false;
@@ -64,9 +69,20 @@ export class OpenAIRealtimeProvider implements RealtimeProvider {
 
     this.toolExecutor = new ToolExecutor();
 
-    // Register initial tools
     if (this.config.tools) {
-      this.config.tools.forEach((tool) => this.registerFunction(tool));
+      this.config.tools.forEach((tool) => this.registerTool(tool, "manual"));
+    }
+
+    if (this.config.mcpServers && this.config.mcpServers.length > 0) {
+      this.mcpManager = new MCPToolManager(this.config.mcpServers);
+      this.mcpInitialization = this.mcpManager
+        .initialize()
+        .then((tools) => {
+          tools.forEach((tool) => this.registerTool(tool, "mcp"));
+        })
+        .catch((error) => {
+          console.error("Failed to initialize MCP servers:", error);
+        });
     }
   }
 
@@ -98,7 +114,7 @@ export class OpenAIRealtimeProvider implements RealtimeProvider {
       this.dataChannel = dataChannel;
 
       dataChannel.onopen = () => {
-        this.configureSession();
+        void this.configureSession();
       };
       dataChannel.onmessage = (event) => {
         this.handleDataChannelMessage(event);
@@ -247,15 +263,43 @@ export class OpenAIRealtimeProvider implements RealtimeProvider {
    * Register a function/tool
    */
   registerFunction(tool: RealtimeTool): void {
+    this.registerTool(tool, "manual");
+  }
+
+  private registerTool(tool: RealtimeTool, origin: "manual" | "mcp"): void {
     this.toolExecutor.register(tool.name, tool.execute);
+    const target = origin === "manual" ? this.manualTools : this.mcpTools;
+    const existingIndex = target.findIndex((existing) => existing.name === tool.name);
+
+    if (existingIndex >= 0) {
+      target[existingIndex] = tool;
+    } else {
+      target.push(tool);
+    }
+  }
+
+  private getAllRegisteredTools(): RealtimeTool[] {
+    const combined = new Map<string, RealtimeTool>();
+    [...this.manualTools, ...this.mcpTools].forEach((tool) => {
+      combined.set(tool.name, tool);
+    });
+    return Array.from(combined.values());
   }
 
   /**
    * Configure the OpenAI session
    */
-  private configureSession(): void {
+  private async configureSession(): Promise<void> {
     if (!this.dataChannel) return;
 
+    if (this.mcpInitialization) {
+      try {
+        await this.mcpInitialization;
+      } catch (error) {
+        console.error("Failed to initialize MCP tools:", error);
+      }
+    }
+
     const sessionConfig: any = {
       modalities: ["text", "audio"],
       input_audio_transcription: {
@@ -275,14 +319,16 @@ export class OpenAIRealtimeProvider implements RealtimeProvider {
       },
     };
 
+    const tools = this.getAllRegisteredTools();
+
     // Only add tools and tool_choice if tools are provided
-    if (this.config.tools && this.config.tools.length > 0) {
-      sessionConfig.tools = this.config.tools.map((tool) => {
+    if (tools.length > 0) {
+      sessionConfig.tools = tools.map((tool) => {
         // Build parameters object, removing the 'required' field from each property
         const properties: any = {};
         const requiredFields: string[] = [];
 
-        Object.entries(tool.parameters).forEach(
+        Object.entries(tool.parameters || {}).forEach(
           ([key, param]: [string, any]) => {
             // Extract 'required' flag before adding to properties
             const { required, ...paramSchema } = param;