Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

16.9 KB
Raw Blame
import { Composio as ComposioClient } from '@composio/client';
import { telemetry } from '../telemetry/Telemetry';
import {
  MCPConfigCreationParams,
  MCPConfigCreationParamsSchema,
  MCPConfigCreateResponse,
  MCPConfigResponseSchema,
  MCPServerInstance,
  MCPGetInstanceParams,
  MCPGetInstanceParamsSchema,
  MCPListResponse,
  MCPListParams,
  MCPListParamsSchema,
  MCPListResponseSchema,
  MCPItemSchema,
  MCPItem,
  MCPUpdateParams,
  MCPUpdateParamsSchema,
} from '../types/mcp.experimental.types';
import { MCPServerInstanceSchema } from '../types/mcp.experimental.types';
import { ValidationError } from '../errors/ValidationErrors';
import { transform } from '../utils/transform';
import { McpUpdateResponse } from '@composio/client/resources.js';
import { McpRetrieveResponse } from '@composio/client/resources';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';

function transformMCPItemResponse(response: McpUpdateResponse | McpRetrieveResponse): MCPItem {
  return transform(response)
    .with(MCPItemSchema)
    .using(raw => ({
      name: raw.name,
      allowedTools: raw.allowed_tools,
      id: raw.id,
      authConfigIds: raw.auth_config_ids,
      commands: raw.commands,
      MCPUrl: raw.mcp_url,
      toolkitIcons: raw.toolkit_icons,
      serverInstanceCount: raw.server_instance_count,
      toolkits: raw.toolkits,
    }));
}
/**
 * MCP (Model Control Protocol) class
 * Handles MCP server operations.
 * When `config.experimental.mcp` is enabled, this class augments the features of `composio.mcp`.
 *
 * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`
 * returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now
 * opt-in per session; the standalone `composio.mcp` server-management API is kept only for
 * backwards compatibility. Prefer the session MCP endpoint; do not generate new code against
 * `composio.mcp`. See https://docs.composio.dev/docs/sessions-via-mcp
 */
export class MCP {
  client: ComposioClient;

  constructor(client: ComposioClient) {
    this.client = client;
    telemetry.instrument(this, 'MCP');
  }

  /**
   * Create a new MCP configuration.
   * @param {Object} params - Parameters for creating the MCP configuration
   * @param {Array} params.authConfig - Array of auth configurations with id and allowed tools
   * @param {Object} params.options - Configuration options
   * @param {string} params.options.name - Unique name for the MCP configuration
   * @param {boolean} [params.options.manuallyManageConnections] - Whether to use chat-based authentication or manually connect accounts
   * @returns {Promise<McpServerCreateResponse<T>>} Created server details with instance getter
   *
   * @example
   * ```typescript
   * const server = await composio.mcpConfig.create("personal-mcp-server", {
   *   toolkits: ["github", "slack"],
   *   allowedTools: ["GMAIL_FETCH_EMAILS", "SLACK_SEND_MESSAGE"],
   *   manuallyManageConnections: false
   *  }
   * });
   *
   * const server = await composio.mcpConfig.create("personal-mcp-server", {
   *   toolkits: [{ toolkit: "gmail", authConfigId: "ac_243434343" }],
   *   allowedTools: ["GMAIL_FETCH_EMAILS"],
   *   manuallyManageConnections: false
   *  }
   * });
   * ```
   */
  async create(
    name: string,
    mcpConfig: MCPConfigCreationParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<MCPConfigCreateResponse> {
    const config = MCPConfigCreationParamsSchema.safeParse(mcpConfig);
    if (config.error) {
      throw new ValidationError('Invalid parameters passed to create mcp config', {
        cause: config.error,
      });
    }

    const toolkits: string[] = [];
    const auth_config_ids: string[] = [];
    const custom_tools: string[] = config.data.allowedTools ?? [];

    // extract all the toolkits, authconfigs, and allowed tools to separate slugs
    config.data.toolkits.forEach(toolkit => {
      if (typeof toolkit === 'string') {
        toolkits.push(toolkit);
      } else if (toolkit.toolkit) {
        toolkits.push(toolkit.toolkit);
      } else if (toolkit.authConfigId) {
        auth_config_ids.push(toolkit.authConfigId);
      }
    });

    const createBody = {
      name,
      toolkits,
      auth_config_ids,
      custom_tools,
      // if manually manage account is set to true, disable composio account management tools
      managed_auth_via_composio: config.data.manuallyManageConnections ? false : true,
    };
    const server = await withCancellation(
      () => this.client.mcp.custom.create(createBody, requestOptions),
      requestOptions?.signal
    );

    const camelCaseServer = transform(server)
      .with(MCPConfigResponseSchema)
      .using(raw => ({
        name: raw.name,
        allowedTools: raw.allowed_tools,
        id: raw.id,
        authConfigIds: raw.auth_config_ids,
        commands: raw.commands,
        MCPUrl: raw.mcp_url,
      }));

    return {
      ...camelCaseServer,
      generate: async (userId: string): Promise<MCPServerInstance> => {
        return await this.generate(userId, server.id, {
          manuallyManageConnections: config.data.manuallyManageConnections,
        });
      },
    };
  }

  /**
   * List the MCP servers with optional filtering and pagination
   * @param {Object} options - Filtering and pagination options
   * @param {number} [options.page=1] - Page number for pagination (1-based)
   * @param {number} [options.limit=10] - Maximum number of items to return per page
   * @param {string[]} [options.toolkits=[]] - Array of toolkit names to filter by
   * @param {string[]} [options.authConfigs=[]] - Array of auth configuration IDs to filter by
   * @param {string} [options.name] - Filter by MCP server name (partial match)
   * @returns {Promise<MCPListResponse>} Paginated list of MCP servers with metadata
   *
   * @example
   * ```typescript
   * // List all MCP servers
   * const allServers = await composio.experimental.mcp.list({});
   *
   * // List with pagination
   * const pagedServers = await composio.experimental.mcp.list({
   *   page: 2,
   *   limit: 5
   * });
   *
   * // Filter by toolkit
   * const githubServers = await composio.experimental.mcp.list({
   *   toolkits: ['github', 'slack']
   * });
   *
   * // Filter by name
   * const namedServers = await composio.experimental.mcp.list({
   *   name: 'personal'
   * });
   * ```
   */
  async list(
    options: MCPListParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<MCPListResponse> {
    const { data: params, error } = MCPListParamsSchema.safeParse(options);
    if (error) {
      throw new ValidationError('Failed to validate list options', {
        cause: error,
      });
    }

    const listParams = {
      page_no: params.page,
      limit: params.limit,
      toolkits: params.toolkits?.length > 0 ? params.toolkits.join(',') : undefined,
      auth_config_ids: params.authConfigs?.length > 0 ? params.authConfigs.join(',') : undefined,
      name: params.name,
    };
    const listResponse = await withCancellation(
      () => this.client.mcp.list(listParams, requestOptions),
      requestOptions?.signal
    );

    const transformedListResponse = transform(listResponse)
      .with(MCPListResponseSchema)
      .using(raw => ({
        currentPage: raw.current_page,
        totalPages: raw.total_pages,
        items: raw.items.map(item => ({
          name: item.name,
          allowedTools: item.allowed_tools,
          id: item.id,
          authConfigIds: item.auth_config_ids,
          commands: item.commands,
          MCPUrl: item.mcp_url,
          toolkitIcons: item.toolkit_icons,
          serverInstanceCount: item.server_instance_count,
          toolkits: item.toolkits,
        })),
      }));

    return transformedListResponse;
  }

  /**
   * Retrieve detailed information about a specific MCP server by its ID
   * @param {string} serverId - The unique identifier of the MCP server to retrieve
   * @returns {Promise<MCPItem>} Complete MCP server details including configuration, tools, and metadata
   *
   * @example
   * ```typescript
   * // Get a specific MCP server by ID
   * const server = await composio.experimental.mcp.get("mcp_12345");
   *
   * console.log(server.name); // "My Personal MCP Server"
   * console.log(server.allowedTools); // ["GITHUB_CREATE_ISSUE", "SLACK_SEND_MESSAGE"]
   * console.log(server.toolkits); // ["github", "slack"]
   * console.log(server.serverInstanceCount); // 3
   *
   * // Access setup commands for different clients
   * console.log(server.commands.claude); // Claude setup command
   * console.log(server.commands.cursor); // Cursor setup command
   * console.log(server.commands.windsurf); // Windsurf setup command
   *
   * // Use the MCP URL for direct connections
   * const mcpUrl = server.MCPUrl;
   * ```
   *
   * @throws {ValidationError} When the server ID is invalid or server not found
   */
  async get(serverId: string, requestOptions?: ComposioRequestOptions): Promise<MCPItem> {
    const response = await withCancellation(
      () => this.client.mcp.retrieve(serverId, requestOptions),
      requestOptions?.signal
    );
    return transformMCPItemResponse(response);
  }

  /**
   * Delete an MCP server configuration permanently
   * @param {string} serverId - The unique identifier of the MCP server to delete
   * @returns {Promise<{id: string; deleted: boolean}>} Confirmation object with server ID and deletion status
   *
   * @example
   * ```typescript
   * // Delete an MCP server by ID
   * const result = await composio.experimental.mcp.delete("mcp_12345");
   *
   * if (result.deleted) {
   *   console.log(`Server ${result.id} has been successfully deleted`);
   * } else {
   *   console.log(`Failed to delete server ${result.id}`);
   * }
   *
   * // Example with error handling
   * try {
   *   const result = await composio.experimental.mcp.delete("mcp_12345");
   *   console.log("Deletion successful:", result);
   * } catch (error) {
   *   console.error("Failed to delete MCP server:", error.message);
   * }
   *
   * // Delete and verify from list
   * await composio.experimental.mcp.delete("mcp_12345");
   * const servers = await composio.experimental.mcp.list({});
   * const serverExists = servers.items.some(server => server.id === "mcp_12345");
   * console.log("Server still exists:", serverExists); // Should be false
   * ```
   *
   * @throws {ValidationError} When the server ID is invalid or server not found
   * @throws {Error} When the server cannot be deleted due to active connections or other constraints
   *
   * @warning This operation is irreversible. Once deleted, the MCP server configuration and all its associated data will be permanently removed.
   */
  async delete(
    serverId: string,
    requestOptions?: ComposioRequestOptions
  ): Promise<{ id: string; deleted: boolean }> {
    return withCancellation(
      () => this.client.mcp.delete(serverId, requestOptions),
      requestOptions?.signal
    );
  }

  /**
   * Update an existing MCP server configuration with new settings
   * @param {string} serverId - The unique identifier of the MCP server to update
   * @param {Object} config - Update configuration parameters
   * @param {string} [config.name] - New name for the MCP server
   * @param {Array} [config.toolkits] - Updated toolkit configurations
   * @param {string} [config.toolkits[].toolkit] - Toolkit identifier (e.g., "github", "slack")
   * @param {string} [config.toolkits[].authConfigId] - Auth configuration ID for the toolkit
   * @param {string[]} [config.toolkits[].allowedTools] - Specific tools to enable for this toolkit
   * @param {boolean} [config.manuallyManageConnections] - Whether to manually manage account connections
   * @returns {Promise<MCPItem>} Updated MCP server configuration with all details
   *
   * @example
   * ```typescript
   * // Update server name only
   * const updatedServer = await composio.experimental.mcp.update("mcp_12345", {
   *   name: "My Updated MCP Server"
   * });
   *
   * // Update toolkits and tools
   * const serverWithNewTools = await composio.experimental.mcp.update("mcp_12345", {
   *   toolkits: [
   *     {
   *       toolkit: "github",
   *       authConfigId: "auth_abc123",
   *       allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS"]
   *     },
   *     {
   *       toolkit: "slack",
   *       authConfigId: "auth_xyz789",
   *       allowedTools: ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"]
   *     }
   *   ]
   * });
   *
   * // Update connection management setting
   * const serverWithManualAuth = await composio.experimental.mcp.update("mcp_12345", {
   *   name: "Manual Auth Server",
   *   manuallyManageConnections: true
   * });
   *
   * // Complete update example
   * const fullyUpdatedServer = await composio.experimental.mcp.update("mcp_12345", {
   *   name: "Production MCP Server",
   *   toolkits: [
   *     {
   *       toolkit: "gmail",
   *       authConfigId: "auth_gmail_prod",
   *     }
   *   ],
   *   allowedTools: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]
   *   manuallyManageConnections: false
   * });
   *
   * console.log("Updated server:", fullyUpdatedServer.name);
   * console.log("New tools:", fullyUpdatedServer.allowedTools);
   * ```
   *
   * @throws {ValidationError} When the update parameters are invalid or malformed
   * @throws {Error} When the server ID doesn't exist or update fails
   *
   * @note Only provided fields will be updated. Omitted fields will retain their current values.
   * @note When updating toolkits, the entire toolkit configuration is replaced, not merged.
   */
  async update(
    serverId: string,
    config: MCPUpdateParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<MCPItem> {
    const { data: params, error } = MCPUpdateParamsSchema.safeParse(config);
    if (error) {
      throw new ValidationError('Failed to validate update params', {
        cause: error,
      });
    }

    const toolkits: string[] = [];
    const auth_config_ids: string[] = [];
    const custom_tools: string[] | undefined = params.allowedTools ?? undefined;

    // extract all the toolkits, authconfigs, and allowed tools to separate slugs
    params.toolkits?.forEach(toolkit => {
      if (typeof toolkit === 'string') {
        toolkits.push(toolkit);
      } else if (toolkit.toolkit) {
        toolkits.push(toolkit.toolkit);
      } else if (toolkit.authConfigId) {
        auth_config_ids.push(toolkit.authConfigId);
      }
    });
    const updateBody = {
      ...{ name: params.name ?? undefined },
      ...(params.toolkits
        ? {
            custom_tools: custom_tools,
            toolkits: toolkits,
            auth_config_ids: auth_config_ids,
          }
        : {}),
      ...{ managed_auth_via_composio: params.manuallyManageConnections ?? undefined },
    };
    const response = await withCancellation(
      () => this.client.mcp.update(serverId, updateBody, requestOptions),
      requestOptions?.signal
    );
    return transformMCPItemResponse(response);
  }

  /**
   * Get server URLs for an existing MCP server.
   * The response is wrapped according to the provider's specifications.
   *
   * @example
   * ```typescript
   * import { Composio } from "@composio/code";
   *
   * const composio = new Composio();
   * const mcp = await composio.experimental.mcp.generate("default", "<mcp_config_id>");
   * ```
   *
   * @param userId {string} external user id from your database for whom you want the server for
   * @param mcpConfigId {string} config id of the MCPConfig for which you want to create a server for
   * @param options {object} additional options
   * @param options.isChatAuth {boolean} Authenticate the users via chat when they use the MCP Server
   */
  async generate(
    userId: string,
    mcpConfigId: string,
    options?: MCPGetInstanceParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<MCPServerInstance> {
    const server = await withCancellation(
      () => this.client.mcp.retrieve(mcpConfigId, requestOptions),
      requestOptions?.signal
    );
    const params = MCPGetInstanceParamsSchema.safeParse(
      options ?? { manuallyManageConnections: false }
    );
    if (params.error) {
      throw new ValidationError('Invalid params passed for Get Instance Params', {
        cause: params.error,
      });
    }

    const urlBody = {
      mcp_server_id: mcpConfigId,
      user_ids: [userId],
      managed_auth_by_composio: options?.manuallyManageConnections ? false : true,
    };
    const urlResponse = await withCancellation(
      () => this.client.mcp.generate.url(urlBody, requestOptions),
      requestOptions?.signal
    );

    const userIdsURL = urlResponse.user_ids_url[0];
    const serverInstance = MCPServerInstanceSchema.safeParse({
      id: server.id,
      name: server.name,
      type: 'streamable_http' as const,
      url: userIdsURL,
      userId: userId,
      allowedTools: server.allowed_tools,
      authConfigs: server.auth_config_ids,
    });

    if (serverInstance.error) {
      throw new ValidationError('Failed to parse MCP server instance', {
        cause: serverInstance.error,
      });
    }

    return serverInstance.data;
  }
}