@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 881 lines 25.1 KB
Rendered Raw
1 # MCP (Model Control Protocol) API
2
3 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.
4
5 ## Overview
6
7 Key benefits of the MCP API:
8
9 - **Flexible configuration**: Support for multiple toolkits and authentication methods
10 - **User-specific servers**: Generate unique MCP server URLs for individual users
11 - **Comprehensive management**: Full CRUD operations for MCP server configurations
12 - **Authentication flexibility**: Choose between manual account management or Composio-managed authentication
13
14 ## Getting Started
15
16 ### Using MCP API
17
18 The MCP features are available by default when you initialize Composio:
19
20 ```typescript
21 import { Composio } from '@composio/core';
22
23 const composio = new Composio({
24 apiKey: process.env.COMPOSIO_API_KEY,
25 });
26 ```
27
28 ### Basic Usage Pattern
29
30 ```typescript
31 // 1. Create MCP configuration
32 const mcpConfig = await composio.mcp.create('my-server-name', {
33 toolkits: [{ toolkit: 'github', authConfigId: 'ac_233434343' }],
34 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
35 manuallyManageConnections: false,
36 });
37
38 // 2. Generate server instance for a user
39 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
40
41 // 3. Use the server URL with any MCP client
42 const mcpUrl = serverInstance.url;
43 ```
44
45 ## API Reference
46
47 ### composio.mcp
48
49 #### create(name, mcpConfig)
50
51 Creates a new MCP server configuration with the specified toolkit settings.
52
53 ```typescript
54 const mcpConfig = await composio.mcp.create('gmail-assistant', {
55 toolkits: [
56 { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
57 { toolkit: 'slack', authConfigId: 'ac_slack_config' },
58 ],
59 allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'SLACK_SEND_MESSAGE'],
60 manuallyManageConnections: false,
61 });
62
63 // Alternative with string toolkit names
64 const mcpConfig = await composio.mcp.create('simple-server', {
65 toolkits: ['github', 'slack'],
66 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
67 manuallyManageConnections: false,
68 });
69 ```
70
71 **Parameters:**
72
73 - `name` (string): Unique name for the MCP server configuration
74 - `mcpConfig` (object): MCP configuration parameters
75 - `toolkits` (Array): Array of toolkit configurations - can be strings or objects
76 - As string: Just the toolkit name (e.g., "github", "slack")
77 - As object: `{ toolkit?: string, authConfigId?: string }`
78 - `allowedTools` (string[], optional): Array of specific tool IDs to expose
79 - `manuallyManageConnections` (boolean, optional): Whether to manually manage account connections. If false, Composio will inject account management tools. Defaults to false.
80
81 **Returns:** `Promise<MCPConfigCreateResponse>` - Created server details including:
82
83 - `id`: Server configuration UUID
84 - `name`: Server name
85 - `allowedTools`: Array of allowed tool IDs
86 - `authConfigIds`: Array of auth configuration IDs
87 - `commands`: Setup commands for different MCP clients (Claude, Cursor, Windsurf)
88 - `MCPUrl`: Base MCP server URL
89 - `generate`: Convenience method to generate user-specific server instances
90
91 #### generate(userId, mcpConfigurationId, options?)
92
93 Generates a user-specific MCP server instance with a unique URL.
94
95 ```typescript
96 const serverInstance = await composio.mcp.generate('user123', 'mcp_config_uuid', {
97 manuallyManageConnections: false,
98 });
99 ```
100
101 **Parameters:**
102
103 - `userId` (string): ID of the user to generate server instance for
104 - `mcpConfigurationId` (string): UUID of the MCP configuration
105 - `options` (object, optional): Additional server options
106 - `manuallyManageConnections` (boolean): Override authentication method
107
108 **Returns:** `Promise<MCPServerInstance>` - Server instance details including:
109
110 - `id`: Server configuration ID
111 - `name`: Server name
112 - `type`: Connection type (always 'streamable_http')
113 - `url`: User-specific MCP server URL
114 - `userId`: Associated user ID
115 - `allowedTools`: Array of available tool IDs
116 - `authConfigs`: Array of auth configuration IDs
117
118 #### list(options)
119
120 Lists MCP server configurations with optional filtering and pagination.
121
122 ```typescript
123 // List all MCP servers
124 const allServers = await composio.mcp.list({});
125
126 // List with pagination
127 const pagedServers = await composio.mcp.list({
128 page: 2,
129 limit: 5
130 });
131
132 // Filter by toolkit
133 const githubServers = await composio.mcp.list({
134 toolkits: ['github', 'slack']
135 });
136
137 // Filter by name
138 const namedServers = await composio.mcp.list({
139 name: 'personal'
140 });
141 ```
142
143 **Parameters:**
144
145 - `options` (object): Filtering and pagination options
146 - `page` (number, optional): Page number for pagination (1-based, defaults to 1)
147 - `limit` (number, optional): Maximum items per page (defaults to 10)
148 - `toolkits` (string[], optional): Filter by toolkit names
149 - `authConfigs` (string[], optional): Filter by auth configuration IDs
150 - `name` (string, optional): Filter by server name (partial match)
151
152 **Returns:** `Promise<MCPListResponse>` - Paginated list with metadata:
153
154 - `items`: Array of MCP server configurations
155 - `currentPage`: Current page number
156 - `totalPages`: Total number of pages
157
158 #### get(serverId)
159
160 Retrieves detailed information about a specific MCP server.
161
162 ```typescript
163 const server = await composio.mcp.get("mcp_12345");
164
165 console.log(server.name); // "My Personal MCP Server"
166 console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
167 console.log(server.toolkits); // ["github", "slack"]
168 console.log(server.serverInstanceCount); // 3
169
170 // Access setup commands for different clients
171 console.log(server.commands.claude); // Claude setup command
172 console.log(server.commands.cursor); // Cursor setup command
173 console.log(server.commands.windsurf); // Windsurf setup command
174 ```
175
176 **Parameters:**
177
178 - `serverId` (string): The unique identifier of the MCP server
179
180 **Returns:** `Promise<MCPItem>` - Complete server details including configuration, tools, and metadata
181
182 #### update(serverId, config)
183
184 Updates an existing MCP server configuration.
185
186 ```typescript
187 // Update server name only
188 const updatedServer = await composio.mcp.update("mcp_12345", {
189 name: "My Updated MCP Server"
190 });
191
192 // Update toolkits and tools
193 const serverWithNewTools = await composio.mcp.update("mcp_12345", {
194 toolkits: [
195 {
196 toolkit: "github",
197 authConfigId: "auth_abc123"
198 },
199 {
200 toolkit: "slack",
201 authConfigId: "auth_xyz789"
202 }
203 ],
204 allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS", "SLACK_SEND_MESSAGE"]
205 });
206 ```
207
208 **Parameters:**
209
210 - `serverId` (string): The unique identifier of the MCP server to update
211 - `config` (object): Update configuration parameters
212 - `name` (string, optional): New name for the MCP server
213 - `toolkits` (Array, optional): Updated toolkit configurations
214 - `allowedTools` (string[], optional): Updated list of allowed tools
215 - `manuallyManageConnections` (boolean, optional): Updated connection management setting
216
217 **Returns:** `Promise<MCPItem>` - Updated MCP server configuration
218
219 #### delete(serverId)
220
221 Permanently deletes an MCP server configuration.
222
223 ```typescript
224 const result = await composio.mcp.delete("mcp_12345");
225
226 if (result.deleted) {
227 console.log(`Server ${result.id} has been successfully deleted`);
228 }
229 ```
230
231 **Parameters:**
232
233 - `serverId` (string): The unique identifier of the MCP server to delete
234
235 **Returns:** `Promise<{id: string; deleted: boolean}>` - Deletion confirmation
236
237 **⚠️ Warning:** This operation is irreversible. Once deleted, the MCP server configuration and all its associated data will be permanently removed.
238
239 ## Complete Examples
240
241 ### Basic MCP Server Setup
242
243 ```typescript
244 import { Composio } from '@composio/core';
245
246 // 1. Initialize Composio
247 const composio = new Composio({
248 apiKey: process.env.COMPOSIO_API_KEY,
249 });
250
251 // 2. Create MCP configuration
252 const mcpConfig = await composio.mcp.create('gmail-assistant', {
253 toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_your_gmail_config' }],
254 allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
255 manuallyManageConnections: false,
256 });
257
258 console.log('MCP Configuration created:', mcpConfig.id);
259 console.log('Setup commands:');
260 console.log('Claude:', mcpConfig.commands.claude);
261 console.log('Cursor:', mcpConfig.commands.cursor);
262 console.log('Windsurf:', mcpConfig.commands.windsurf);
263
264 // 3. Generate server instance for a user
265 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
266
267 console.log('MCP Server URL for user123:', serverInstance.url);
268 console.log('Available tools:', serverInstance.allowedTools);
269 ```
270
271 ### Using with Generic MCP Client
272
273 ```typescript
274 import { Composio } from '@composio/core';
275 import { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
276 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
277
278 // 1. Initialize Composio and create MCP configuration
279 const composio = new Composio({
280 apiKey: process.env.COMPOSIO_API_KEY,
281 });
282
283 const mcpConfig = await composio.mcp.create('multi-toolkit-assistant', {
284 toolkits: [
285 { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
286 { toolkit: 'github', authConfigId: 'ac_github_config' },
287 ],
288 allowedTools: [
289 'GMAIL_FETCH_EMAILS',
290 'GMAIL_SEND_EMAIL',
291 'GITHUB_CREATE_AN_ISSUE',
292 'GITHUB_LIST_REPOS'
293 ],
294 manuallyManageConnections: false,
295 });
296
297 // 2. Generate server instance for a specific user
298 const serverInstance = await composio.mcp.generate('user456', mcpConfig.id);
299
300 // 3. Create MCP client connection
301 const transport = new SSEClientTransport(new URL(serverInstance.url));
302 const mcpClient = new MCPClient({
303 name: 'composio-mcp-client',
304 version: '1.0.0',
305 });
306
307 await mcpClient.connect(transport);
308
309 // 4. List available tools
310 const { tools } = await mcpClient.listTools();
311 console.log('Available tools:', tools.map(t => t.name));
312
313 // 5. Call a tool
314 const result = await mcpClient.callTool({
315 name: 'GMAIL_FETCH_EMAILS',
316 arguments: {
317 limit: 5
318 }
319 });
320
321 console.log('Email fetch result:', result);
322
323 // 6. Clean up
324 await mcpClient.close();
325 ```
326
327 ### Managing Multiple Servers
328
329 ```typescript
330 import { Composio } from '@composio/core';
331
332 const composio = new Composio({
333 apiKey: process.env.COMPOSIO_API_KEY,
334 });
335
336 // Create multiple MCP configurations for different use cases
337 const personalConfig = await composio.mcp.create('personal-assistant', {
338 toolkits: ['gmail', 'calendar'],
339 allowedTools: ['GMAIL_FETCH_EMAILS', 'CALENDAR_LIST_EVENTS'],
340 manuallyManageConnections: false,
341 });
342
343 const workConfig = await composio.mcp.create('work-assistant', {
344 toolkits: [
345 { toolkit: 'github', authConfigId: 'ac_work_github' },
346 { toolkit: 'slack', authConfigId: 'ac_work_slack' },
347 ],
348 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
349 manuallyManageConnections: false,
350 });
351
352 // List all configurations
353 const allConfigs = await composio.mcp.list({});
354 console.log(`Total configurations: ${allConfigs.items.length}`);
355
356 // Generate instances for different users
357 const personalInstance = await composio.mcp.generate('user123', personalConfig.id);
358 const workInstance = await composio.mcp.generate('user123', workConfig.id);
359
360 console.log('Personal MCP URL:', personalInstance.url);
361 console.log('Work MCP URL:', workInstance.url);
362
363 // Update a configuration
364 const updatedConfig = await composio.mcp.update(personalConfig.id, {
365 name: 'Enhanced Personal Assistant',
366 allowedTools: [
367 'GMAIL_FETCH_EMAILS',
368 'GMAIL_SEND_EMAIL',
369 'CALENDAR_LIST_EVENTS',
370 'CALENDAR_CREATE_EVENT'
371 ]
372 });
373
374 console.log('Updated configuration:', updatedConfig.name);
375 ```
376
377 ### Vercel AI Integration Example
378
379 ```typescript
380 import { Composio } from '@composio/core';
381 import { experimental_createMCPClient as createMCPClient, streamText } from 'ai';
382 import { openai } from '@ai-sdk/openai';
383 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
384
385 // 1. Initialize Composio and create MCP configuration
386 const composio = new Composio({
387 apiKey: process.env.COMPOSIO_API_KEY,
388 });
389
390 const mcpConfig = await composio.mcp.create('ai-assistant', {
391 toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail_config' }],
392 allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
393 manuallyManageConnections: false,
394 });
395
396 // 2. Generate server instance
397 const serverInstance = await composio.mcp.generate('user789', mcpConfig.id);
398
399 // 3. Create Vercel AI MCP client
400 const transport = new SSEClientTransport(new URL(serverInstance.url));
401 const mcpClient = await createMCPClient({
402 name: 'composio-mcp-client',
403 transport: transport,
404 });
405
406 const tools = await mcpClient.tools();
407
408 // 4. Use with Vercel AI
409 const stream = streamText({
410 model: openai('gpt-4o-mini'),
411 messages: [
412 {
413 role: 'user',
414 content: 'Fetch my latest 3 emails and provide a summary of each one',
415 },
416 ],
417 tools,
418 });
419
420 // 5. Stream the response
421 for await (const textPart of stream.textStream) {
422 process.stdout.write(textPart);
423 }
424
425 // 6. Clean up
426 await mcpClient.close();
427 ```
428
429 ## Configuration Management
430
431 ### Auth Configuration
432
433 Before creating MCP configurations, you need to set up authentication configurations for your toolkits:
434
435 ```typescript
436 // Create an auth configuration for Gmail
437 const authConfig = await composio.authConfigs.create({
438 toolkit: 'gmail',
439 authScheme: 'OAUTH2',
440 // Additional auth parameters...
441 });
442
443 // Use the auth config ID in your MCP configuration
444 const mcpConfig = await composio.mcp.create('gmail-server', {
445 toolkits: [{ toolkit: 'gmail', authConfigId: authConfig.id }],
446 allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
447 manuallyManageConnections: false,
448 });
449 ```
450
451 ### Tool Selection
452
453 You can specify exactly which tools to expose through your MCP server:
454
455 ```typescript
456 const mcpConfig = await composio.mcp.create('multi-toolkit-server', {
457 toolkits: [
458 { toolkit: 'gmail', authConfigId: 'ac_gmail_config' },
459 { toolkit: 'slack', authConfigId: 'ac_slack_config' },
460 ],
461 allowedTools: [
462 'GMAIL_FETCH_EMAILS',
463 'GMAIL_SEND_EMAIL',
464 'GMAIL_CREATE_DRAFT',
465 'SLACK_SEND_MESSAGE',
466 'SLACK_LIST_CHANNELS',
467 ],
468 manuallyManageConnections: false,
469 });
470 ```
471
472 ### Flexible Toolkit Configuration
473
474 You can configure toolkits in multiple ways:
475
476 ```typescript
477 // Using string array (requires default auth configs)
478 const simpleConfig = await composio.mcp.create('simple-server', {
479 toolkits: ['github', 'slack'],
480 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'SLACK_SEND_MESSAGE'],
481 manuallyManageConnections: false,
482 });
483
484 // Using mixed configuration
485 const mixedConfig = await composio.mcp.create('mixed-server', {
486 toolkits: [
487 'calendar', // Uses default auth config
488 { toolkit: 'gmail', authConfigId: 'ac_specific_gmail' }, // Uses specific auth config
489 { authConfigId: 'ac_custom_integration' }, // Uses auth config without toolkit name
490 ],
491 manuallyManageConnections: false,
492 });
493 ```
494
495 ## Types
496
497 ### MCPConfigCreationParams
498
499 ```typescript
500 interface MCPConfigCreationParams {
501 toolkits: Array<string | MCPConfigToolkits>; // Array of toolkit configurations
502 allowedTools?: string[]; // Optional array of specific tool IDs to expose
503 manuallyManageConnections?: boolean; // Whether to manually manage account connections (default: false)
504 }
505
506 interface MCPConfigToolkits {
507 toolkit?: string; // Toolkit identifier (e.g., "github", "slack")
508 authConfigId?: string; // Authentication configuration ID
509 }
510 ```
511
512 ### MCPConfigCreateResponse
513
514 ```typescript
515 interface MCPConfigCreateResponse {
516 id: string; // Configuration UUID
517 name: string; // Configuration name
518 allowedTools: string[]; // Array of allowed tool IDs
519 authConfigIds: string[]; // Array of auth configuration IDs
520 commands: {
521 claude: string; // Claude setup command
522 cursor: string; // Cursor setup command
523 windsurf: string; // Windsurf setup command
524 };
525 MCPUrl: string; // Base MCP server URL
526 generate: (userId: string) => Promise<MCPServerInstance>; // Convenience method
527 }
528 ```
529
530 ### MCPServerInstance
531
532 ```typescript
533 interface MCPServerInstance {
534 id: string; // Server configuration ID
535 name: string; // Server name
536 type: 'streamable_http'; // Connection type
537 url: string; // User-specific MCP server URL
538 userId: string; // Associated user ID
539 allowedTools: string[]; // Array of available tool IDs
540 authConfigs: string[]; // Array of auth configuration IDs
541 }
542 ```
543
544 ### MCPListParams
545
546 ```typescript
547 interface MCPListParams {
548 page?: number; // Page number for pagination (1-based, default: 1)
549 limit?: number; // Maximum items per page (default: 10)
550 toolkits?: string[]; // Filter by toolkit names
551 authConfigs?: string[]; // Filter by auth configuration IDs
552 name?: string; // Filter by server name (partial match)
553 }
554 ```
555
556 ### MCPListResponse
557
558 ```typescript
559 interface MCPListResponse {
560 items: MCPItem[]; // Array of MCP server configurations
561 currentPage: number; // Current page number
562 totalPages: number; // Total number of pages
563 }
564 ```
565
566 ### MCPItem
567
568 ```typescript
569 interface MCPItem {
570 id: string; // Server configuration ID
571 name: string; // Server name
572 allowedTools: string[]; // Array of allowed tool IDs
573 authConfigIds: string[]; // Array of auth configuration IDs
574 commands: {
575 claude: string; // Claude setup command
576 cursor: string; // Cursor setup command
577 windsurf: string; // Windsurf setup command
578 };
579 MCPUrl: string; // Base MCP server URL
580 toolkitIcons: Record<string, string>; // Toolkit icons mapping
581 serverInstanceCount: number; // Number of active server instances
582 toolkits: string[]; // Array of associated toolkit names
583 }
584 ```
585
586 ### MCPUpdateParams
587
588 ```typescript
589 interface MCPUpdateParams {
590 name?: string; // Updated server name
591 toolkits?: Array<string | MCPConfigToolkits>; // Updated toolkit configurations
592 allowedTools?: string[]; // Updated array of allowed tools
593 manuallyManageConnections?: boolean; // Updated connection management setting
594 }
595 ```
596
597 ### MCPGetInstanceParams
598
599 ```typescript
600 interface MCPGetInstanceParams {
601 manuallyManageConnections?: boolean; // Whether to manually manage account connections (default: false)
602 }
603 ```
604
605 ## Best Practices
606
607 ### 1. Configuration Naming
608
609 Use descriptive names that indicate the purpose and scope:
610
611 ```typescript
612 // Good
613 await composio.mcp.create(
614 "gmail-support-assistant",
615 {
616 toolkits: [...],
617 manuallyManageConnections: false
618 }
619 );
620
621 // Avoid
622 await composio.mcp.create(
623 "config1",
624 {
625 toolkits: [...],
626 manuallyManageConnections: false
627 }
628 );
629 ```
630
631 ### 2. Tool Selection
632
633 Be specific about which tools to expose:
634
635 ```typescript
636 // Good - specific tools for the use case
637 const mcpConfig = await composio.mcp.create('email-assistant', {
638 toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail' }],
639 allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'GMAIL_CREATE_DRAFT'],
640 manuallyManageConnections: false,
641 });
642
643 // Avoid - exposing unnecessary tools
644 const mcpConfig = await composio.mcp.create('email-assistant', {
645 toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_gmail' }],
646 // No allowedTools specified - exposes all tools
647 manuallyManageConnections: false,
648 });
649 ```
650
651 ### 3. Authentication Management
652
653 Use Composio-managed authentication when possible:
654
655 ```typescript
656 // Recommended
657 const mcpConfig = await composio.mcp.create(
658 "server-name",
659 {
660 toolkits: [...],
661 manuallyManageConnections: false // Let Composio handle auth
662 }
663 );
664 ```
665
666 ### 4. Error Handling
667
668 Always handle potential errors:
669
670 ```typescript
671 try {
672 const mcpConfig = await composio.mcp.create('server-name', {
673 toolkits: serverConfigs,
674 manuallyManageConnections: false,
675 });
676
677 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
678
679 // Use server instance with your MCP client
680 } catch (error) {
681 if (error instanceof ValidationError) {
682 console.error('Configuration error:', error.message);
683 } else {
684 console.error('Unexpected error:', error);
685 }
686 }
687 ```
688
689 ### 5. Resource Cleanup
690
691 Clean up MCP clients when done:
692
693 ```typescript
694 // For generic MCP clients
695 await mcpClient.close();
696
697 // For Vercel AI MCP clients
698 await mcpClient.close();
699 ```
700
701 ### 6. Server Instance Management
702
703 Generate server instances per user to maintain proper isolation:
704
705 ```typescript
706 // Good - separate instances for different users
707 const userAInstance = await composio.mcp.generate('userA', mcpConfig.id);
708 const userBInstance = await composio.mcp.generate('userB', mcpConfig.id);
709
710 // Each user gets their own isolated MCP server URL
711 console.log('User A MCP URL:', userAInstance.url);
712 console.log('User B MCP URL:', userBInstance.url);
713 ```
714
715 ### 7. Pagination for Large Lists
716
717 Use pagination when listing many MCP configurations:
718
719 ```typescript
720 // Good - paginate through results
721 let currentPage = 1;
722 let hasMore = true;
723
724 while (hasMore) {
725 const result = await composio.mcp.list({
726 page: currentPage,
727 limit: 20
728 });
729
730 // Process result.items
731 console.log(`Page ${currentPage}: ${result.items.length} items`);
732
733 hasMore = currentPage < result.totalPages;
734 currentPage++;
735 }
736 ```
737
738 ## Migration from Deprecated MCP API
739
740 If you're using the deprecated MCP API, here's how to migrate:
741
742 ### Before (Deprecated MCP API)
743
744 ```typescript
745 const composio = new Composio({
746 apiKey: process.env.COMPOSIO_API_KEY,
747 provider: new AnthropicProvider(),
748 });
749
750 const server = await composio.deprecated.mcp.create(
751 'server-name',
752 [
753 {
754 authConfigId: 'ac_config',
755 allowedTools: ['GMAIL_FETCH_EMAILS'],
756 },
757 ],
758 { isChatAuth: true }
759 );
760
761 const urls = await server.getServer({
762 userId: 'user123',
763 });
764 ```
765
766 ### After (Current MCP API)
767
768 ```typescript
769 const composio = new Composio({
770 apiKey: process.env.COMPOSIO_API_KEY,
771 });
772
773 const mcpConfig = await composio.mcp.create('server-name', {
774 toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_config' }],
775 allowedTools: ['GMAIL_FETCH_EMAILS'],
776 manuallyManageConnections: true, // Equivalent to isChatAuth: true
777 });
778
779 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
780 ```
781
782 ### Key Differences
783
784 1. **API Location**: Moved from `composio.deprecated.mcp` to `composio.mcp`
785 2. **Configuration Structure**: Simplified toolkit configuration with flexible options
786 3. **Response Format**: Returns `MCPServerInstance` instead of provider-specific formats
787 4. **Method Names**: `generate()` instead of `getServer()`
788 5. **Authentication**: `manuallyManageConnections` instead of `isChatAuth`
789
790 ## Troubleshooting
791
792 ### Common Issues
793
794 1. **Auth config not found**: Verify your auth configuration IDs are correct and exist
795 ```typescript
796 // Verify auth config exists
797 try {
798 const authConfig = await composio.authConfigs.get('ac_your_config_id');
799 console.log('Auth config found:', authConfig.toolkit);
800 } catch (error) {
801 console.error('Auth config not found:', error.message);
802 }
803 ```
804
805 2. **Tool not available**: Check that tools are properly configured in your toolkit
806 ```typescript
807 // List available tools for a toolkit
808 const tools = await composio.tools.list({ toolkit: 'gmail' });
809 console.log('Available Gmail tools:', tools.map(t => t.slug));
810 ```
811
812 3. **Connection timeout**: MCP clients need to remain active while tools are being used
813 ```typescript
814 // Set appropriate timeouts for long-running operations
815 const transport = new SSEClientTransport(new URL(serverInstance.url), {
816 timeout: 30000 // 30 seconds
817 });
818 ```
819
820 4. **Server instance not found**: Ensure the MCP configuration ID is valid
821 ```typescript
822 // Verify configuration exists before generating instance
823 try {
824 const config = await composio.mcp.get(mcpConfigId);
825 const instance = await composio.mcp.generate(userId, mcpConfigId);
826 } catch (error) {
827 console.error('Configuration not found:', error.message);
828 }
829 ```
830
831 5. **Validation errors**: Check that your configuration parameters are correct
832 ```typescript
833 // Ensure toolkits array is properly formatted
834 const mcpConfig = await composio.mcp.create('server-name', {
835 toolkits: [
836 { toolkit: 'gmail', authConfigId: 'ac_valid_id' }, // Valid format
837 'github', // Also valid for default auth
838 ],
839 allowedTools: ['GMAIL_FETCH_EMAILS'], // Must be valid tool slugs
840 manuallyManageConnections: false, // Must be boolean
841 });
842 ```
843
844 ### Debug Mode
845
846 Enable debug logging to troubleshoot issues:
847
848 ```typescript
849 // Set environment variable for debug logging
850 process.env.COMPOSIO_LOG_LEVEL = 'debug';
851
852 const composio = new Composio({
853 apiKey: process.env.COMPOSIO_API_KEY,
854 });
855
856 // Additional debugging
857 console.log('Composio config:', {
858 baseURL: composio.config?.baseURL,
859 hasApiKey: !!composio.config?.apiKey,
860 });
861 ```
862
863 ### Getting Help
864
865 If you encounter issues:
866
867 1. Check the [Composio documentation](https://docs.composio.dev)
868 2. Review your auth configurations and connected accounts
869 3. Verify that your MCP client is compatible with the Server-Sent Events transport
870 4. Ensure your API key has the necessary permissions
871
872 ## Conclusion
873
874 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:
875
876 - **Comprehensive management**: Full CRUD operations for MCP server configurations
877 - **User isolation**: Generate unique server instances for individual users
878 - **Flexible authentication**: Choose between Composio-managed or manual account management
879 - **Universal compatibility**: Works with any MCP-compatible client
880
881 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.