@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 413 lines 9.92 KB
Rendered Raw
1 # MCP API
2
3 The MCP (Model Control Protocol) API provides advanced server management capabilities for creating, configuring, and managing MCP servers with enhanced features.
4
5 ## Overview
6
7 The MCP class offers comprehensive CRUD operations for MCP servers, including:
8
9 - Creating custom MCP configurations with toolkit-specific settings
10 - Listing and filtering servers with pagination
11 - Retrieving detailed server information
12 - Updating server configurations
13 - Deleting servers
14 - Managing server instances for users
15
16 ## Getting Started
17
18 ```typescript
19 import { Composio } from '@composio/core';
20
21 const composio = new Composio();
22 const userId = "xxx-oooo-xxx";
23
24 // create an MCP Server Config
25 const server = await composio.mcp.create('my-mcp-server', {
26 toolkits: [
27 {
28 toolkit: 'slack',
29 authConfigId: 'ac_12324343',
30 allowedTools: ['SLACK_SEND_MESSAGE'],
31 },
32 ],
33 });
34
35 // get an instance for a user
36 const mcp = await server.generate(userId);
37
38 // using the global api
39 const mcp = await composio.mcp.generate(userId, server.id);
40
41 /** mcp
42 * {
43 * ...
44 * id: "serverid",
45 * url: "mcp-server.com/mcp",
46 * ...
47 * }
48 * /
49
50 // use the mcp with your mcp-client
51 ```
52
53 ## Methods
54
55 ### create(name, config)
56
57 Creates a new MCP server configuration with specified toolkits and authentication settings.
58
59 **Parameters:**
60
61 - `name` (string): Unique name for the MCP configuration
62 - `config` (MCPConfigCreationParams): Configuration object containing:
63 - `toolkits` (Array): Array of toolkit configurations
64 - `toolkit` (string, optional): Toolkit identifier (e.g., "github", "slack")
65 - `authConfigId` (string, optional): Auth configuration ID
66 - `allowedTools` (string[], optional): Specific tools to enable
67 - `manuallyManageConnections` (boolean, optional): Whether to manually manage account connections (default: false)
68
69 **Returns:** `Promise<MCPConfigCreateResponse>`
70
71 **Example:**
72
73 ```typescript
74 const server = await composio.mcp.create('personal-mcp-server', {
75 toolkits: [
76 {
77 toolkit: 'github',
78 authConfigId: 'ac_xyz',
79 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
80 },
81 {
82 toolkit: 'slack',
83 authConfigId: 'ac_abc',
84 allowedTools: ['SLACK_SEND_MESSAGE'],
85 },
86 ],
87 manuallyManageConnections: false,
88 });
89
90 // Get server instance for a user
91 const mcp = await server.generate('user_12345');
92 ```
93
94 ### list(options)
95
96 Lists MCP servers with optional filtering and pagination.
97
98 **Parameters:**
99
100 - `options` (MCPListParams): Filtering and pagination options
101 - `page` (number, optional): Page number for pagination (default: 1)
102 - `limit` (number, optional): Maximum items per page (default: 10)
103 - `toolkits` (string[], optional): Filter by toolkit names
104 - `authConfigs` (string[], optional): Filter by auth configuration IDs
105 - `name` (string, optional): Filter by server name (partial match)
106
107 **Returns:** `Promise<MCPListResponse>`
108
109 **Example:**
110
111 ```typescript
112 // List all servers
113 const allServers = await composio.mcp.list({});
114
115 // Paginated listing
116 const pagedServers = await composio.mcp.list({
117 page: 2,
118 limit: 5,
119 });
120
121 // Filter by toolkit
122 const githubServers = await composio.mcp.list({
123 toolkits: ['github', 'slack'],
124 });
125
126 // Filter by name
127 const personalServers = await composio.mcp.list({
128 name: 'personal',
129 });
130 ```
131
132 ### get(serverId)
133
134 Retrieves detailed information about a specific MCP server/config.
135
136 **Parameters:**
137
138 - `serverId` (string): The unique identifier of the MCP server/config
139
140 **Returns:** `Promise<MCPItem>`
141
142 **Example:**
143
144 ```typescript
145 const server = await composio.mcp.get('mcp_12345');
146
147 console.log(server.name); // "My Personal MCP Server"
148 console.log(server.allowedTools); // ["GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE"]
149 console.log(server.toolkits); // ["github", "slack"]
150 console.log(server.serverInstanceCount); // 3
151
152 // Access setup commands for different clients
153 console.log(server.commands.claude); // Claude setup command
154 console.log(server.commands.cursor); // Cursor setup command
155 console.log(server.commands.windsurf); // Windsurf setup command
156 ```
157
158 ### update(serverId, config)
159
160 Updates an existing MCP server configuration.
161
162 **Parameters:**
163
164 - `serverId` (string): The unique identifier of the MCP server to update
165 - `config` (MCPUpdateParams): Update configuration parameters
166 - `name` (string, optional): New server name
167 - `toolkits` (Array, optional): Updated toolkit configurations
168 - `manuallyManageConnections` (boolean, optional): Connection management setting
169
170 **Returns:** `Promise<MCPItem>`
171
172 **Example:**
173
174 ```typescript
175 // Update server name only
176 const updatedServer = await composio.mcp.update('mcp_12345', {
177 name: 'My Updated MCP Server',
178 });
179
180 // Update toolkits and tools
181 const serverWithNewTools = await composio.mcp.update('mcp_12345', {
182 toolkits: [
183 {
184 toolkit: 'github',
185 authConfigId: 'auth_abc123',
186 allowedTools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_LIST_REPOS'],
187 },
188 {
189 toolkit: 'slack',
190 authConfigId: 'auth_xyz789',
191 allowedTools: ['SLACK_SEND_MESSAGE', 'SLACK_LIST_CHANNELS'],
192 },
193 ],
194 });
195
196 // Complete update
197 const fullyUpdatedServer = await composio.mcp.update('mcp_12345', {
198 name: 'Production MCP Server',
199 toolkits: [
200 {
201 toolkit: 'gmail',
202 authConfigId: 'auth_gmail_prod',
203 allowedTools: ['GMAIL_SEND_EMAIL', 'GMAIL_FETCH_EMAILS'],
204 },
205 ],
206 manuallyManageConnections: false,
207 });
208 ```
209
210 ### delete(serverId)
211
212 Permanently deletes an MCP server configuration.
213
214 **Parameters:**
215
216 - `serverId` (string): The unique identifier of the MCP server to delete
217
218 **Returns:** `Promise<{id: string; deleted: boolean}>`
219
220 **Example:**
221
222 ```typescript
223 // Delete a server
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 } else {
229 console.log(`Failed to delete server ${result.id}`);
230 }
231
232 // With error handling
233 try {
234 const result = await composio.mcp.delete('mcp_12345');
235 console.log('Deletion successful:', result);
236 } catch (error) {
237 console.error('Failed to delete MCP server:', error.message);
238 }
239
240 // Verify deletion
241 await composio.mcp.delete('mcp_12345');
242 const servers = await composio.mcp.list({});
243 const serverExists = servers.items.some(server => server.id === 'mcp_12345');
244 console.log('Server still exists:', serverExists); // Should be false
245 ```
246
247 ### generate(userId, mcpConfigId, options?)
248
249 Creates a server instance for a specific user.
250
251 **Parameters:**
252
253 - `userId` (string): External user ID from your database
254 - `mcpConfigId` (string): MCP configuration ID
255 - `options` (MCPGetInstanceParams, optional): Additional options
256 - `manuallyManageConnections` (boolean, optional): Whether to manually manage connections
257
258 **Returns:** `Promise<MCPServerInstance>`
259
260 **Example:**
261
262 ```typescript
263 const mcp = await composio.mcp.generate('user_12345', 'mcp_67890', {
264 manuallyManageConnections: false,
265 });
266
267 console.log(mcp.url); // Server URL for the user
268 console.log(mcp.allowedTools); // Available tools
269 ```
270
271 ## Data Types
272
273 ### MCPItem
274
275 Complete MCP server information including:
276
277 - `id`: Unique server identifier
278 - `name`: Human-readable server name
279 - `allowedTools`: Array of enabled tool identifiers
280 - `authConfigIds`: Array of auth configuration IDs
281 - `toolkits`: Array of toolkit names
282 - `commands`: Setup commands for different clients (Claude, Cursor, Windsurf)
283 - `MCPUrl`: Server connection URL
284 - `toolkitIcons`: Map of toolkit icons
285 - `serverInstanceCount`: Number of active instances
286
287 ### MCPListResponse
288
289 Paginated list response containing:
290
291 - `items`: Array of MCPItem objects
292 - `currentPage`: Current page number
293 - `totalPages`: Total number of pages
294
295 ### MCPServerInstance
296
297 User-specific server instance containing:
298
299 - `id`: Server identifier
300 - `name`: Server name
301 - `type`: Connection type (always 'streamable_http')
302 - `url`: User-specific connection URL
303 - `userId`: Associated user ID
304 - `allowedTools`: Available tools for the user
305 - `authConfigs`: Associated auth configurations
306
307 ## Error Handling
308
309 All methods can throw the following exceptions:
310
311 - **ValidationError**: When input parameters are invalid or malformed
312 - **Error**: When API operations fail (server not found, network issues, etc.)
313
314 ### Example Error Handling
315
316 ```typescript
317 try {
318 const server = await composio.mcp.create('test-server', config);
319 } catch (error) {
320 if (error instanceof ValidationError) {
321 console.error('Invalid configuration:', error.message);
322 } else {
323 console.error('API error:', error.message);
324 }
325 }
326 ```
327
328 ## Best Practices
329
330 ### 1. Server Naming
331
332 Use descriptive, unique names for your MCP servers:
333
334 ```typescript
335 // Good
336 'production-github-slack-server';
337 'dev-testing-environment';
338 'user-personal-tools';
339
340 // Avoid
341 'server1';
342 'test';
343 'mcp';
344 ```
345
346 ### 2. Toolkit Configuration
347
348 Be specific about allowed tools to maintain security:
349
350 ```typescript
351 // Specific tools (recommended)
352 {
353 toolkit: "github",
354 allowedTools: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_LIST_REPOS"]
355 }
356
357 // Avoid allowing all tools unless necessary
358 {
359 toolkit: "github"
360 // No allowedTools = all tools enabled
361 }
362 ```
363
364 ### 3. Connection Management
365
366 Choose the appropriate connection management strategy:
367
368 ```typescript
369 // For chat based agents
370 {
371 manuallyManageConnections: false;
372 }
373
374 // For background agents, where you have to pre connect all the accounts
375 {
376 manuallyManageConnections: true;
377 }
378 ```
379
380 ### 4. Pagination
381
382 Use pagination for large server lists:
383
384 ```typescript
385 let page = 1;
386 let allServers = [];
387
388 while (true) {
389 const response = await composio.mcp.list({
390 page,
391 limit: 50,
392 });
393
394 allServers.push(...response.items);
395
396 if (page >= response.totalPages) break;
397 page++;
398 }
399 ```
400
401 ## Limitations
402 - Toolkit updates replace the entire configuration (no merging)
403 - Deleted servers cannot be recovered
404 - Server instances are tied to specific user IDs
405
406 ## Support
407
408 For issues with the MCP API:
409
410 1. Check the error message for validation issues
411 2. Verify your server configurations are valid
412 3. Ensure you have proper permissions for the requested operations
413 4. Contact support with specific error details and reproduction steps