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
fix
Utkarsh Dixit committed
Jul 10, 2025 at 11:43 UTC
f2caa0fbe00c29622621e2b21a2a6b629904d88e
2 files changed
+125
-137
fern/pages/src/mcp/developers.mdx
+37
-36
@@ -11,6 +11,10 @@ hide-nav-links: true
11
Composio MCP lets you build custom MCP servers that your users can connect to and use to perform actions.
12
You can manage these servers via our [Dashboard](https://app.composio.dev), or use the [SDK/API](/api-reference/mcp) for greater control and flexibility.
13
14
+<Note>
15
+The MCP SDK has been updated to use positional parameters instead of object parameters for better performance and simpler usage. All examples below reflect the latest API structure.
16
+</Note>
17
+
18
## Creating MCP Servers and Onboarding End Users
19
<Steps>
20
<Step title="Configure Authentication">
@@ -32,9 +36,9 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
36
});
37
38
// Create an MCP server with the new API structure
35
- const mcpConfig = await composio.mcp.create({
36
- name: "Gmail MCP Server",
37
- serverConfig: [
39
+ const mcpConfig = await composio.mcp.create(
40
+ "Gmail MCP Server",
41
+ [
42
{
43
authConfigId: "ac_auth_12", // Your auth config ID
44
allowedTools: [
@@ -44,10 +48,10 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
48
]
49
}
50
],
47
- options: {
51
+ {
52
isChatAuth: true // Enable chat-based authentication
53
}
50
- });
54
+ );
55
56
console.log(`✅ MCP server created: ${mcpConfig.id}`);
57
console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
@@ -57,24 +61,21 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
61
**Using the SDK:**
62
```typescript
63
// Get server URLs for a specific user
60
- const serverUrls = await composio.mcp.getServer({
61
- id: mcpConfig.id,
62
- userId: "user123@example.com",
63
- options: {
64
- limitTools: ["GMAIL_FETCH_EMAILS"], // Optional: limit to specific tools
65
- isChatAuth: true
66
- }
67
- });
64
+ const serverUrls = await composio.mcp.getServer(
65
+ mcpConfig.id,
66
+ "user123@example.com"
67
+ );
68
69
console.log("Server URLs:", serverUrls);
70
```
71
72
- **Using the convenience method (from create response):**
72
+ **Using the server ID (from create response):**
73
```typescript
74
- // Use the convenience method on the created server
75
- const serverUrls = await mcpConfig.getServer({
76
- userId: "user123@example.com"
77
- });
74
+ // Get server URLs using the created server ID
75
+ const serverUrls = await composio.mcp.getServer(
76
+ mcpConfig.id,
77
+ "user123@example.com"
78
+ );
79
```
80
</Step>
81
<Step title="Client applications connect to the server">
@@ -102,10 +103,10 @@ Before using an MCP server, you can check if a user has the necessary connected
103
104
```typescript
105
// Check if a user has connected accounts for all required toolkits
105
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
106
- id: mcpConfig.id,
107
- userId: "user123@example.com"
108
-});
106
+const connectionStatus = await composio.mcp.getUserConnectionStatus(
107
+ "user123@example.com",
108
+ mcpConfig.id
109
+);
110
111
console.log("Overall connection status:", connectionStatus.connected);
112
console.log("Individual toolkit status:", connectionStatus.connectedToolkits);
@@ -169,17 +170,17 @@ Authenticate users upfront via the Composio SDK/API before they use the MCP serv
170
171
```typescript
172
// Check what authentication is needed
172
-const authParams = await composio.mcp.getConnectionParams({
173
- id: mcpConfig.id,
174
- toolkit: "gmail"
175
-});
173
+const authParams = await composio.mcp.getConnectionParams(
174
+ mcpConfig.id,
175
+ "gmail"
176
+);
177
178
// Initiate authentication for a user
178
-const authRequest = await composio.mcp.authorize({
179
- id: mcpConfig.id,
180
- userId: "user123@example.com",
181
- toolkit: "gmail"
182
-});
179
+const authRequest = await composio.mcp.authorize(
180
+ "user123@example.com",
181
+ mcpConfig.id,
182
+ "gmail"
183
+);
184
185
if (authRequest.redirectUrl) {
186
console.log("Please complete authentication:", authRequest.redirectUrl);
@@ -191,10 +192,10 @@ if (authRequest.redirectUrl) {
192
Let the agent authenticate users on-demand by including helper actions:
193
194
```typescript
194
-const serverUrls = await composio.mcp.getServer({
195
- id: mcpConfig.id,
196
- userId: "user123@example.com"
197
-});
195
+const serverUrls = await composio.mcp.getServer(
196
+ mcpConfig.id,
197
+ "user123@example.com"
198
+);
199
200
// The server URLs will include helper actions that guide users through authentication
201
```
@@ -209,7 +210,7 @@ Pre-authentication is recommended for production applications as it provides bet
210
2. **Limit tools appropriately** - Only include the tools your users actually need.
211
3. **Check connection status** - Always verify user authentication before using server URLs.
212
4. **Handle authentication gracefully** - Provide clear instructions when users need to authenticate.
212
-5. **Use the convenience methods** - The `getServer` method on create responses simplifies URL generation.
213
+5. **Use the server ID** - Store the server ID from the create response for generating URLs.
214
215
<Warning>
216
SSE support is deprecated. If you're using `/sse` endpoints or `transport=sse` query parameters, migrate to the standard `/mcp` endpoints.
fern/pages/src/mcp/introduction.mdx
+88
-101
@@ -10,6 +10,10 @@ hide-nav-links: true
10
11
[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open protocol that standardizes how LLM-powered applications provide tools and context to underlying models. Composio MCP servers make all [Composio tools](/tools) available through this standardized protocol, enabling seamless integration with MCP-compatible clients.
12
13
+<Note>
14
+The MCP SDK has been updated to use positional parameters instead of object parameters for better performance and simpler usage. All examples below reflect the latest API structure.
15
+</Note>
16
+
17
## Key Features
18
19
- **🔧 1000+ Tools**: Access to all Composio tools through MCP
@@ -37,23 +41,24 @@ const composio = new Composio({
41
});
42
43
// Create an MCP server
40
-const mcpServer = await composio.mcp.create({
41
- name: "My Gmail Server",
42
- serverConfig: [
44
+const mcpServer = await composio.mcp.create(
45
+ "My Gmail Server",
46
+ [
47
{
48
authConfigId: "ac_your_auth_config_id",
49
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
50
}
51
],
48
- options: {
52
+ {
53
isChatAuth: true
54
}
51
-});
55
+);
56
57
// Get server URLs for a user
54
-const serverUrls = await mcpServer.getServer({
55
- userId: "user@example.com"
56
-});
58
+const serverUrls = await composio.mcp.getServer(
59
+ mcpServer.id,
60
+ "user@example.com"
61
+);
62
63
console.log("MCP Server URLs:", serverUrls);
64
```
@@ -62,10 +67,10 @@ console.log("MCP Server URLs:", serverUrls);
67
68
### Creating MCP Servers
69
65
-The `create` method uses named object arguments for clear, readable configuration:
70
+The `create` method uses positional parameters for better performance:
71
72
```typescript
68
-const mcpServer = await composio.mcp.create({
73
+const mcpServer = await composio.mcp.create(
74
name: string, // Unique server name
75
serverConfig: Array<{ // Auth configurations
76
authConfigId: string, // Your auth config ID
@@ -74,15 +79,15 @@ const mcpServer = await composio.mcp.create({
79
options: {
80
isChatAuth?: boolean // Enable chat-based auth (default: false)
81
}
77
-});
82
+);
83
```
84
85
**Complete Example:**
86
87
```typescript
83
-const mcpServer = await composio.mcp.create({
84
- name: "Multi-Service Productivity Server",
85
- serverConfig: [
88
+const mcpServer = await composio.mcp.create(
89
+ "Multi-Service Productivity Server",
90
+ [
91
{
92
authConfigId: "ac_gmail_config",
93
allowedTools: [
@@ -99,10 +104,10 @@ const mcpServer = await composio.mcp.create({
104
]
105
}
106
],
102
- options: {
107
+ {
108
isChatAuth: true
109
}
105
-});
110
+);
111
112
console.log(`✅ Server created: ${mcpServer.id}`);
113
console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
@@ -113,39 +118,26 @@ console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
118
The `getServer` method provides URLs for MCP clients to connect:
119
120
```typescript
116
-const serverUrls = await composio.mcp.getServer({
121
+const serverUrls = await composio.mcp.getServer(
122
id: string, // Server ID
118
- userId: string, // User identifier
119
- options?: {
120
- limitTools?: string[], // Subset of tools to include
121
- isChatAuth?: boolean // Override chat auth setting
122
- }
123
-});
123
+ userId: string // User identifier
124
+);
125
```
126
127
**Examples:**
128
129
```typescript
130
// Basic usage
130
-const basicUrls = await composio.mcp.getServer({
131
- id: "mcp_server_id",
132
- userId: "user123@example.com"
133
-});
134
-
135
-// With tool limitations
136
-const limitedUrls = await composio.mcp.getServer({
137
- id: "mcp_server_id",
138
- userId: "user123@example.com",
139
- options: {
140
- limitTools: ["GMAIL_FETCH_EMAILS"], // Only allow email fetching
141
- isChatAuth: false
142
- }
143
-});
131
+const basicUrls = await composio.mcp.getServer(
132
+ "mcp_server_id",
133
+ "user123@example.com"
134
+);
135
145
-// Using convenience method (from create response)
146
-const convenientUrls = await mcpServer.getServer({
147
- userId: "user123@example.com"
148
-});
136
+// Using server ID from create response
137
+const serverUrls = await composio.mcp.getServer(
138
+ mcpServer.id,
139
+ "user123@example.com"
140
+);
141
```
142
143
### Checking User Connection Status
@@ -153,10 +145,10 @@ const convenientUrls = await mcpServer.getServer({
145
Before using an MCP server, check if users have the required connected accounts:
146
147
```typescript
156
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
157
- id: string, // Server ID
158
- userId: string // User identifier
159
-});
148
+const connectionStatus = await composio.mcp.getUserConnectionStatus(
149
+ userId: string, // User identifier
150
+ id: string // Server ID
151
+);
152
153
// Returns: McpUserConnectionStatus
154
{
@@ -176,10 +168,10 @@ const connectionStatus = await composio.mcp.getUserConnectionStatus({
168
**Complete Example:**
169
170
```typescript
179
-const status = await composio.mcp.getUserConnectionStatus({
180
- id: mcpServer.id,
181
- userId: "user123@example.com"
182
-});
171
+const status = await composio.mcp.getUserConnectionStatus(
172
+ "user123@example.com",
173
+ mcpServer.id
174
+);
175
176
console.log(`Overall status: ${status.connected ? "✅ Ready" : "❌ Needs auth"}`);
177
@@ -190,17 +182,17 @@ if (!status.connected) {
182
console.log(`❌ ${toolkit} requires authentication`);
183
184
// Get authentication parameters
193
- const authParams = await composio.mcp.getConnectionParams({
194
- id: mcpServer.id,
185
+ const authParams = await composio.mcp.getConnectionParams(
186
+ mcpServer.id,
187
toolkit
196
- });
188
+ );
189
190
// Initiate authentication
199
- const authRequest = await composio.mcp.authorize({
200
- id: mcpServer.id,
201
- userId: "user123@example.com",
191
+ const authRequest = await composio.mcp.authorize(
192
+ "user123@example.com",
193
+ mcpServer.id,
194
toolkit
203
- });
195
+ );
196
197
if (authRequest.redirectUrl) {
198
console.log(`🔗 Authenticate here: ${authRequest.redirectUrl}`);
@@ -274,19 +266,19 @@ Authenticate users before they use the MCP server:
266
267
```typescript
268
// 1. Check what's needed
277
-const authParams = await composio.mcp.getConnectionParams({
278
- id: mcpServer.id,
279
- toolkit: "gmail"
280
-});
269
+const authParams = await composio.mcp.getConnectionParams(
270
+ mcpServer.id,
271
+ "gmail"
272
+);
273
274
console.log("Required fields:", authParams.required_fields);
275
276
// 2. Initiate authentication
285
-const authRequest = await composio.mcp.authorize({
286
- id: mcpServer.id,
287
- userId: "user@example.com",
288
- toolkit: "gmail"
289
-});
277
+const authRequest = await composio.mcp.authorize(
278
+ "user@example.com",
279
+ mcpServer.id,
280
+ "gmail"
281
+);
282
283
// 3. Direct user to authentication URL
284
if (authRequest.redirectUrl) {
@@ -294,10 +286,10 @@ if (authRequest.redirectUrl) {
286
}
287
288
// 4. Verify connection after user completes auth
297
-const finalStatus = await composio.mcp.getUserConnectionStatus({
298
- id: mcpServer.id,
299
- userId: "user@example.com"
300
-});
289
+const finalStatus = await composio.mcp.getUserConnectionStatus(
290
+ "user@example.com",
291
+ mcpServer.id
292
+);
293
294
if (finalStatus.connected) {
295
console.log("✅ All toolkits connected, ready to use!");
@@ -309,13 +301,10 @@ if (finalStatus.connected) {
301
Let the agent handle authentication on-demand:
302
303
```typescript
312
-const serverUrls = await composio.mcp.getServer({
313
- id: mcpServer.id,
314
- userId: "user@example.com",
315
- options: {
316
- isChatAuth: true // Include helper actions for authentication
317
- }
318
-});
304
+const serverUrls = await composio.mcp.getServer(
305
+ mcpServer.id,
306
+ "user@example.com"
307
+);
308
309
// The agent can now guide users through authentication as needed
310
```
@@ -338,9 +327,9 @@ async function setupGmailMCP(userId: string) {
327
} catch (error) {
328
// 2. Create new server if it doesn't exist
329
console.log("📦 Creating new Gmail server...");
341
- gmailServer = await composio.mcp.create({
342
- name: "Production Gmail Server",
343
- serverConfig: [
330
+ gmailServer = await composio.mcp.create(
331
+ "Production Gmail Server",
332
+ [
333
{
334
authConfigId: process.env.GMAIL_AUTH_CONFIG_ID!,
335
allowedTools: [
@@ -351,27 +340,27 @@ async function setupGmailMCP(userId: string) {
340
]
341
}
342
],
354
- options: {
343
+ {
344
isChatAuth: true
345
}
357
- });
346
+ );
347
}
348
349
// 3. Check user connection status
361
- const connectionStatus = await composio.mcp.getUserConnectionStatus({
362
- id: gmailServer.id,
363
- userId
364
- });
350
+ const connectionStatus = await composio.mcp.getUserConnectionStatus(
351
+ userId,
352
+ gmailServer.id
353
+ );
354
355
// 4. Handle authentication if needed
356
if (!connectionStatus.connected) {
357
console.log("🔐 User needs to authenticate with Gmail");
358
370
- const authRequest = await composio.mcp.authorize({
371
- id: gmailServer.id,
359
+ const authRequest = await composio.mcp.authorize(
360
userId,
373
- toolkit: "gmail"
374
- });
361
+ gmailServer.id,
362
+ "gmail"
363
+ );
364
365
return {
366
server: gmailServer,
@@ -381,12 +370,10 @@ async function setupGmailMCP(userId: string) {
370
}
371
372
// 5. Generate server URLs for MCP client
384
- const serverUrls = await gmailServer.getServer({
385
- userId,
386
- options: {
387
- limitTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
388
- }
389
- });
373
+ const serverUrls = await composio.mcp.getServer(
374
+ gmailServer.id,
375
+ userId
376
+ );
377
378
return {
379
server: gmailServer,
@@ -409,18 +396,18 @@ if (result.needsAuth) {
396
397
```typescript
398
try {
412
- const mcpServer = await composio.mcp.create({
413
- name: "Test Server",
414
- serverConfig: [
399
+ const mcpServer = await composio.mcp.create(
400
+ "Test Server",
401
+ [
402
{
403
authConfigId: "invalid_config",
404
allowedTools: ["INVALID_TOOL"]
405
}
406
],
420
- options: {
407
+ {
408
isChatAuth: true
409
}
423
- });
410
+ );
411
} catch (error) {
412
if (error instanceof ValidationError) {
413
console.error("Configuration error:", error.message);
@@ -439,7 +426,7 @@ try {
426
4. **Limit tools appropriately** - Only include tools your application actually needs
427
5. **Cache server configurations** - Reuse existing servers when possible
428
6. **Monitor connection health** - Regularly check and refresh user connections
442
-7. **Use the convenience methods** - The `getServer` method on create responses simplifies workflows
429
+7. **Store server IDs** - Keep track of server IDs from create responses for generating URLs
430
431
## Next Steps
432