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 22, 22:00 UTC
feat: update mcp flow in ts sdk
Utkarsh Dixit committed
Jul 5, 2025 at 19:30 UTC
f1a7e0f9ca35dda708e908c26cc0785f5913b5b3
9 files changed
+91
-124
fern/pages/src/mcp/developers.mdx
+9
-11
@@ -155,7 +155,7 @@ const updatedServer = await composio.mcp.update(
155
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
156
}
157
],
158
- { useComposioManagedAuth: true }
158
+ { isChatAuth: true }
159
);
160
```
161
@@ -203,20 +203,18 @@ Pre-authentication is recommended for production applications as it provides bet
203
204
## Best Practices
205
206
-1. **Use meaningful server names** - This helps with organization and makes servers easier to find
207
-2. **Limit tools appropriately** - Only include the tools your users actually need
208
-3. **Check connection status** - Always verify user authentication before using server URLs
209
-4. **Handle authentication gracefully** - Provide clear instructions when users need to authenticate
210
-5. **Use the convenience methods** - The `getServer` method on create responses simplifies URL generation
206
+1. **Use meaningful server names** - This helps with organization and makes servers easier to find.
207
+2. **Limit tools appropriately** - Only include the tools your users actually need.
208
+3. **Check connection status** - Always verify user authentication before using server URLs.
209
+4. **Handle authentication gracefully** - Provide clear instructions when users need to authenticate.
210
+5. **Use the convenience methods** - The `getServer` method on create responses simplifies URL generation.
211
212
<Warning>
213
SSE support is deprecated. If you're using `/sse` endpoints or `transport=sse` query parameters, migrate to the standard `/mcp` endpoints.
214
</Warning>
215
216
-### Configuring authentication
217
-You or your users need to authenticate against an app to use its MCP server through Composio!
218
-This can be done in two ways:
216
+### Configuring Authentication
217
+You or your users need to authenticate against an app to use its MCP server through Composio. This can be done in two ways:
218
219
* Authenticate users upfront via the Composio SDK/API. Follow [custom auth configs](/docs/custom-auth-configs) to learn how to connect users. This is recommended for most use cases.
221
-* Let the agent authenticate users on demand. Passing `include_composio_helper_actions=true` in the URL will include Composio's helper actions and the agent will guide the user through auth on demand.
222
-
220
+* Let the agent authenticate users on demand. Passing `include_composio_helper_actions=true` in the URL will include Composio's helper actions, and the agent will guide the user through authentication on demand.
fern/pages/src/mcp/introduction.mdx
+1
-1
@@ -255,7 +255,7 @@ const updatedServer = await composio.mcp.update(
255
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
256
}
257
],
258
- { useComposioManagedAuth: true }
258
+ { isChatAuth: true }
259
);
260
```
261
ts/docs/api/mcp.md
+6
-6
@@ -29,7 +29,7 @@ const server = await composio.mcp.create(
29
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
30
}
31
],
32
- { useComposioManagedAuth: true }
32
+ { isChatAuth: true }
33
);
34
35
// Create an MCP server with multiple toolkits
@@ -63,7 +63,7 @@ const urls = await server.getServer({
63
- `authConfigId`: The auth configuration ID to use
64
- `allowedTools`: Array of specific tool IDs to expose
65
- `authOptions` (MCPAuthOptions): Optional authentication options
66
- - `useComposioManagedAuth`: Whether to use Composio-managed authentication
66
+ - `isChatAuth`: Whether to use Composio-managed authentication
67
68
**Returns:** Promise<McpServerCreateResponse> - Created server details with convenience `getServer` method
69
@@ -91,7 +91,7 @@ const userUrls = await composio.mcp.getServer("server-uuid", {
91
const customAuthUrls = await composio.mcp.getServer(
92
"server-uuid",
93
{ userId: "user_123" },
94
- { useComposioManagedAuth: false }
94
+ { isChatAuth: false }
95
);
96
```
97
@@ -173,7 +173,7 @@ const updatedServer = await composio.mcp.update(
173
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GMAIL_CREATE_DRAFT"]
174
}
175
],
176
- { useComposioManagedAuth: true }
176
+ { isChatAtuh: true }
177
);
178
```
179
@@ -286,7 +286,7 @@ interface MCPToolkitConfig {
286
287
```typescript
288
interface MCPAuthOptions {
289
- useComposioManagedAuth?: boolean; // Use Composio-managed authentication
289
+ isChatAuth?: boolean; // Use Composio-managed authentication
290
}
291
```
292
@@ -364,7 +364,7 @@ const mcpServer = await composio.mcp.create(
364
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
365
}
366
],
367
- { useComposioManagedAuth: true }
367
+ { isChatAuth: true }
368
);
369
370
// Get server URLs for connected accounts
ts/docs/core-concepts.md
+1
-1
@@ -349,7 +349,7 @@ const mcpServer = await composio.mcp.create(
349
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
350
}
351
],
352
- { useComposioManagedAuth: true }
352
+ { isChatAuth: true }
353
);
354
355
// Get server URLs for AI agent to connect
ts/examples/anthropic/src/mcp.ts
+1
-1
@@ -41,7 +41,7 @@ async function main() {
41
]
42
}
43
],
44
- { useComposioManagedAuth: true }
44
+ { isChatAuth: true }
45
);
46
47
console.log(`✅ MCP server created: ${mcpConfig.id}`);
ts/examples/mastra/src/mcp.ts
+1
-1
@@ -39,7 +39,7 @@ const mcpConfig = await composio.mcp.create(
39
]
40
}
41
],
42
- { useComposioManagedAuth: true }
42
+ { isChatAuth: true }
43
);
44
45
console.log(`✅ MCP server created: ${mcpConfig.id}`);
ts/packages/core/src/models/MCP.ts
+68
-99
@@ -1,8 +1,6 @@
1
/**
2
* @fileoverview MCP class for Composio SDK, used to manage MCP servers.
3
*
4
- * @author Apoorv Taneja <apoorv@composio.dev>
5
- * @date 2025-06-12
4
* @module MCP
5
*/
6
import ComposioClient from '@composio/client';
@@ -13,7 +11,6 @@ import {
11
MCPGetServerParams,
12
MCPToolkitConfigsArraySchema,
13
MCPAuthOptionsSchema,
16
- MCPGetServerParamsSchema,
14
ComposioCustomCreateResponseSchema,
15
ComposioMcpListResponseSchema,
16
McpRetrieveResponseSchema,
@@ -35,10 +32,7 @@ import {
32
McpUserConnectionStatus,
33
ConnectionStatus,
34
} from '../types/mcp.types';
38
-import {
39
- CustomCreateResponse as CustomCreateResponseRaw,
40
- GenerateURLParams as GenerateURLParamsRaw,
41
-} from '@composio/client/resources/mcp';
35
+import { CustomCreateResponse as CustomCreateResponseRaw } from '@composio/client/resources/mcp';
36
import { ValidationError } from '../errors/ValidationErrors';
37
import { BaseComposioProvider } from '../provider/BaseProvider';
38
import {
@@ -107,15 +101,13 @@ export class MCP<T = McpServerGetResponse> {
101
*
102
* @example
103
* ```typescript
110
- * const server = await composio.mcp.create({
111
- * serverConfig: [
104
+ * const server = await composio.mcp.create("personal-mcp-server", [
105
* {
106
* authConfigId: "ac_xyz",
107
* allowedTools: ["GMAIL_FETCH_EMAILS", "SLACK_SEND_MESSAGE"]
108
* }
109
* ],
117
- * options: {
118
- * name: "personal-mcp-server",
110
+ * {
111
* isChatAuth: true
112
* }
113
* });
@@ -126,20 +118,16 @@ export class MCP<T = McpServerGetResponse> {
118
* });
119
* ```
120
*/
129
- async create({
130
- name,
131
- serverConfig,
132
- options,
133
- }: {
134
- name: string;
121
+ async create(
122
+ name: string,
123
serverConfig: Array<{
124
authConfigId: string;
125
allowedTools: string[];
138
- }>;
126
+ }>,
127
options: {
128
isChatAuth?: boolean;
141
- };
142
- }): Promise<McpServerCreateResponse<T>> {
129
+ }
130
+ ): Promise<McpServerCreateResponse<T>> {
131
// Validate inputs using Zod schemas
132
if (!serverConfig || serverConfig.length === 0) {
133
throw new ValidationError('At least one auth config is required', {});
@@ -236,10 +224,7 @@ export class MCP<T = McpServerGetResponse> {
224
* @example
225
* ```typescript
226
* // Check if user can access an MCP server with Gmail and Slack toolkits
239
- * const connectionStatus = await composio.mcp.getUserConnectionStatus({
240
- * id: 'mcp-server-uuid',
241
- * userId: 'user123'
242
- * });
227
+ * const connectionStatus = await composio.mcp.getUserConnectionStatus('user123', 'mcp-server-uuid');
228
*
229
* if (connectionStatus.connected) {
230
* console.log('User can access all required toolkits');
@@ -277,18 +262,15 @@ export class MCP<T = McpServerGetResponse> {
262
* }
263
* ```
264
*/
280
- async getUserConnectionStatus({
281
- id,
282
- userId,
283
- }: {
284
- id: string;
285
- userId: string;
286
- }): Promise<McpUserConnectionStatus> {
287
- const serverDetails = await this.get(id);
265
+ async getUserConnectionStatus(
266
+ userId: string,
267
+ serverId: string
268
+ ): Promise<McpUserConnectionStatus> {
269
+ const serverDetails = await this.get(serverId);
270
271
if (!serverDetails.toolkits || serverDetails.toolkits.length === 0) {
272
throw new ValidationError('MCP server has no toolkits configured', {
291
- meta: { serverId: id },
273
+ meta: { serverId: serverId },
274
});
275
}
276
@@ -342,14 +324,14 @@ export class MCP<T = McpServerGetResponse> {
324
}
325
}
326
345
- async getConnectionParams({
346
- id,
347
- toolkit,
348
- }: {
349
- id: string;
350
- toolkit: string;
351
- }): Promise<ToolkitAuthFieldsResponse> {
352
- const mcpServerDetails = await this.get(id);
327
+ /**
328
+ * Get the connection parameters for a toolkit
329
+ * @param {string} serverId - The UUID of the MCP server
330
+ * @param {string} toolkit - The toolkit to get connection parameters for
331
+ * @returns {Promise<ToolkitAuthFieldsResponse>} Connection parameters for the toolkit
332
+ */
333
+ async getConnectionParams(serverId: string, toolkit: string): Promise<ToolkitAuthFieldsResponse> {
334
+ const mcpServerDetails = await this.get(serverId);
335
const authConfigs = mcpServerDetails.authConfigIds
336
? await Promise.all(
337
mcpServerDetails.authConfigIds.map(id => this.client.authConfigs.retrieve(id))
@@ -359,7 +341,7 @@ export class MCP<T = McpServerGetResponse> {
341
const authConfig = authConfigs.find(config => config.toolkit.slug === toolkit);
342
if (!authConfig) {
343
throw new ValidationError('Auth config not found', {
362
- meta: { serverId: id, toolkit },
344
+ meta: { serverId: serverId, toolkit },
345
});
346
}
347
@@ -370,63 +352,50 @@ export class MCP<T = McpServerGetResponse> {
352
return connectionParams;
353
}
354
373
- async authorize({
374
- id,
375
- userId,
376
- toolkit,
377
- }: {
378
- id: string;
379
- userId: string;
380
- toolkit: string;
381
- }): Promise<ConnectionRequest> {
382
- const mcpServerDetails = await this.get(id);
355
+ /**
356
+ * Authorize a user for a toolkit
357
+ * @param {string} serverId - The UUID of the MCP server
358
+ * @param {string} userId - The ID of the user to authorize
359
+ * @param {string} toolkit - The toolkit to authorize
360
+ * @returns {Promise<ConnectionRequest>} Connection request for the toolkit
361
+ */
362
+ async authorize(userId: string, serverId: string, toolkit: string): Promise<ConnectionRequest> {
363
+ const mcpServerDetails = await this.get(serverId);
364
const authConfigId = mcpServerDetails.authConfigIds?.[0];
365
return this.toolkits.authorize(userId, toolkit, authConfigId);
366
}
367
368
/**
369
* Get server URLs for an existing MCP server
389
- * @param {Object} params - Parameters for getting server URLs
390
- * @param {string} params.id - Server UUID
391
- * @param {string} params.userId - User ID to get server URLs for
392
- * @param {Object} [params.options] - Additional options for server configuration
393
- * @param {string[]} [params.options.limitTools] - Subset of tools to limit (from MCP config)
394
- * @param {boolean} [params.options.isChatAuth] - Whether to use chat-based authentication
370
+ * @param {string} serverId - Server UUID
371
+ * @param {string} userId - User ID to get server URLs for
372
+ * @param {Object} [options] - Additional options for server configuration
373
+ * @param {string[]} [options.limitTools] - Subset of tools to limit (from MCP config)
374
+ * @param {boolean} [options.isChatAuth] - Whether to use chat-based authentication
375
* @returns {Promise<T>} Transformed server URLs in provider-specific format
376
*
377
* @example
378
* ```typescript
379
* // Get URLs for an existing server with basic user ID
400
- * const urls = await composio.mcp.getServer({
401
- * id: "mcp_xyz",
402
- * userId: "hey@example.com"
403
- * });
380
+ * const urls = await composio.mcp.getServer("mcp_xyz", "hey@example.com");
381
*
382
* // Get URLs with additional options
406
- * const urls = await composio.mcp.getServer({
407
- * id: "mcp_xyz",
408
- * userId: "hey@example.com",
409
- * options: {
410
- * limitTools: ["GMAIL_FETCH_EMAILS", "SLACK_SEND_MESSAGE"],
411
- * isChatAuth: true
412
- * }
383
+ * const urls = await composio.mcp.getServer("mcp_xyz", "hey@example.com", {
384
+ * limitTools: ["GMAIL_FETCH_EMAILS", "SLACK_SEND_MESSAGE"],
385
+ * isChatAuth: true
386
* });
387
* ```
388
*/
416
- async getServer({
417
- id,
418
- userId,
419
- options,
420
- }: {
421
- id: string;
422
- userId: string;
389
+ async getServer(
390
+ serverId: string,
391
+ userId: string,
392
options?: {
393
limitTools?: string[];
394
isChatAuth?: boolean;
426
- };
427
- }): Promise<T> {
395
+ }
396
+ ): Promise<T> {
397
// Get server details first
429
- const serverDetails = await this.get(id);
398
+ const serverDetails = await this.get(serverId);
399
400
// Validate userId is provided
401
if (!userId) {
@@ -550,7 +519,7 @@ export class MCP<T = McpServerGetResponse> {
519
520
/**
521
* Get details of a specific MCP server
553
- * @param {string} id - Server UUID
522
+ * @param {string} serverId - Server UUID
523
* @returns {Promise<McpRetrieveResponse>} Server details
524
*
525
* @example
@@ -558,11 +527,11 @@ export class MCP<T = McpServerGetResponse> {
527
* const serverDetails = await composio.mcp.get('server-uuid');
528
* ```
529
*/
561
- async get(id: string): Promise<McpRetrieveResponse> {
530
+ async get(serverId: string): Promise<McpRetrieveResponse> {
531
// Retrieve MCP server with error handling
532
let retrieveResponse;
533
try {
565
- retrieveResponse = await this.client.mcp.retrieve(id);
534
+ retrieveResponse = await this.client.mcp.retrieve(serverId);
535
} catch (error) {
536
throw new ValidationError('Failed to retrieve MCP server', {
537
cause: error,
@@ -583,7 +552,7 @@ export class MCP<T = McpServerGetResponse> {
552
553
/**
554
* Delete an MCP server
586
- * @param {string} id - Server UUID
555
+ * @param {string} serverId - Server UUID
556
* @returns {Promise<McpDeleteResponse>} Deletion response
557
*
558
* @example
@@ -591,11 +560,11 @@ export class MCP<T = McpServerGetResponse> {
560
* const result = await composio.mcp.delete('server-uuid');
561
* ```
562
*/
594
- async delete(id: string): Promise<McpDeleteResponse> {
563
+ async delete(serverId: string): Promise<McpDeleteResponse> {
564
// Delete MCP server with error handling
565
let deleteResponse;
566
try {
598
- deleteResponse = await this.client.mcp.delete(id);
567
+ deleteResponse = await this.client.mcp.delete(serverId);
568
} catch (error) {
569
throw new ValidationError('Failed to delete MCP server', {
570
cause: error,
@@ -635,13 +604,13 @@ export class MCP<T = McpServerGetResponse> {
604
* },
605
* ],
606
* {
638
- * useComposioManagedAuth: true,
607
+ * isChatAuth: true,
608
* }
609
* );
610
* ```
611
*/
612
async update(
644
- id: string,
613
+ serverId: string,
614
name: string,
615
toolkitConfigs: MCPToolkitConfig[],
616
authOptions?: MCPAuthOptions
@@ -654,11 +623,11 @@ export class MCP<T = McpServerGetResponse> {
623
// Update MCP server with error handling
624
let updateResponse;
625
try {
657
- updateResponse = await this.client.mcp.update(id, {
626
+ updateResponse = await this.client.mcp.update(serverId, {
627
name,
628
toolkits: toolkits,
629
allowed_tools: toolkitConfigs.flatMap(config => config.allowedTools),
661
- managed_auth_via_composio: authOptions?.useComposioManagedAuth || false,
630
+ managed_auth_via_composio: authOptions?.isChatAuth || false,
631
});
632
} catch (error) {
633
throw new ValidationError('Failed to update MCP server', {
@@ -680,20 +649,20 @@ export class MCP<T = McpServerGetResponse> {
649
650
/**
651
* Generate URL for an MCP server
652
+ * @param {string} serverId - Server UUID
653
* @param {GenerateURLParams} params - Parameters for URL generation
654
* @returns {Promise<GenerateURLResponse>} Generated URL response
655
*
656
* @example
657
* ```typescript
688
- * const urlResponse = await composio.mcp.generateUrl({
658
+ * const urlResponse = await composio.mcp.generateUrl('server-uuid', {
659
* userIds: ['user123'],
660
* connectedAccountIds: ['account456'],
691
- * mcpServerId: 'server-uuid',
692
- * composioManagedAuth: true
661
+ * isChatAuth: true
662
* });
663
* ```
664
*/
696
- async generateUrl(params: GenerateURLParams): Promise<GenerateURLResponse> {
665
+ async generateUrl(serverId: string, params: GenerateURLParams): Promise<GenerateURLResponse> {
666
// Validate parameters using Zod schema (snake_case)
667
const paramsResult = GenerateURLParamsSchema.safeParse(params);
668
if (paramsResult.error) {
@@ -706,7 +675,7 @@ export class MCP<T = McpServerGetResponse> {
675
let urlResponse;
676
try {
677
urlResponse = await this.client.mcp.generate.url({
709
- mcp_server_id: params.mcpServerId,
678
+ mcp_server_id: serverId,
679
user_ids: params.userIds,
680
connected_account_ids: params.connectedAccountIds,
681
managed_auth_by_composio: params.composioManagedAuth,
@@ -806,8 +775,8 @@ export class MCP<T = McpServerGetResponse> {
775
* const serverDetails = await composio.mcp.getByName('my-gmail-server');
776
* ```
777
*/
809
- async getByName(name: string): Promise<McpRetrieveResponse> {
810
- if (!name) {
778
+ async getByName(serverName: string): Promise<McpRetrieveResponse> {
779
+ if (!serverName) {
780
throw new ValidationError('Server name is required', {});
781
}
782
@@ -815,7 +784,7 @@ export class MCP<T = McpServerGetResponse> {
784
let listResponse;
785
try {
786
listResponse = await this.client.mcp.list({
818
- name: name,
787
+ name: serverName,
788
limit: 10,
789
});
790
} catch (error) {
@@ -835,8 +804,8 @@ export class MCP<T = McpServerGetResponse> {
804
const servers = listResponse.items || [];
805
806
if (servers.length === 0) {
838
- throw new ValidationError(`MCP server with name '${name}' not found`, {
839
- meta: { serverName: name },
807
+ throw new ValidationError(`MCP server with name '${serverName}' not found`, {
808
+ meta: { serverName: serverName },
809
});
810
}
811
ts/packages/core/src/types/mcp.types.ts
+3
-3
@@ -28,7 +28,7 @@ export const MCPToolkitConfigsArraySchema = z
28
}, 'Duplicate toolkits are not allowed. Each toolkit must be unique.');
29
30
export const MCPAuthOptionsSchema = z.object({
31
- useComposioManagedAuth: z.boolean().optional(),
31
+ isChatAuth: z.boolean().optional(),
32
});
33
34
export type MCPAuthOptions = z.infer<typeof MCPAuthOptionsSchema>;
@@ -59,13 +59,13 @@ export type MCPInstanceParams = {
59
serverId: string;
60
userIds?: string[];
61
connectedAccountIds?: string[];
62
- useComposioManagedAuth?: boolean;
62
+ isChatAuth?: boolean;
63
};
64
65
export const MCPGenerateURLParamsSchema = z.object({
66
userIds: z.array(z.string()).optional(),
67
connectedAccountIds: z.array(z.string()).optional(),
68
- useComposioManagedAuth: z.boolean().optional(),
68
+ isChatAuth: z.boolean().optional(),
69
});
70
export type MCPGenerateURLParams = z.infer<typeof MCPGenerateURLParamsSchema>;
71
ts/packages/core/test/models/mcp.test.ts
+1
-1
@@ -527,7 +527,7 @@ describe('MCP', () => {
527
mockClient.mcp.update.mockResolvedValue(mockUpdateResponse);
528
529
const result = await mcp.update('mcp_123', 'updated-server', updatedConfigs, {
530
- useComposioManagedAuth: true,
530
+ isChatAuth: true,
531
});
532
533
expect(mockClient.mcp.update).toHaveBeenCalledWith('mcp_123', {