@copilotkit/runtime 1.8.5-next.2 → 1.8.5-next.4

package/dist/lib/integrations/node-http/index.mjs

@@ -1,7 +1,7 @@
 import {
   copilotRuntimeNodeHttpEndpoint
-} from "../../../chunk-A4MGCX6X.mjs";
-import "../../../chunk-FZJAYGIR.mjs";
+} from "../../../chunk-PKO7BUPS.mjs";
+import "../../../chunk-DNI7KA7Y.mjs";
 import "../../../chunk-5BIEM2UU.mjs";
 import "../../../chunk-RTFJTJMA.mjs";
 import "../../../chunk-2OZAGFV3.mjs";

package/dist/service-adapters/index.mjs

@@ -10,7 +10,7 @@ import {
   OpenAIAssistantAdapter,
   RemoteChain,
   UnifyAdapter
-} from "../chunk-FZJAYGIR.mjs";
+} from "../chunk-DNI7KA7Y.mjs";
 import "../chunk-FHD4JECV.mjs";
 export {
   AnthropicAdapter,

package/dist/{copilot-runtime-9347bd66.d.ts → shared-86ec42e7.d.ts}

@@ -1,52 +1,11 @@
-import { Parameter, Action } from '@copilotkit/shared';
-import { b as CopilotServiceAdapter, R as RemoteChainParameters, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, f as RuntimeEventSource, g as ExtensionsResponse } from './langserve-6f7af8d3.js';
-import { M as MessageInput, a as Message } from './index-5bec5424.js';
 import * as graphql from 'graphql';
 import * as pino from 'pino';
 import { YogaInitialContext, createYoga } from 'graphql-yoga';
+import { Parameter, Action } from '@copilotkit/shared';
+import { b as CopilotServiceAdapter, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, R as RemoteChainParameters, f as RuntimeEventSource, g as ExtensionsResponse } from './langserve-6f7af8d3.js';
+import { M as MessageInput, a as Message } from './index-5bec5424.js';
 import { CopilotCloudOptions } from './lib/cloud/index.js';
 
-type LogLevel = "debug" | "info" | "warn" | "error";
-type CopilotRuntimeLogger = ReturnType<typeof createLogger>;
-declare function createLogger(options?: {
-    level?: LogLevel;
-    component?: string;
-}): pino.Logger<never>;
-
-declare const logger: pino.Logger<never>;
-declare const addCustomHeaderPlugin: {
-    onResponse({ response }: {
-        response: any;
-    }): void;
-};
-type AnyPrimitive = string | boolean | number | null;
-type CopilotRequestContextProperties = Record<string, AnyPrimitive | Record<string, AnyPrimitive>>;
-type GraphQLContext = YogaInitialContext & {
-    _copilotkit: CreateCopilotRuntimeServerOptions;
-    properties: CopilotRequestContextProperties;
-    logger: typeof logger;
-};
-interface CreateCopilotRuntimeServerOptions {
-    runtime: CopilotRuntime<any>;
-    serviceAdapter: CopilotServiceAdapter;
-    endpoint: string;
-    baseUrl?: string;
-    cloud?: CopilotCloudOptions;
-    properties?: CopilotRequestContextProperties;
-    logLevel?: LogLevel;
-}
-declare function createContext(initialContext: YogaInitialContext, copilotKitContext: CreateCopilotRuntimeServerOptions, contextLogger: typeof logger, properties?: CopilotRequestContextProperties): Promise<Partial<GraphQLContext>>;
-declare function buildSchema(options?: {
-    emitSchemaFile?: string;
-}): graphql.GraphQLSchema;
-type CommonConfig = {
-    logging: typeof logger;
-    schema: ReturnType<typeof buildSchema>;
-    plugins: Parameters<typeof createYoga>[0]["plugins"];
-    context: (ctx: YogaInitialContext) => Promise<Partial<GraphQLContext>>;
-};
-declare function getCommonConfig(options: CreateCopilotRuntimeServerOptions): CommonConfig;
-
 declare enum MetaEventName {
     LangGraphInterruptEvent = "LangGraphInterruptEvent",
     CopilotKitLangGraphInterruptEvent = "CopilotKitLangGraphInterruptEvent"
@@ -167,6 +126,53 @@ interface CopilotObservabilityConfig {
     hooks: CopilotObservabilityHooks;
 }
 
+/**
+ * Represents a tool provided by an MCP server.
+ */
+interface MCPTool {
+    description?: string;
+    /** Schema defining parameters, mirroring the MCP structure. */
+    schema?: {
+        parameters?: {
+            properties?: Record<string, any>;
+            required?: string[];
+        };
+    };
+    /** The function to call to execute the tool on the MCP server. */
+    execute(options: {
+        params: any;
+    }): Promise<any>;
+}
+/**
+ * Defines the contract for *any* MCP client implementation the user might provide.
+ */
+interface MCPClient {
+    /** A method that returns a map of tool names to MCPTool objects available from the connected MCP server. */
+    tools(): Promise<Record<string, MCPTool>>;
+    /** An optional method for cleanup if the underlying client requires explicit disconnection. */
+    close?(): Promise<void>;
+}
+/**
+ * Configuration for connecting to an MCP endpoint.
+ */
+interface MCPEndpointConfig {
+    endpoint: string;
+    apiKey?: string;
+}
+/**
+ * Extracts CopilotKit-compatible parameters from an MCP tool schema.
+ * @param toolSchema The schema object from an MCPTool.
+ * @returns An array of Parameter objects.
+ */
+declare function extractParametersFromSchema(toolSchema?: MCPTool["schema"]): Parameter[];
+/**
+ * Converts a map of MCPTools into an array of CopilotKit Actions.
+ * @param mcpTools A record mapping tool names to MCPTool objects.
+ * @param mcpEndpoint The endpoint URL from which these tools were fetched.
+ * @returns An array of Action<any> objects.
+ */
+declare function convertMCPToolsToActions(mcpTools: Record<string, MCPTool>, mcpEndpoint: string): Action<any>[];
+
 /**
  * <Callout type="info">
  *   This is the reference for the `CopilotRuntime` class. For more information and example code snippets, please see [Concept: Copilot Runtime](/concepts/copilot-runtime).
@@ -181,6 +187,7 @@ interface CopilotObservabilityConfig {
  * ```
  */
 
+type CreateMCPClientFunction = (config: MCPEndpointConfig) => Promise<MCPClient>;
 interface CopilotRuntimeRequest {
     serviceAdapter: CopilotServiceAdapter;
     messages: MessageInput[];
@@ -290,6 +297,39 @@ interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []> {
      * ```
      */
     observability_c?: CopilotObservabilityConfig;
+    /**
+     * Configuration for connecting to Model Context Protocol (MCP) servers.
+     * Allows fetching and using tools defined on external MCP-compliant servers.
+     * Requires providing the `createMCPClient` function during instantiation.
+     * @experimental
+     */
+    mcpEndpoints?: MCPEndpointConfig[];
+    /**
+     * A function that creates an MCP client instance for a given endpoint configuration.
+     * This function is responsible for using the appropriate MCP client library
+     * (e.g., `@copilotkit/runtime`, `ai`) to establish a connection.
+     * Required if `mcpEndpoints` is provided.
+     *
+     * ```typescript
+     * import { experimental_createMCPClient } from "ai"; // Import from vercel ai library
+     * // ...
+     * const runtime = new CopilotRuntime({
+     *   mcpEndpoints: [{ endpoint: "..." }],
+     *   async createMCPClient(config) {
+     *     return await experimental_createMCPClient({
+     *       transport: {
+     *         type: "sse",
+     *         url: config.endpoint,
+     *         headers: config.apiKey
+     *           ? { Authorization: `Bearer ${config.apiKey}` }
+     *           : undefined,
+     *       },
+     *     });
+     *   }
+     * });
+     * ```
+     */
+    createMCPClient?: CreateMCPClientFunction;
 }
 declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     actions: ActionsConfiguration<T>;
@@ -300,7 +340,11 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private delegateAgentProcessingToServiceAdapter;
     private observability?;
     private availableAgents;
+    private readonly mcpEndpointsConfig?;
+    private mcpActionCache;
+    private readonly createMCPClientImpl?;
     constructor(params?: CopilotRuntimeConstructorParams<T>);
+    private injectMCPToolInstructions;
     processRuntimeRequest(request: CopilotRuntimeRequest): Promise<CopilotRuntimeResponse>;
     discoverAgentsFromEndpoints(graphqlContext: GraphQLContext): Promise<AgentWithEndpoint[]>;
     loadAgentState(graphqlContext: GraphQLContext, threadId: string, agentName: string): Promise<LoadAgentStateResponse>;
@@ -313,4 +357,45 @@ declare function copilotKitEndpoint(config: Omit<CopilotKitEndpoint, "type">): C
 declare function langGraphPlatformEndpoint(config: Omit<LangGraphPlatformEndpoint, "type">): LangGraphPlatformEndpoint;
 declare function resolveEndpointType(endpoint: EndpointDefinition): EndpointType;
 
-export { CopilotRuntimeConstructorParams as C, GraphQLContext as G, LogLevel as L, CopilotRuntime as a, addCustomHeaderPlugin as b, copilotKitEndpoint as c, CopilotRequestContextProperties as d, CreateCopilotRuntimeServerOptions as e, flattenToolCallsNoDuplicates as f, createContext as g, buildSchema as h, CommonConfig as i, getCommonConfig as j, CopilotRuntimeLogger as k, langGraphPlatformEndpoint as l, createLogger as m, resolveEndpointType as r };
+type LogLevel = "debug" | "info" | "warn" | "error";
+type CopilotRuntimeLogger = ReturnType<typeof createLogger>;
+declare function createLogger(options?: {
+    level?: LogLevel;
+    component?: string;
+}): pino.Logger<never>;
+
+declare const logger: pino.Logger<never>;
+declare const addCustomHeaderPlugin: {
+    onResponse({ response }: {
+        response: any;
+    }): void;
+};
+type AnyPrimitive = string | boolean | number | null;
+type CopilotRequestContextProperties = Record<string, AnyPrimitive | Record<string, AnyPrimitive>>;
+type GraphQLContext = YogaInitialContext & {
+    _copilotkit: CreateCopilotRuntimeServerOptions;
+    properties: CopilotRequestContextProperties;
+    logger: typeof logger;
+};
+interface CreateCopilotRuntimeServerOptions {
+    runtime: CopilotRuntime<any>;
+    serviceAdapter: CopilotServiceAdapter;
+    endpoint: string;
+    baseUrl?: string;
+    cloud?: CopilotCloudOptions;
+    properties?: CopilotRequestContextProperties;
+    logLevel?: LogLevel;
+}
+declare function createContext(initialContext: YogaInitialContext, copilotKitContext: CreateCopilotRuntimeServerOptions, contextLogger: typeof logger, properties?: CopilotRequestContextProperties): Promise<Partial<GraphQLContext>>;
+declare function buildSchema(options?: {
+    emitSchemaFile?: string;
+}): graphql.GraphQLSchema;
+type CommonConfig = {
+    logging: typeof logger;
+    schema: ReturnType<typeof buildSchema>;
+    plugins: Parameters<typeof createYoga>[0]["plugins"];
+    context: (ctx: YogaInitialContext) => Promise<Partial<GraphQLContext>>;
+};
+declare function getCommonConfig(options: CreateCopilotRuntimeServerOptions): CommonConfig;
+
+export { CopilotRequestContextProperties as C, GraphQLContext as G, LogLevel as L, MCPTool as M, addCustomHeaderPlugin as a, CreateCopilotRuntimeServerOptions as b, createContext as c, buildSchema as d, CommonConfig as e, CopilotRuntimeLogger as f, getCommonConfig as g, createLogger as h, CopilotRuntimeRequest as i, CopilotRuntimeConstructorParams as j, CopilotRuntime as k, flattenToolCallsNoDuplicates as l, copilotKitEndpoint as m, langGraphPlatformEndpoint as n, MCPClient as o, MCPEndpointConfig as p, extractParametersFromSchema as q, resolveEndpointType as r, convertMCPToolsToActions as s };

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.8.5-next.2",
+  "version": "1.8.5-next.4",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -59,7 +59,7 @@
     "rxjs": "^7.8.1",
     "type-graphql": "2.0.0-rc.1",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.8.5-next.2"
+    "@copilotkit/shared": "1.8.5-next.4"
   },
   "keywords": [
     "copilotkit",

package/src/lib/index.ts

@@ -1,4 +1,3 @@
-export * from "./runtime/copilot-runtime";
 export * from "../service-adapters/openai/openai-adapter";
 export * from "../service-adapters/langchain/langchain-adapter";
 export * from "../service-adapters/google/google-genai-adapter";
@@ -7,3 +6,5 @@ export * from "../service-adapters/unify/unify-adapter";
 export * from "../service-adapters/groq/groq-adapter";
 export * from "./integrations";
 export * from "./logger";
+export * from "./runtime/copilot-runtime";
+export * from "./runtime/mcp-tools-utils";

package/src/lib/runtime/copilot-runtime.ts

@@ -67,8 +67,15 @@ import {
   LLMResponseData,
   LLMErrorData,
 } from "../observability";
+import { MessageRole } from "../../graphql/types/enums";
 
-interface CopilotRuntimeRequest {
+// +++ MCP Imports +++
+import { MCPClient, MCPEndpointConfig, convertMCPToolsToActions } from "./mcp-tools-utils";
+// Define the function type alias here or import if defined elsewhere
+type CreateMCPClientFunction = (config: MCPEndpointConfig) => Promise<MCPClient>;
+// --- MCP Imports ---
+
+export interface CopilotRuntimeRequest {
   serviceAdapter: CopilotServiceAdapter;
   messages: MessageInput[];
   actions: ActionInput[];
@@ -208,6 +215,41 @@ export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []
    * ```
    */
   observability_c?: CopilotObservabilityConfig;
+
+  /**
+   * Configuration for connecting to Model Context Protocol (MCP) servers.
+   * Allows fetching and using tools defined on external MCP-compliant servers.
+   * Requires providing the `createMCPClient` function during instantiation.
+   * @experimental
+   */
+  mcpEndpoints?: MCPEndpointConfig[];
+
+  /**
+   * A function that creates an MCP client instance for a given endpoint configuration.
+   * This function is responsible for using the appropriate MCP client library
+   * (e.g., `@copilotkit/runtime`, `ai`) to establish a connection.
+   * Required if `mcpEndpoints` is provided.
+   *
+   * ```typescript
+   * import { experimental_createMCPClient } from "ai"; // Import from vercel ai library
+   * // ...
+   * const runtime = new CopilotRuntime({
+   *   mcpEndpoints: [{ endpoint: "..." }],
+   *   async createMCPClient(config) {
+   *     return await experimental_createMCPClient({
+   *       transport: {
+   *         type: "sse",
+   *         url: config.endpoint,
+   *         headers: config.apiKey
+   *           ? { Authorization: `Bearer ${config.apiKey}` }
+   *           : undefined,
+   *       },
+   *     });
+   *   }
+   * });
+   * ```
+   */
+  createMCPClient?: CreateMCPClientFunction;
 }
 
 export class CopilotRuntime<const T extends Parameter[] | [] = []> {
@@ -220,6 +262,15 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
   private observability?: CopilotObservabilityConfig;
   private availableAgents: Pick<AgentWithEndpoint, "name" | "id">[];
 
+  // +++ MCP Properties +++
+  private readonly mcpEndpointsConfig?: MCPEndpointConfig[];
+  private mcpActionCache = new Map<string, Action<any>[]>();
+  // --- MCP Properties ---
+
+  // +++ MCP Client Factory +++
+  private readonly createMCPClientImpl?: CreateMCPClientFunction;
+  // --- MCP Client Factory ---
+
   constructor(params?: CopilotRuntimeConstructorParams<T>) {
     if (
       params?.actions &&
@@ -243,7 +294,98 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
     this.delegateAgentProcessingToServiceAdapter =
       params?.delegateAgentProcessingToServiceAdapter || false;
     this.observability = params?.observability_c;
+
+    // +++ MCP Initialization +++
+    this.mcpEndpointsConfig = params?.mcpEndpoints;
+    this.createMCPClientImpl = params?.createMCPClient;
+
+    // Validate: If mcpEndpoints are provided, createMCPClient must also be provided
+    if (
+      this.mcpEndpointsConfig &&
+      this.mcpEndpointsConfig.length > 0 &&
+      !this.createMCPClientImpl
+    ) {
+      throw new CopilotKitMisuseError({
+        message:
+          "MCP Integration Error: `mcpEndpoints` were provided, but the `createMCPClient` function was not passed to the CopilotRuntime constructor. " +
+          "Please provide an implementation for `createMCPClient`.",
+      });
+    }
+
+    // Warning if actions are defined alongside LangGraph platform (potentially MCP too?)
+    if (
+      params?.actions &&
+      (params?.remoteEndpoints?.some((e) => e.type === EndpointType.LangGraphPlatform) ||
+        this.mcpEndpointsConfig?.length)
+    ) {
+      console.warn(
+        "Local 'actions' defined in CopilotRuntime might not be available to remote agents (LangGraph, MCP). Consider defining actions closer to the agent implementation if needed.",
+      );
+    }
+  }
+
+  // +++ MCP Instruction Injection Method +++
+  private injectMCPToolInstructions(
+    messages: MessageInput[],
+    currentActions: Action<any>[],
+  ): MessageInput[] {
+    // Filter the *passed-in* actions for MCP tools
+    const mcpActionsForRequest = currentActions.filter((action) => (action as any)._isMCPTool);
+
+    if (!mcpActionsForRequest || mcpActionsForRequest.length === 0) {
+      return messages; // No MCP tools for this specific request
+    }
+
+    // Filter only MCP actions and format instructions
+    const mcpToolInstructions = mcpActionsForRequest
+      .map((action) => {
+        const paramsString =
+          action.parameters && action.parameters.length > 0
+            ? ` Parameters: ${action.parameters
+                .map((p) => `${p.name}${p.required ? "*" : ""}(${p.type})`)
+                .join(", ")}`
+            : "";
+        return `- ${action.name}:${paramsString} ${action.description || ""}`;
+      })
+      .join("\n");
+
+    if (!mcpToolInstructions) {
+      return messages; // No MCP tools to describe
+    }
+
+    const instructions =
+      "You have access to the following tools provided by external Model Context Protocol (MCP) servers:\n" +
+      mcpToolInstructions +
+      "\nUse them when appropriate to fulfill the user's request.";
+
+    const systemMessageIndex = messages.findIndex((msg) => msg.textMessage?.role === "system");
+
+    const newMessages = [...messages]; // Create a mutable copy
+
+    if (systemMessageIndex !== -1) {
+      const existingMsg = newMessages[systemMessageIndex];
+      if (existingMsg.textMessage) {
+        existingMsg.textMessage.content =
+          (existingMsg.textMessage.content ? existingMsg.textMessage.content + "\n\n" : "") +
+          instructions;
+      }
+    } else {
+      newMessages.unshift({
+        id: randomId(),
+        createdAt: new Date(),
+        textMessage: {
+          role: MessageRole.system,
+          content: instructions,
+        },
+        actionExecutionMessage: undefined,
+        resultMessage: undefined,
+        agentStateMessage: undefined,
+      });
+    }
+
+    return newMessages;
   }
+  // --- MCP Instruction Injection Method ---
 
   async processRuntimeRequest(request: CopilotRuntimeRequest): Promise<CopilotRuntimeResponse> {
     const {
@@ -280,9 +422,20 @@ please use an LLM adapter instead.`,
         });
       }
 
-      const messages = rawMessages.filter((message) => !message.agentStateMessage);
-      const inputMessages = convertGqlInputToMessages(messages);
+      // +++ Get Server Side Actions (including dynamic MCP) EARLY +++
       const serverSideActions = await this.getServerSideActions(request);
+      // --- Get Server Side Actions (including dynamic MCP) EARLY ---
+
+      // Filter raw messages *before* injection
+      const filteredRawMessages = rawMessages.filter((message) => !message.agentStateMessage);
+
+      // +++ Inject MCP Instructions based on current actions +++
+      const messagesWithInjectedInstructions = this.injectMCPToolInstructions(
+        filteredRawMessages,
+        serverSideActions,
+      );
+      const inputMessages = convertGqlInputToMessages(messagesWithInjectedInstructions);
+      // --- Inject MCP Instructions based on current actions ---
 
       // Log LLM request if logging is enabled
       if (this.observability?.enabled && publicApiKey) {
@@ -913,10 +1066,11 @@ please use an LLM adapter instead.`,
   }
 
   private async getServerSideActions(request: CopilotRuntimeRequest): Promise<Action<any>[]> {
-    const { messages: rawMessages, graphqlContext, agentStates, url } = request;
+    const { graphqlContext, messages: rawMessages, agentStates, url } = request;
+
+    // --- Standard Action Fetching (unchanged) ---
     const inputMessages = convertGqlInputToMessages(rawMessages);
     const langserveFunctions: Action<any>[] = [];
-
     for (const chainPromise of this.langserve) {
       try {
         const chain = await chainPromise;
@@ -927,11 +1081,7 @@ please use an LLM adapter instead.`,
     }
 
     const remoteEndpointDefinitions = this.remoteEndpointDefinitions.map(
-      (endpoint) =>
-        ({
-          ...endpoint,
-          type: resolveEndpointType(endpoint),
-        }) as EndpointDefinition,
+      (endpoint) => ({ ...endpoint, type: resolveEndpointType(endpoint) }) as EndpointDefinition,
     );
 
     const remoteActions = await setupRemoteActions({
@@ -946,8 +1096,65 @@ please use an LLM adapter instead.`,
       typeof this.actions === "function"
         ? this.actions({ properties: graphqlContext.properties, url })
         : this.actions;
+    // --- Standard Action Fetching (unchanged) ---
+
+    // +++ Dynamic MCP Action Fetching +++
+    const requestSpecificMCPActions: Action<any>[] = [];
+    if (this.createMCPClientImpl) {
+      // 1. Determine effective MCP endpoints for this request
+      const baseEndpoints = this.mcpEndpointsConfig || [];
+      // Assuming frontend passes config via properties.mcpEndpoints
+      const requestEndpoints = (graphqlContext.properties?.mcpEndpoints ||
+        []) as MCPEndpointConfig[];
+
+      // Merge and deduplicate endpoints based on URL
+      const effectiveEndpointsMap = new Map<string, MCPEndpointConfig>();
+      [...baseEndpoints, ...requestEndpoints].forEach((ep) => {
+        if (ep && ep.endpoint) {
+          // Basic validation
+          effectiveEndpointsMap.set(ep.endpoint, ep);
+        }
+      });
+      const effectiveEndpoints = Array.from(effectiveEndpointsMap.values());
 
-    return [...configuredActions, ...langserveFunctions, ...remoteActions];
+      // 2. Fetch/Cache actions for effective endpoints
+      for (const config of effectiveEndpoints) {
+        const endpointUrl = config.endpoint;
+        let actionsForEndpoint: Action<any>[] | undefined = this.mcpActionCache.get(endpointUrl);
+
+        if (!actionsForEndpoint) {
+          // Not cached, fetch now
+          let client: MCPClient | null = null;
+          try {
+            console.log(`MCP: Cache miss. Fetching tools for endpoint: ${endpointUrl}`);
+            client = await this.createMCPClientImpl(config);
+            const tools = await client.tools();
+            actionsForEndpoint = convertMCPToolsToActions(tools, endpointUrl);
+            this.mcpActionCache.set(endpointUrl, actionsForEndpoint); // Store in cache
+            console.log(
+              `MCP: Fetched and cached ${actionsForEndpoint.length} tools for ${endpointUrl}`,
+            );
+          } catch (error) {
+            console.error(
+              `MCP: Failed to fetch tools from endpoint ${endpointUrl}. Skipping. Error:`,
+              error,
+            );
+            actionsForEndpoint = []; // Assign empty array on error to prevent re-fetching constantly
+            this.mcpActionCache.set(endpointUrl, actionsForEndpoint); // Cache the failure (empty array)
+          }
+        }
+        requestSpecificMCPActions.push(...(actionsForEndpoint || []));
+      }
+    }
+    // --- Dynamic MCP Action Fetching ---
+
+    // Combine all action sources, including the dynamically fetched MCP actions
+    return [
+      ...configuredActions,
+      ...langserveFunctions,
+      ...remoteActions,
+      ...requestSpecificMCPActions,
+    ];
   }
 
   // Add helper method to detect provider

package/src/lib/runtime/mcp-tools-utils.ts

@@ -0,0 +1,117 @@
+import { Action, Parameter } from "@copilotkit/shared";
+
+/**
+ * Represents a tool provided by an MCP server.
+ */
+export interface MCPTool {
+  description?: string;
+  /** Schema defining parameters, mirroring the MCP structure. */
+  schema?: {
+    parameters?: {
+      properties?: Record<string, any>;
+      required?: string[];
+    };
+  };
+  /** The function to call to execute the tool on the MCP server. */
+  execute(options: { params: any }): Promise<any>;
+}
+
+/**
+ * Defines the contract for *any* MCP client implementation the user might provide.
+ */
+export interface MCPClient {
+  /** A method that returns a map of tool names to MCPTool objects available from the connected MCP server. */
+  tools(): Promise<Record<string, MCPTool>>;
+  /** An optional method for cleanup if the underlying client requires explicit disconnection. */
+  close?(): Promise<void>;
+}
+
+/**
+ * Configuration for connecting to an MCP endpoint.
+ */
+export interface MCPEndpointConfig {
+  endpoint: string;
+  apiKey?: string;
+}
+
+/**
+ * Extracts CopilotKit-compatible parameters from an MCP tool schema.
+ * @param toolSchema The schema object from an MCPTool.
+ * @returns An array of Parameter objects.
+ */
+export function extractParametersFromSchema(toolSchema?: MCPTool["schema"]): Parameter[] {
+  const parameters: Parameter[] = [];
+  const properties = toolSchema?.parameters?.properties;
+  const requiredParams = new Set(toolSchema?.parameters?.required || []);
+
+  if (!properties) {
+    return parameters;
+  }
+
+  for (const paramName in properties) {
+    if (Object.prototype.hasOwnProperty.call(properties, paramName)) {
+      const paramDef = properties[paramName];
+      parameters.push({
+        name: paramName,
+        // Infer type, default to string. MCP schemas might have more complex types.
+        // This might need refinement based on common MCP schema practices.
+        type: paramDef.type || "string",
+        description: paramDef.description,
+        required: requiredParams.has(paramName),
+        // Attributes might not directly map, handle if necessary
+        // attributes: paramDef.attributes || undefined,
+      });
+    }
+  }
+
+  return parameters;
+}
+
+/**
+ * Converts a map of MCPTools into an array of CopilotKit Actions.
+ * @param mcpTools A record mapping tool names to MCPTool objects.
+ * @param mcpEndpoint The endpoint URL from which these tools were fetched.
+ * @returns An array of Action<any> objects.
+ */
+export function convertMCPToolsToActions(
+  mcpTools: Record<string, MCPTool>,
+  mcpEndpoint: string,
+): Action<any>[] {
+  const actions: Action<any>[] = [];
+
+  for (const [toolName, tool] of Object.entries(mcpTools)) {
+    const parameters = extractParametersFromSchema(tool.schema);
+
+    const handler = async (params: any): Promise<any> => {
+      try {
+        const result = await tool.execute({ params });
+        // Ensure the result is a string or stringify it, as required by many LLMs.
+        // This might need adjustment depending on how different LLMs handle tool results.
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } catch (error) {
+        console.error(
+          `Error executing MCP tool '${toolName}' from endpoint ${mcpEndpoint}:`,
+          error,
+        );
+        // Re-throw or format the error for the LLM
+        throw new Error(
+          `Execution failed for MCP tool '${toolName}': ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    };
+
+    actions.push({
+      name: toolName,
+      description: tool.description || `MCP tool: ${toolName} (from ${mcpEndpoint})`,
+      parameters: parameters,
+      handler: handler,
+      // Add metadata for easier identification/debugging
+      _isMCPTool: true,
+      _mcpEndpoint: mcpEndpoint,
+    } as Action<any> & { _isMCPTool: boolean; _mcpEndpoint: string }); // Type assertion for metadata
+  }
+
+  return actions;
+}