@devries-cameron20 / composio Mirror · read-only / commits / f2caa0fbe
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 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