composiohq--composio/ts/docs/api/experimental-mcp.md

MCP (Model Control Protocol) API

The MCP API provides comprehensive Model Control Protocol capabilities for integrating Composio tools with modern AI frameworks. This API offers streamlined MCP server creation, management, and user-specific URL generation.

Overview

Key benefits of the MCP API:

• Flexible configuration: Support for multiple toolkits and authentication methods
• User-specific servers: Generate unique MCP server URLs for individual users
• Comprehensive management: Full CRUD operations for MCP server configurations
• Authentication flexibility: Choose between manual account management or Composio-managed authentication

Getting Started

Using MCP API

The MCP features are available by default when you initialize Composio:

import { Composio } from '@composio/core';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

Basic Usage Pattern

// 1. Create MCP configuration
const mcpConfig = await composio.mcp.create('my-server-name', {
  toolkits: [{ toolkit: 'github', authConfigId: 'ac_233434343' }],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS'],
  manuallyManageConnections: false,
});

// 2. Generate server instance for a user
const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);

// 3. Use the server URL with any MCP client
const mcpUrl = serverInstance.url;

API Reference

composio.mcp

create(name, mcpConfig)

Creates a new MCP server configuration with the specified toolkit settings.

const mcpConfig = await composio.mcp.create('gmail-assistant', {
  toolkits: [
    { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
    { toolkit: 'slack', authConfigId: 'ac_slack_config' },
  ],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'SLACK_SEND_MESSAGE'],
  manuallyManageConnections: false,
});

// Alternative with string toolkit names
const mcpConfig = await composio.mcp.create('simple-server', {
  toolkits: ['github', 'slack'],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
  manuallyManageConnections: false,
});

Parameters:

• name (string): Unique name for the MCP server configuration
• mcpConfig (object): MCP configuration parameters
  • toolkits (Array): Array of toolkit configurations - can be strings or objects
    • As string: Just the toolkit name (e.g., "github", "slack")
    • As object: { toolkit?: string, authConfigId?: string }
  • allowedTools (string[], optional): Array of specific tool IDs to expose
  • manuallyManageConnections (boolean, optional): Whether to manually manage account connections. If false, Composio will inject account management tools. Defaults to false.

Returns: Promise<MCPConfigCreateResponse> - Created server details including:

• id: Server configuration UUID
• name: Server name
• allowedTools: Array of allowed tool IDs
• authConfigIds: Array of auth configuration IDs
• commands: Setup commands for different MCP clients (Claude, Cursor, Windsurf)
• MCPUrl: Base MCP server URL
• generate: Convenience method to generate user-specific server instances

generate(userId, mcpConfigurationId, options?)

Generates a user-specific MCP server instance with a unique URL.

const serverInstance = await composio.mcp.generate('user123', 'mcp_config_uuid', {
  manuallyManageConnections: false,
});

Parameters:

• userId (string): ID of the user to generate server instance for
• mcpConfigurationId (string): UUID of the MCP configuration
• options (object, optional): Additional server options
  • manuallyManageConnections (boolean): Override authentication method

Returns: Promise<MCPServerInstance> - Server instance details including:

• id: Server configuration ID
• name: Server name
• type: Connection type (always 'streamable_http')
• url: User-specific MCP server URL
• userId: Associated user ID
• allowedTools: Array of available tool IDs
• authConfigs: Array of auth configuration IDs

list(options)

Lists MCP server configurations with optional filtering and pagination.

// List all MCP servers
const allServers = await composio.mcp.list({});

// List with pagination
const pagedServers = await composio.mcp.list({
  page: 2,
  limit: 5
});

// Filter by toolkit
const githubServers = await composio.mcp.list({
  toolkits: ['github', 'slack']
});

// Filter by name
const namedServers = await composio.mcp.list({
  name: 'personal'
});

Parameters:

• options (object): Filtering and pagination options
  • page (number, optional): Page number for pagination (1-based, defaults to 1)
  • limit (number, optional): Maximum items per page (defaults to 10)
  • toolkits (string[], optional): Filter by toolkit names
  • authConfigs (string[], optional): Filter by auth configuration IDs
  • name (string, optional): Filter by server name (partial match)

Returns: Promise<MCPListResponse> - Paginated list with metadata:

• items: Array of MCP server configurations
• currentPage: Current page number
• totalPages: Total number of pages

get(serverId)

Retrieves detailed information about a specific MCP server.

const server = await composio.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

Parameters:

• serverId (string): The unique identifier of the MCP server

Returns: Promise<MCPItem> - Complete server details including configuration, tools, and metadata

update(serverId, config)

Updates an existing MCP server configuration.

// Update server name only
const updatedServer = await composio.mcp.update("mcp_12345", {
  name: "My Updated MCP Server"
});

// Update toolkits and tools
const serverWithNewTools = await composio.mcp.update("mcp_12345", {
  toolkits: [
    {
      toolkit: "github",
      authConfigId: "auth_abc123"
    },
    {
      toolkit: "slack", 
      authConfigId: "auth_xyz789"
    }
  ],
  allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_REPOS", "SLACK_SEND_MESSAGE"]
});

Parameters:

• serverId (string): The unique identifier of the MCP server to update
• config (object): Update configuration parameters
  • name (string, optional): New name for the MCP server
  • toolkits (Array, optional): Updated toolkit configurations
  • allowedTools (string[], optional): Updated list of allowed tools
  • manuallyManageConnections (boolean, optional): Updated connection management setting

Returns: Promise<MCPItem> - Updated MCP server configuration

delete(serverId)

Permanently deletes an MCP server configuration.

const result = await composio.mcp.delete("mcp_12345");

if (result.deleted) {
  console.log(`Server ${result.id} has been successfully deleted`);
}

Parameters:

• serverId (string): The unique identifier of the MCP server to delete

Returns: Promise<{id: string; deleted: boolean}> - Deletion confirmation

⚠️ Warning: This operation is irreversible. Once deleted, the MCP server configuration and all its associated data will be permanently removed.

Complete Examples

Basic MCP Server Setup

import { Composio } from '@composio/core';

// 1. Initialize Composio
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// 2. Create MCP configuration
const mcpConfig = await composio.mcp.create('gmail-assistant', {
  toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_your_gmail_config' }],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
  manuallyManageConnections: false,
});

console.log('MCP Configuration created:', mcpConfig.id);
console.log('Setup commands:');
console.log('Claude:', mcpConfig.commands.claude);
console.log('Cursor:', mcpConfig.commands.cursor);
console.log('Windsurf:', mcpConfig.commands.windsurf);

// 3. Generate server instance for a user
const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);

console.log('MCP Server URL for user123:', serverInstance.url);
console.log('Available tools:', serverInstance.allowedTools);

Using with Generic MCP Client

import { Composio } from '@composio/core';
import { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

// 1. Initialize Composio and create MCP configuration
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

const mcpConfig = await composio.mcp.create('multi-toolkit-assistant', {
  toolkits: [
    { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
    { toolkit: 'github', authConfigId: 'ac_github_config' },
  ],
  allowedTools: [
    'GMAIL_FETCH_EMAILS',
    'GMAIL_SEND_EMAIL', 
    'GITHUB_CREATE_ISSUE',
    'GITHUB_LIST_REPOS'
  ],
  manuallyManageConnections: false,
});

// 2. Generate server instance for a specific user
const serverInstance = await composio.mcp.generate('user456', mcpConfig.id);

// 3. Create MCP client connection
const transport = new SSEClientTransport(new URL(serverInstance.url));
const mcpClient = new MCPClient({
  name: 'composio-mcp-client',
  version: '1.0.0',
});

await mcpClient.connect(transport);

// 4. List available tools
const { tools } = await mcpClient.listTools();
console.log('Available tools:', tools.map(t => t.name));

// 5. Call a tool
const result = await mcpClient.callTool({
  name: 'GMAIL_FETCH_EMAILS',
  arguments: {
    limit: 5
  }
});

console.log('Email fetch result:', result);

// 6. Clean up
await mcpClient.close();

Managing Multiple Servers

import { Composio } from '@composio/core';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// Create multiple MCP configurations for different use cases
const personalConfig = await composio.mcp.create('personal-assistant', {
  toolkits: ['gmail', 'calendar'],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'CALENDAR_LIST_EVENTS'],
  manuallyManageConnections: false,
});

const workConfig = await composio.mcp.create('work-assistant', {
  toolkits: [
    { toolkit: 'github', authConfigId: 'ac_work_github' },
    { toolkit: 'slack', authConfigId: 'ac_work_slack' },
  ],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
  manuallyManageConnections: false,
});

// List all configurations
const allConfigs = await composio.mcp.list({});
console.log(`Total configurations: ${allConfigs.items.length}`);

// Generate instances for different users
const personalInstance = await composio.mcp.generate('user123', personalConfig.id);
const workInstance = await composio.mcp.generate('user123', workConfig.id);

console.log('Personal MCP URL:', personalInstance.url);
console.log('Work MCP URL:', workInstance.url);

// Update a configuration
const updatedConfig = await composio.mcp.update(personalConfig.id, {
  name: 'Enhanced Personal Assistant',
  allowedTools: [
    'GMAIL_FETCH_EMAILS', 
    'GMAIL_SEND_EMAIL',
    'CALENDAR_LIST_EVENTS',
    'CALENDAR_CREATE_EVENT'
  ]
});

console.log('Updated configuration:', updatedConfig.name);

Vercel AI Integration Example

import { Composio } from '@composio/core';
import { experimental_createMCPClient as createMCPClient, streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

// 1. Initialize Composio and create MCP configuration
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

const mcpConfig = await composio.mcp.create('ai-assistant', {
  toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail_config' }],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
  manuallyManageConnections: false,
});

// 2. Generate server instance
const serverInstance = await composio.mcp.generate('user789', mcpConfig.id);

// 3. Create Vercel AI MCP client
const transport = new SSEClientTransport(new URL(serverInstance.url));
const mcpClient = await createMCPClient({
  name: 'composio-mcp-client',
  transport: transport,
});

const tools = await mcpClient.tools();

// 4. Use with Vercel AI
const stream = streamText({
  model: openai('gpt-4o-mini'),
  messages: [
    {
      role: 'user',
      content: 'Fetch my latest 3 emails and provide a summary of each one',
    },
  ],
  tools,
});

// 5. Stream the response
for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

// 6. Clean up
await mcpClient.close();

Configuration Management

Auth Configuration

Before creating MCP configurations, you need to set up authentication configurations for your toolkits:

// Create an auth configuration for Gmail
const authConfig = await composio.authConfigs.create({
  toolkit: 'gmail',
  authScheme: 'OAUTH2',
  // Additional auth parameters...
});

// Use the auth config ID in your MCP configuration
const mcpConfig = await composio.mcp.create('gmail-server', {
  toolkits: [{ toolkit: 'gmail', authConfigId: authConfig.id }],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
  manuallyManageConnections: false,
});

Tool Selection

You can specify exactly which tools to expose through your MCP server:

const mcpConfig = await composio.mcp.create('multi-toolkit-server', {
  toolkits: [
    { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
    { toolkit: 'slack', authConfigId: 'ac_slack_config' },
  ],
  allowedTools: [
    'GMAIL_FETCH_EMAILS',
    'GMAIL_SEND_EMAIL',
    'GMAIL_CREATE_DRAFT',
    'SLACK_SEND_MESSAGE',
    'SLACK_LIST_CHANNELS',
  ],
  manuallyManageConnections: false,
});

Flexible Toolkit Configuration

You can configure toolkits in multiple ways:

// Using string array (requires default auth configs)
const simpleConfig = await composio.mcp.create('simple-server', {
  toolkits: ['github', 'slack'],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
  manuallyManageConnections: false,
});

// Using mixed configuration
const mixedConfig = await composio.mcp.create('mixed-server', {
  toolkits: [
    'calendar', // Uses default auth config
    { toolkit: 'gmail', authConfigId: 'ac_specific_gmail' }, // Uses specific auth config
    { authConfigId: 'ac_custom_integration' }, // Uses auth config without toolkit name
  ],
  manuallyManageConnections: false,
});

Types

MCPConfigCreationParams

interface MCPConfigCreationParams {
  toolkits: Array<string | MCPConfigToolkits>; // Array of toolkit configurations
  allowedTools?: string[]; // Optional array of specific tool IDs to expose
  manuallyManageConnections?: boolean; // Whether to manually manage account connections (default: false)
}

interface MCPConfigToolkits {
  toolkit?: string; // Toolkit identifier (e.g., "github", "slack")
  authConfigId?: string; // Authentication configuration ID
}

MCPConfigCreateResponse

interface MCPConfigCreateResponse {
  id: string; // Configuration UUID
  name: string; // Configuration name
  allowedTools: string[]; // Array of allowed tool IDs
  authConfigIds: string[]; // Array of auth configuration IDs
  commands: {
    claude: string; // Claude setup command
    cursor: string; // Cursor setup command
    windsurf: string; // Windsurf setup command
  };
  MCPUrl: string; // Base MCP server URL
  generate: (userId: string) => Promise<MCPServerInstance>; // Convenience method
}

MCPServerInstance

interface MCPServerInstance {
  id: string; // Server configuration ID
  name: string; // Server name
  type: 'streamable_http'; // Connection type
  url: string; // User-specific MCP server URL
  userId: string; // Associated user ID
  allowedTools: string[]; // Array of available tool IDs
  authConfigs: string[]; // Array of auth configuration IDs
}

MCPListParams

interface MCPListParams {
  page?: number; // Page number for pagination (1-based, default: 1)
  limit?: number; // Maximum items per page (default: 10)
  toolkits?: string[]; // Filter by toolkit names
  authConfigs?: string[]; // Filter by auth configuration IDs
  name?: string; // Filter by server name (partial match)
}

MCPListResponse

interface MCPListResponse {
  items: MCPItem[]; // Array of MCP server configurations
  currentPage: number; // Current page number
  totalPages: number; // Total number of pages
}

MCPItem

interface MCPItem {
  id: string; // Server configuration ID
  name: string; // Server name
  allowedTools: string[]; // Array of allowed tool IDs
  authConfigIds: string[]; // Array of auth configuration IDs
  commands: {
    claude: string; // Claude setup command
    cursor: string; // Cursor setup command
    windsurf: string; // Windsurf setup command
  };
  MCPUrl: string; // Base MCP server URL
  toolkitIcons: Record<string, string>; // Toolkit icons mapping
  serverInstanceCount: number; // Number of active server instances
  toolkits: string[]; // Array of associated toolkit names
}

MCPUpdateParams

interface MCPUpdateParams {
  name?: string; // Updated server name
  toolkits?: Array<string | MCPConfigToolkits>; // Updated toolkit configurations
  allowedTools?: string[]; // Updated array of allowed tools
  manuallyManageConnections?: boolean; // Updated connection management setting
}

MCPGetInstanceParams

interface MCPGetInstanceParams {
  manuallyManageConnections?: boolean; // Whether to manually manage account connections (default: false)
}

Best Practices

1. Configuration Naming

Use descriptive names that indicate the purpose and scope:

// Good
await composio.mcp.create(
  "gmail-support-assistant",
  {
    toolkits: [...],
    manuallyManageConnections: false
  }
);

// Avoid
await composio.mcp.create(
  "config1",
  {
    toolkits: [...],
    manuallyManageConnections: false
  }
);

2. Tool Selection

Be specific about which tools to expose:

// Good - specific tools for the use case
const mcpConfig = await composio.mcp.create('email-assistant', {
  toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail' }],
  allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'GMAIL_CREATE_DRAFT'],
  manuallyManageConnections: false,
});

// Avoid - exposing unnecessary tools
const mcpConfig = await composio.mcp.create('email-assistant', {
  toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail' }],
  // No allowedTools specified - exposes all tools
  manuallyManageConnections: false,
});

3. Authentication Management

Use Composio-managed authentication when possible:

// Recommended
const mcpConfig = await composio.mcp.create(
  "server-name",
  {
    toolkits: [...],
    manuallyManageConnections: false  // Let Composio handle auth
  }
);

4. Error Handling

Always handle potential errors:

try {
  const mcpConfig = await composio.mcp.create('server-name', {
    toolkits: serverConfigs,
    manuallyManageConnections: false,
  });

  const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);

  // Use server instance with your MCP client
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Configuration error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

5. Resource Cleanup

Clean up MCP clients when done:

// For generic MCP clients
await mcpClient.close();

// For Vercel AI MCP clients
await mcpClient.close();

6. Server Instance Management

Generate server instances per user to maintain proper isolation:

// Good - separate instances for different users
const userAInstance = await composio.mcp.generate('userA', mcpConfig.id);
const userBInstance = await composio.mcp.generate('userB', mcpConfig.id);

// Each user gets their own isolated MCP server URL
console.log('User A MCP URL:', userAInstance.url);
console.log('User B MCP URL:', userBInstance.url);

7. Pagination for Large Lists

Use pagination when listing many MCP configurations:

// Good - paginate through results
let currentPage = 1;
let hasMore = true;

while (hasMore) {
  const result = await composio.mcp.list({
    page: currentPage,
    limit: 20
  });
  
  // Process result.items
  console.log(`Page ${currentPage}: ${result.items.length} items`);
  
  hasMore = currentPage < result.totalPages;
  currentPage++;
}

Migration from Deprecated MCP API

If you're using the deprecated MCP API, here's how to migrate:

Before (Deprecated MCP API)

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new AnthropicProvider(),
});

const server = await composio.deprecated.mcp.create(
  'server-name',
  [
    {
      authConfigId: 'ac_config',
      allowedTools: ['GMAIL_FETCH_EMAILS'],
    },
  ],
  { isChatAuth: true }
);

const urls = await server.getServer({
  userId: 'user123',
});

After (Current MCP API)

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

const mcpConfig = await composio.mcp.create('server-name', {
  toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_config' }],
  allowedTools: ['GMAIL_FETCH_EMAILS'],
  manuallyManageConnections: true, // Equivalent to isChatAuth: true
});

const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);

Key Differences

1. API Location: Moved from composio.deprecated.mcp to composio.mcp
2. Configuration Structure: Simplified toolkit configuration with flexible options
3. Response Format: Returns MCPServerInstance instead of provider-specific formats
4. Method Names: generate() instead of getServer()
5. Authentication: manuallyManageConnections instead of isChatAuth

Troubleshooting

Common Issues

1. Auth config not found: Verify your auth configuration IDs are correct and exist

   // Verify auth config exists
   try {
     const authConfig = await composio.authConfigs.get('ac_your_config_id');
     console.log('Auth config found:', authConfig.toolkit);
   } catch (error) {
     console.error('Auth config not found:', error.message);
   }
   

2. Tool not available: Check that tools are properly configured in your toolkit

   // List available tools for a toolkit
   const tools = await composio.tools.list({ toolkit: 'gmail' });
   console.log('Available Gmail tools:', tools.map(t => t.slug));
   

3. Connection timeout: MCP clients need to remain active while tools are being used

   // Set appropriate timeouts for long-running operations
   const transport = new SSEClientTransport(new URL(serverInstance.url), {
     timeout: 30000 // 30 seconds
   });
   

4. Server instance not found: Ensure the MCP configuration ID is valid

   // Verify configuration exists before generating instance
   try {
     const config = await composio.mcp.get(mcpConfigId);
     const instance = await composio.mcp.generate(userId, mcpConfigId);
   } catch (error) {
     console.error('Configuration not found:', error.message);
   }
   

5. Validation errors: Check that your configuration parameters are correct

   // Ensure toolkits array is properly formatted
   const mcpConfig = await composio.mcp.create('server-name', {
     toolkits: [
       { toolkit: 'gmail', authConfigId: 'ac_valid_id' }, // Valid format
       'github', // Also valid for default auth
     ],
     allowedTools: ['GMAIL_FETCH_EMAILS'], // Must be valid tool slugs
     manuallyManageConnections: false, // Must be boolean
   });
   

Debug Mode

Enable debug logging to troubleshoot issues:

// Set environment variable for debug logging
process.env.COMPOSIO_LOG_LEVEL = 'debug';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
});

// Additional debugging
console.log('Composio config:', {
  baseURL: composio.config?.baseURL,
  hasApiKey: !!composio.config?.apiKey,
});

Getting Help

If you encounter issues:

1. Check the Composio documentation
2. Review your auth configurations and connected accounts
3. Verify that your MCP client is compatible with the Server-Sent Events transport
4. Ensure your API key has the necessary permissions

Conclusion

The MCP API provides a powerful and flexible way to integrate Composio's tools with modern AI frameworks through the Model Control Protocol. Key benefits include:

• Comprehensive management: Full CRUD operations for MCP server configurations
• User isolation: Generate unique server instances for individual users
• Flexible authentication: Choose between Composio-managed or manual account management
• Universal compatibility: Works with any MCP-compatible client

By following the patterns and best practices outlined in this documentation, you can build robust and maintainable AI applications that leverage the full power of Composio's tool ecosystem through standardized MCP interfaces.