@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, 03:37 UTC

next
mdx 524 lines 16.4 KB
Raw
1 ---
2 title: "MCP (Model Control Protocol) & Experimental ToolRouter"
3 description: "Comprehensive MCP support and experimental ToolRouter for isolated, scoped sessions"
4 date: "2025-09-26"
5 ---
6
7
8 Composio now introduces **comprehensive MCP (Model Control Protocol) support** and an **experimental ToolRouter** for creating isolated, scoped sessions with advanced toolkit management. These features enable seamless integration with modern AI frameworks and provide powerful session-based tool routing capabilities.
9
10 ### Why Use MCP & ToolRouter?
11
12 - **Framework Integration**: Native MCP support for Vercel AI, Mastra, OpenAI Agents, and LangChain
13 - **Session Isolation**: Create isolated sessions with specific toolkit configurations
14 - **Advanced Authentication**: Flexible auth config management per toolkit
15 - **Scoped Access**: Control which tools are available within each session
16 - **Multi-Service Workflows**: Route tool calls efficiently across different services
17 - **Development & Testing**: Perfect for testing and development with scoped MCP server access
18
19 ### TypeScript SDK (v0.1.53)
20
21 #### **Added: MCP API**
22
23 **Core MCP Features:**
24 - **MCP Server Creation**: Create and manage MCP server configurations
25 - **User-Specific URLs**: Generate unique MCP server URLs for individual users
26 - **Toolkit Configuration**: Support for multiple toolkits with custom auth configs
27 - **Tool Filtering**: Specify allowed tools per configuration
28 - **Connection Management**: Choose between manual and automatic account management
29
30 **Basic Usage:**
31
32 ```typescript
33 // @noErrors
34 import { Composio } from '@composio/core';
35
36 const composio = new Composio({
37 apiKey: process.env.COMPOSIO_API_KEY,
38 });
39
40 // Create MCP configuration
41 const mcpConfig = await composio.mcp.create('my-server-name', {
42 toolkits: [
43 { toolkit: 'github', authConfigId: 'ac_233434343' },
44 { toolkit: 'gmail', authConfigId: 'ac_567890123' }
45 ],
46 allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
47 manuallyManageConnections: false,
48 });
49
50 // Generate server instance for a user
51 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
52 console.log('MCP URL:', serverInstance.url);
53 ```
54
55 **Framework Integration Examples:**
56
57 ```typescript
58 // @noErrors
59 // Vercel AI Integration
60 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
61 import { experimental_createMCPClient as createMCPClient } from 'ai';
62
63 const mcpClient = await createMCPClient({
64 name: 'composio-mcp-client',
65 transport: new SSEClientTransport(new URL(serverInstance.url)),
66 });
67
68 // Mastra Integration
69 import { MCPClient as MastraMCPClient } from '@mastra/mcp';
70
71 const mcpClient = new MastraMCPClient({
72 servers: {
73 composio: { url: new URL(mcpSession.url) },
74 },
75 });
76
77 // OpenAI Agents Integration
78 import { hostedMcpTool } from '@openai/agents';
79
80 const tools = [
81 hostedMcpTool({
82 serverLabel: 'composio',
83 serverUrl: mcpSession.url,
84 }),
85 ];
86 ```
87
88 #### **Added: Experimental ToolRouter**
89
90 **Core ToolRouter Features:**
91 - **Session-Based Routing**: Create isolated sessions for specific users and toolkit combinations
92 - **Dynamic Configuration**: Configure toolkits and auth configs per session
93 - **MCP Server URLs**: Each session gets a unique MCP server endpoint
94 - **Flexible Toolkit Management**: Support for string names or detailed toolkit configurations
95 - **Connection Control**: Manual or automatic connection management per session
96
97 **Basic Usage:**
98
99 ```typescript
100 // @noErrors
101 // Create session with simple toolkit names
102 const session = await composio.experimental.toolRouter.createSession('user_123', {
103 toolkits: ['gmail', 'slack', 'github'],
104 });
105
106 // Create session with auth configs
107 const session = await composio.experimental.toolRouter.createSession('user_456', {
108 toolkits: [
109 { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
110 { toolkit: 'slack', authConfigId: 'ac_slack_team' },
111 { toolkit: 'github', authConfigId: 'ac_github_personal' },
112 ],
113 manuallyManageConnections: true,
114 });
115
116 console.log('Session ID:', session.sessionId);
117 console.log('MCP URL:', session.url);
118 ```
119
120 **Advanced Multi-Service Integration:**
121
122 ```typescript
123 // @noErrors
124 // Complex workflow session
125 const integrationSession = await composio.experimental.toolRouter.createSession('user_789', {
126 toolkits: [
127 { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
128 { toolkit: 'slack', authConfigId: 'ac_slack_team' },
129 { toolkit: 'github', authConfigId: 'ac_github_personal' },
130 { toolkit: 'notion', authConfigId: 'ac_notion_workspace' },
131 { toolkit: 'calendar', authConfigId: 'ac_gcal_primary' },
132 ],
133 });
134
135 // Use with any MCP client
136 const mcpClient = new MCPClient(integrationSession.url);
137 ```
138
139 **Framework-Specific Examples:**
140
141 ```typescript
142 // @noErrors
143 // Mastra Integration
144 const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
145 toolkits: ["gmail"],
146 manuallyManageConnections: true,
147 });
148
149 const agent = new MastraAgent({
150 name: 'Gmail Assistant',
151 model: openai('gpt-4o-mini'),
152 tools: await mcpClient.getTools(),
153 });
154
155 // OpenAI Agents Integration
156 const tools = [
157 hostedMcpTool({
158 serverLabel: 'composio tool router',
159 serverUrl: mcpSession.url,
160 requireApproval: {
161 never: { toolNames: ['GMAIL_FETCH_EMAILS'] },
162 },
163 }),
164 ];
165 ```
166
167
168
169 ### Python SDK (v0.8.17)
170
171 #### **Added: MCP Support**
172
173 **Core MCP Features:**
174 - **Server Configuration**: Create and manage MCP server configurations
175 - **Toolkit Management**: Support for both simple toolkit names and detailed configurations
176 - **Authentication Control**: Per-toolkit auth config specification
177 - **Tool Filtering**: Specify allowed tools across all toolkits
178 - **User Instance Generation**: Generate user-specific MCP server instances
179
180 **Basic Usage:**
181
182 ```python
183 from composio import Composio
184
185 composio = Composio()
186
187 # Create MCP server with toolkit configurations
188 server = composio.mcp.create(
189 'personal-mcp-server',
190 toolkits=[
191 {
192 'toolkit': 'github',
193 'auth_config_id': 'ac_xyz',
194 },
195 {
196 'toolkit': 'slack',
197 'auth_config_id': 'ac_abc',
198 },
199 ],
200 allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
201 manually_manage_connections=False
202 )
203
204 # Generate server instance for a user
205 mcp_instance = server.generate('user_12345')
206 print(f"MCP URL: {mcp_instance['url']}")
207 ```
208
209 **Simple Toolkit Usage:**
210
211 ```python
212 # Using simple toolkit names
213 server = composio.mcp.create(
214 'simple-mcp-server',
215 toolkits=['composio_search', 'text_to_pdf'],
216 allowed_tools=['COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH', 'TEXT_TO_PDF_CONVERT_TEXT_TO_PDF']
217 )
218
219 # All tools from toolkits (default behavior)
220 server = composio.mcp.create(
221 'all-tools-server',
222 toolkits=['composio_search', 'text_to_pdf']
223 # allowed_tools=None means all tools from these toolkits
224 )
225 ```
226
227 **LangChain Integration:**
228
229 ```python
230 import asyncio
231 from composio import Composio
232 from langchain_mcp_adapters.client import MultiServerMCPClient
233 from langgraph.prebuilt import create_react_agent
234
235 composio = Composio()
236
237 mcp_config = composio.mcp.create(
238 name="langchain-slack-mcp",
239 toolkits=[{"toolkit": "slack", "auth_config_id": "<auth-config-id>"}],
240 )
241
242 mcp_server = mcp_config.generate(user_id='<user-id>')
243
244 client = MultiServerMCPClient({
245 "composio": {
246 "url": mcp_server["url"],
247 "transport": "streamable_http",
248 }
249 })
250
251 async def langchain_mcp(message: str):
252 tools = await client.get_tools()
253 agent = create_react_agent("openai:gpt-4.1", tools)
254 response = await agent.ainvoke({"messages": message})
255 return response
256
257 response = asyncio.run(langchain_mcp("Show me 20 most used slack channels"))
258 ```
259
260 #### **Added: Experimental ToolRouter**
261
262 **Core ToolRouter Features:**
263 - **Session Management**: Create isolated tool routing sessions for users
264 - **Toolkit Configuration**: Support for both simple toolkit names and detailed configurations
265 - **Session Isolation**: Each session gets its own MCP URL and session ID
266 - **Flexible Authentication**: Per-session auth config management
267 - **Scoped Tool Access**: Control which tools are available within each session
268
269 **Basic Usage:**
270
271 ```python
272 from composio import Composio
273
274 composio = Composio()
275
276 # Create a tool router session
277 session = composio.experimental.tool_router.create_session(
278 user_id='user_123',
279 toolkits=['github', 'slack'],
280 manually_manage_connections=False
281 )
282
283 print(f"Session ID: {session['session_id']}")
284 print(f"MCP URL: {session['url']}")
285 ```
286
287 **Advanced Configuration:**
288
289 ```python
290 # Create session with detailed toolkit configurations
291 session = composio.experimental.tool_router.create_session(
292 user_id='user_456',
293 toolkits=[
294 {
295 'toolkit': 'github',
296 'auth_config_id': 'ac_github_123'
297 },
298 {
299 'toolkit': 'slack',
300 'auth_config_id': 'ac_slack_456'
301 }
302 ],
303 manually_manage_connections=True
304 )
305
306 # Minimal session (no specific toolkits)
307 session = composio.experimental.tool_router.create_session(
308 user_id='user_789'
309 )
310 ```
311
312 **Integration with AI Frameworks:**
313
314 ```python
315 import asyncio
316 from composio import Composio
317 from langchain_mcp_adapters.client import MultiServerMCPClient
318
319 composio = Composio()
320
321 # Create tool router session
322 session = composio.experimental.tool_router.create_session(
323 user_id='ai_user',
324 toolkits=['composio_search', 'text_to_pdf']
325 )
326
327 # Use with LangChain MCP client
328 client = MultiServerMCPClient({
329 "composio": {
330 "url": session["url"],
331 "transport": "streamable_http",
332 }
333 })
334
335 async def use_tool_router():
336 tools = await client.get_tools()
337 # Use tools in your AI workflow
338 return tools
339
340 tools = asyncio.run(use_tool_router())
341 ```
342
343
344
345 ### Migration Guide
346
347 #### **TypeScript SDK: Migrating to New MCP API**
348
349 The new MCP API provides enhanced functionality and better integration patterns. Here's how to migrate from the previous MCP implementation:
350
351 ##### **Before (Legacy MCP)**
352
353 ```typescript
354 // @noErrors
355 // Legacy MCP approach (still accessible via deprecated.mcp)
356 import { Composio } from '@composio/core';
357
358 const composio = new Composio();
359
360 // Old MCP server creation
361 const legacyMCP = await composio.deprecated.mcp.createServer({
362 name: 'my-server',
363 toolkits: ['github', 'gmail'],
364 });
365
366 // Direct URL usage
367 const mcpUrl = legacyMCP.url;
368 ```
369
370 ##### **After (New MCP API)**
371
372 ```typescript
373 // @noErrors
374 // New MCP API approach
375 import { Composio } from '@composio/core';
376
377 const composio = new Composio({
378 apiKey: process.env.COMPOSIO_API_KEY,
379 });
380
381 // Step 1: Create MCP configuration
382 const mcpConfig = await composio.mcp.create('my-server', {
383 toolkits: [
384 { toolkit: 'github', authConfigId: 'ac_github_123' },
385 { toolkit: 'gmail', authConfigId: 'ac_gmail_456' }
386 ],
387 allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
388 manuallyManageConnections: false,
389 });
390
391 // Step 2: Generate user-specific server instance
392 const serverInstance = await composio.mcp.generate('user_123', mcpConfig.id);
393 const mcpUrl = serverInstance.url;
394 ```
395
396 ##### **Key Migration Changes**
397
398 1. **Two-Step Process**:
399 - **Before**: Single step server creation
400 - **After**: Create configuration, then generate user instances
401
402 2. **Enhanced Configuration**:
403 - **Before**: Simple toolkit names only
404 - **After**: Detailed toolkit configs with auth, tool filtering, connection management
405
406 3. **User-Specific URLs**:
407 - **Before**: Single server URL for all users
408 - **After**: Unique URLs per user for better isolation
409
410 4. **Backward Compatibility**:
411 - **Legacy Access**: Old MCP functionality remains available via `composio.deprecated.mcp`
412 - **Gradual Migration**: Migrate at your own pace without breaking existing implementations
413
414 ##### **Migration Benefits**
415
416 - **Better Security**: User-specific sessions with isolated access
417 - **Enhanced Control**: Fine-grained toolkit and tool management
418 - **Framework Integration**: Native support for modern AI frameworks
419 - **Scalability**: Better resource management and user isolation
420
421 ##### **Migration Timeline**
422
423 - **Phase 1**: New MCP API available alongside legacy implementation
424 - **Phase 2**: Legacy MCP accessible via `deprecated.mcp` namespace
425 - **Phase 3**: Full deprecation (timeline to be announced)
426
427 **Recommendation**: Start new projects with the new MCP API and gradually migrate existing implementations to benefit from enhanced features and better framework integration.
428
429
430 ### Key Benefits & Use Cases
431
432 #### **Development & Testing**
433 - **Isolated Environments**: Test different toolkit combinations without affecting production
434 - **Scoped Access**: Limit tool access for security and testing purposes
435 - **Framework Flexibility**: Works with any MCP-compatible client or framework
436
437 #### **Production Workflows**
438 - **Multi-Service Integration**: Seamlessly combine tools from different services
439 - **User-Specific Sessions**: Each user gets their own isolated session with appropriate permissions
440 - **Authentication Management**: Fine-grained control over authentication per toolkit
441
442 #### **Framework Compatibility**
443 - **Vercel AI**: Native integration with Vercel AI SDK
444 - **Mastra**: Full support for Mastra agents and workflows
445 - **OpenAI Agents**: Direct integration with OpenAI's agent framework
446 - **LangChain**: Complete LangGraph and LangChain compatibility
447 - **Custom Clients**: Works with any MCP-compatible client
448
449 #### **Enterprise Features**
450 - **Session Management**: Track and manage multiple user sessions
451 - **Resource Control**: Limit concurrent sessions and resource usage
452 - **Audit Trail**: Full logging and monitoring of tool usage
453 - **Security**: Isolated sessions prevent cross-user data access
454
455
456 ### Migration & Compatibility
457
458 Both MCP and ToolRouter features are designed to complement existing Composio functionality:
459
460 ```typescript
461 // @noErrors
462 // Can be used alongside regular tool management
463 const regularTools = await composio.tools.get({ toolkits: ['github'] });
464 const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
465 toolkits: ['gmail', 'slack']
466 });
467
468 // Both approaches can coexist and serve different purposes
469 ```
470
471 The experimental ToolRouter API provides a preview of advanced session management capabilities, while the MCP API offers production-ready Model Control Protocol support for modern AI frameworks.
472
473
474
475 ### Bug Fixes
476
477 #### **Fixed: ToolRouter Dependency Issue**
478
479 **Python SDK (v0.8.19)**
480
481 **Issue Fixed:**
482 - **ToolRouter Functionality**: Fixed ToolRouter tests that were failing due to missing `tool_router` attribute in HttpClient
483 - **Dependency Update**: Updated `composio-client` dependency from version 1.9.1 to 1.10.0+ to include ToolRouter functionality
484 - **Version Compatibility**: Resolved compatibility issues between ToolRouter implementation and client library
485
486 **Details:**
487 ToolRouter functionality was briefly broken in versions 0.8.15 to 0.8.18 due to a dependency version mismatch. The `composio-client` library version 1.9.1 did not include the `tool_router` attribute, causing all ToolRouter integration tests to fail with `AttributeError: 'HttpClient' object has no attribute 'tool_router'`.
488
489 This has been fixed in version 0.8.19 by:
490 - Updating the `composio-client` dependency to version 1.10.0+
491 - Ensuring all ToolRouter functionality is now available
492 - All ToolRouter integration tests now pass successfully
493
494 **Previous Issue:**
495 ```python
496 # This would fail in versions 0.8.15-0.8.18
497 session = composio.experimental.tool_router.create_session(user_id='test')
498 # AttributeError: 'HttpClient' object has no attribute 'tool_router'
499 ```
500
501 **Fixed in 0.8.19:**
502 ```python
503 # This now works correctly
504 session = composio.experimental.tool_router.create_session(user_id='test')
505 # Returns: {'session_id': '...', 'url': '...'}
506 ```
507
508 #### **Fixed: Missing Descriptions in Auth Config Fields**
509
510 **Python SDK (v0.8.17) & TypeScript SDK (v0.1.53)**
511
512 **Issue Fixed:**
513 - **Auth Config Connection Fields**: Added missing descriptions to toolkit auth configuration connection fields
514 - **Auth Config Creation Fields**: Added missing descriptions to toolkit auth configuration creation fields
515 - **Field Documentation**: Improved field documentation and help text for better developer experience
516
517 **Details:**
518 Previously, when developers were setting up auth configurations for toolkits, many fields lacked proper descriptions, making it difficult to understand what information was required. This fix ensures all auth config fields now include:
519
520 - Clear, descriptive field labels
521 - Helpful placeholder text where appropriate
522 - Detailed explanations of field requirements
523
524 This improvement affects all toolkits and makes the authentication setup process more intuitive and error-free.