Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat: updated mcp folder structure (#1646)

Apoorv Tanejafa08d209ca5f
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5dc3257b4..aff3b9df9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -283,6 +283,9 @@ importers:
'@mastra/core':
specifier: ^0.10.0
+ '@mastra/mcp':
+ specifier: ^0.10.3
dotenv:
specifier: ^16.4.1
version: 16.5.0
@@ -476,7 +479,7 @@ importers:
version: 3.16.8
effect-errors:
specifier: ^1.10.11
- version: 1.10.11(ff5edfb43a1891ed491370151a2c33b9)
+ version: 1.10.11(krha7h4zqwvrjoe7foerbk5wme)
indent-string:
specifier: ^5.0.0
version: 5.0.0
@@ -644,7 +647,7 @@ importers:
dependencies:
'@langchain/core':
specifier: ^0.3.44
devDependencies:
'@composio/core':
specifier: workspace:*
@@ -1664,6 +1667,12 @@ packages:
peerDependencies:
zod: ^3.0.0
+ '@mastra/[email protected]':
+ resolution: {integrity: sha512-kFRypsAU3s84CQOEkU4ZFUxOJBxbFztgo+tliBfVlUp98XRYKXifol5aM8eVgKtC59LQq/Q15QjIwNaiNpb/ZQ==}
+ peerDependencies:
+ '@mastra/core': ^0.10.2-alpha.0
+ zod: ^3.0.0
+
'@mastra/[email protected]':
resolution: {integrity: sha512-QCPnD0Jd7NJgfVdvNkLPJhqSjyNcA+eaa16N+3kwa+wTBMb6eziWZC1aQNQ6o4T1JVPoo5unVVtL1pqiIgV+tA==}
peerDependencies:
@@ -3342,6 +3351,9 @@ packages:
resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==}
+ resolution: {integrity: sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==}
+
resolution: {integrity: sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA==}
@@ -3601,6 +3613,10 @@ packages:
resolution: {integrity: sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==}
engines: {node: '>=16.17'}
+ resolution: {integrity: sha512-Fqs7ChZm72y40wKjOFXBKg7nJZvQJmewP5/7LtePDdnah/+FH9Hp5sgMujSCMPXlxOAW2//1jrW9pnsY7o20vQ==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-/kP8CAwxzLVEeFrMm4kMmy4CCDlpipyA7MYLVrdJIkV0fYF0UaigQHRsxHiuY/GEea+bh4KSv3TIlgr+2UL6bw==}
engines: {node: '>=12.0.0'}
@@ -7004,6 +7020,23 @@ snapshots:
transitivePeerDependencies:
- openai
+ dependencies:
+ '@cfworker/json-schema': 4.1.1
+ ansi-styles: 5.2.0
+ camelcase: 6.3.0
+ decamelize: 1.2.0
+ js-tiktoken: 1.0.20
+ mustache: 4.2.0
+ p-queue: 6.6.2
+ p-retry: 4.6.2
+ uuid: 10.0.0
+ zod: 3.25.62
+ zod-to-json-schema: 3.24.5([email protected])
+ transitivePeerDependencies:
+ - openai
+
dependencies:
@@ -7124,6 +7157,20 @@ snapshots:
- valibot
- zod-openapi
+ dependencies:
+ '@modelcontextprotocol/sdk': 1.12.1
+ date-fns: 4.1.0
+ exit-hook: 4.0.0
+ fast-deep-equal: 3.1.3
+ hono: 4.7.11
+ uuid: 11.1.0
+ zod: 3.25.62
+ zod-from-json-schema: 0.0.5
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
@@ -8777,7 +8824,7 @@ snapshots:
sirv: 3.0.1
tinyglobby: 0.2.14
tinyrainbow: 2.0.0
'@vitest/[email protected]':
dependencies:
@@ -9203,6 +9250,8 @@ snapshots:
+
@@ -9262,7 +9311,7 @@ snapshots:
- [email protected](ff5edfb43a1891ed491370151a2c33b9):
+ [email protected](krha7h4zqwvrjoe7foerbk5wme):
dependencies:
'@effect/platform': 0.84.11([email protected])
@@ -9458,6 +9507,8 @@ snapshots:
signal-exit: 4.1.0
strip-final-newline: 3.0.0
+
@@ -10080,6 +10131,18 @@ snapshots:
optionalDependencies:
+ dependencies:
+ '@types/uuid': 10.0.0
+ chalk: 4.1.2
+ console-table-printer: 2.14.3
+ p-queue: 6.6.2
+ p-retry: 4.6.2
+ semver: 7.7.2
+ uuid: 10.0.0
+ optionalDependencies:
+
dependencies:
prelude-ls: 1.2.1
diff --git a/ts/docs/api/mcp.md b/ts/docs/api/mcp.md
new file mode 100644
index 000000000..d3173596b
--- /dev/null
+++ b/ts/docs/api/mcp.md
@@ -0,0 +1,429 @@
+
+# MCP (Model Control Protocol) API
+
+The `MCP` class provides methods to manage Model Control Protocol servers, enabling AI models to interact with external tools and services through a standardized protocol. MCP servers act as bridges between AI agents and various toolkits, providing secure and managed access to external capabilities.
+
+## Overview
+
+MCP (Model Control Protocol) is a protocol for exposing tools and capabilities to AI models in a standardized way. With Composio's MCP integration, you can:
+
+- Create MCP servers that expose specific toolkits and tools
+- Manage authentication for MCP servers
+- Generate secure URLs for AI agents to connect to MCP servers
+- Support multiple AI frameworks through provider-specific transformations
+
+## Methods
+
+### create(name, toolkitConfigs, authOptions?)
+
+Creates a new MCP server with specified toolkit configurations.
+
+```typescript
+// Create an MCP server with Gmail toolkit
+const server = await composio.mcp.create(
+ "my-gmail-server",
+ [
+ {
+ toolkit: "gmail",
+ authConfigId: "ac_sdhkjfhjksdk",
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
+ }
+ ],
+ { useComposioManagedAuth: true }
+);
+
+// Create an MCP server with multiple toolkits
+const multiToolServer = await composio.mcp.create(
+ "multi-tool-server",
+ [
+ {
+ toolkit: "github",
+ authConfigId: "ac_github123",
+ allowedTools: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_REPO"]
+ },
+ {
+ toolkit: "slack",
+ authConfigId: "ac_slack456",
+ allowedTools: ["SLACK_SEND_MESSAGE"]
+ }
+ ]
+);
+
+// Use the convenience method to get server URLs
+const urls = await server.getServer({
+ connectedAccountIds: { gmail: "connected_account_id" }
+});
+```
+
+**Parameters:**
+
+- `name` (string): Unique name for the MCP server
+- `toolkitConfigs` (MCPToolkitConfig[]): Array of toolkit configurations
+ - `toolkit`: The toolkit slug (e.g., "gmail", "github")
+ - `authConfigId`: The auth configuration ID to use
+ - `allowedTools`: Array of specific tool IDs to expose
+- `authOptions` (MCPAuthOptions): Optional authentication options
+ - `useComposioManagedAuth`: Whether to use Composio-managed authentication
+
+**Returns:** Promise<McpServerCreateResponse> - Created server details with convenience `getServer` method
+
+**Throws:** ValidationError if configurations are invalid or server creation fails
+
+### getServer(id, params, authOptions?)
+
+Retrieves server URLs for an existing MCP server. This method generates secure URLs that AI agents can use to connect to the MCP server.
+
+```typescript
+// Get URLs for a server using connected account IDs
+const urls = await composio.mcp.getServer("server-uuid", {
+ connectedAccountIds: {
+ gmail: "connected_account_123",
+ github: "connected_account_456"
+ }
+});
+
+// Get URLs for a server using user ID
+const userUrls = await composio.mcp.getServer("server-uuid", {
+ userId: "user_123"
+});
+
+// Override authentication options
+const customAuthUrls = await composio.mcp.getServer(
+ "server-uuid",
+ { userId: "user_123" },
+ { useComposioManagedAuth: false }
+);
+```
+
+**Parameters:**
+
+- `id` (string): Server UUID
+- `params` (MCPGetServerParams): Parameters for getting server URLs
+ - Either `connectedAccountIds` (object mapping toolkit names to account IDs) OR `userId` (string)
+- `authOptions` (MCPAuthOptions): Optional authentication options to override server defaults
+
+**Returns:** Promise<T> - Transformed server URLs in provider-specific format
+
+**Throws:** ValidationError if parameters are invalid or URL generation fails
+
+### list(options)
+
+Lists MCP server configurations with filtering options.
+
+```typescript
+// List all servers with pagination
+const servers = await composio.mcp.list({
+ page: 1,
+ limit: 10
+});
+
+// List servers for specific toolkits
+const gmailServers = await composio.mcp.list({
+ toolkits: ['gmail', 'google-calendar'],
+ limit: 20
+});
+
+// List servers by auth config
+const authFilteredServers = await composio.mcp.list({
+ authConfigs: ['auth_123', 'auth_456'],
+ name: 'production'
+});
+```
+
+**Parameters:**
+
+- `options` (object): Filtering and pagination options
+ - `page`: Page number for pagination (default: 1)
+ - `limit`: Number of items per page (default: 10)
+ - `toolkits`: Filter by toolkit names
+ - `authConfigs`: Filter by auth config IDs
+ - `name`: Filter by server name
+
+**Returns:** Promise<McpListResponse> - List of MCP servers
+
+### get(id)
+
+Retrieves details of a specific MCP server.
+
+```typescript
+const serverDetails = await composio.mcp.get('server-uuid');
+console.log(serverDetails.name);
+console.log(serverDetails.toolkits);
+console.log(serverDetails.status);
+```
+
+**Parameters:**
+
+- `id` (string): Server UUID
+
+**Returns:** Promise<McpRetrieveResponse> - Server details including configuration and metadata
+
+### update(id, name, toolkitConfigs, authOptions?)
+
+Updates an MCP server configuration.
+
+```typescript
+const updatedServer = await composio.mcp.update(
+ "server-uuid",
+ "updated-server-name",
+ [
+ {
+ toolkit: "gmail",
+ authConfigId: "ac_new_auth_config",
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GMAIL_CREATE_DRAFT"]
+ }
+ ],
+ { useComposioManagedAuth: true }
+);
+```
+
+**Parameters:**
+
+- `id` (string): Server UUID
+- `name` (string): New name for the server
+- `toolkitConfigs` (MCPToolkitConfig[]): Updated toolkit configurations
+- `authOptions` (MCPAuthOptions): Updated authentication options
+
+**Returns:** Promise<McpUpdateResponse> - Updated server details
+
+### delete(id)
+
+Deletes an MCP server.
+
+```typescript
+const result = await composio.mcp.delete('server-uuid');
+console.log(result.deleted); // true
+```
+
+**Parameters:**
+
+- `id` (string): Server UUID
+
+**Returns:** Promise<McpDeleteResponse> - Deletion confirmation
+
+### generateUrl(params)
+
+Generates URLs for MCP server access. This is a lower-level method primarily used internally.
+
+```typescript
+const urlResponse = await composio.mcp.generateUrl({
+ userIds: ['user123'],
+ connectedAccountIds: ['account456'],
+ mcpServerId: 'server-uuid',
+ managedAuthByComposio: true
+});
+```
+
+**Parameters:**
+
+- `params` (GenerateURLParams): URL generation parameters
+ - `userIds`: Array of user IDs
+ - `connectedAccountIds`: Array of connected account IDs
+ - `mcpServerId`: MCP server ID
+ - `managedAuthByComposio`: Whether to use Composio-managed auth
+
+**Returns:** Promise<GenerateURLResponse> - Generated URLs
+
+## Provider Integration
+
+Different AI frameworks expect MCP server URLs in different formats. Composio automatically handles these transformations through provider-specific implementations.
+
+### Using with Providers
+
+```typescript
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+import { AnthropicProvider } from '@composio/anthropic';
+
+// With Mastra provider - returns key-value URL mapping
+const composioMastra = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new MastraProvider()
+});
+
+const mastraServer = await composioMastra.mcp.create(...);
+const mastraUrls = await mastraServer.getServer({
+ connectedAccountIds: { gmail: "account_id" }
+});
+// Returns: { "server-0": { url: "..." } }
+
+// With Anthropic provider - returns array of server info
+const composioAnthropic = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new AnthropicProvider()
+});
+
+const anthropicServer = await composioAnthropic.mcp.create(...);
+const anthropicUrls = await anthropicServer.getServer({
+ connectedAccountIds: { gmail: "account_id" }
+});
+// Returns: [{ url: URL, name: "...", toolkit: "gmail" }]
+```
+
+### Supported Providers
+
+- **Anthropic** - Returns McpServerUrlInfo[]
+- **OpenAI** - Returns McpServerUrlInfo[]
+- **LangChain** - Returns McpServerUrlInfo[]
+- **Vercel** - Returns McpServerUrlInfo[]
+- **Google** - Returns McpServerUrlInfo[]
+- **CloudFlare** - Returns McpServerUrlInfo[]
+- **Mastra** - Returns custom key-value URL mapping
+
+## Types
+
+### MCPToolkitConfig
+
+```typescript
+interface MCPToolkitConfig {
+ toolkit: string; // Toolkit slug (e.g., "gmail", "github")
+ authConfigId: string; // Auth configuration ID
+ allowedTools: string[]; // Array of allowed tool IDs
+}
+```
+
+### MCPAuthOptions
+
+```typescript
+interface MCPAuthOptions {
+ useComposioManagedAuth?: boolean; // Use Composio-managed authentication
+}
+```
+
+### MCPGetServerParams
+
+```typescript
+interface MCPGetServerParams {
+ userId?: string; // User ID (XOR with connectedAccountIds)
+ connectedAccountIds?: Record<string, string>; // Toolkit to account ID mapping
+}
+```
+
+### McpServerCreateResponse
+
+```typescript
+interface McpServerCreateResponse<T> {
+ id: string; // Server UUID
+ name: string; // Server name
+ createdAt?: string; // Creation timestamp
+ updatedAt?: string; // Last update timestamp
+ status?: string; // Server status
+ toolkits: string[]; // List of enabled toolkits
+ getServer: (params: MCPGetServerParams) => Promise<T>; // Convenience method
+}
+```
+
+### McpListResponse
+
+```typescript
+interface McpListResponse {
+ items?: Array<{
+ id: string;
+ name: string;
+ createdAt?: string;
+ updatedAt?: string;
+ status?: string;
+ }>;
+}
+```
+
+### McpServerUrlInfo
+
+```typescript
+interface McpServerUrlInfo {
+ url: URL; // MCP server URL
+ name: string; // Server instance name
+ toolkit?: string; // Associated toolkit
+}
+```
+
+## Complete Example
+
+Here's a complete example of using MCP with an AI agent:
+
+```typescript
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+import { MCPClient } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+// Initialize Composio with Mastra provider
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new MastraProvider(),
+});
+
+// Create an MCP server with Gmail toolkit
+const mcpServer = await composio.mcp.create(
+ "gmail-assistant",
+ [
+ {
+ toolkit: "gmail",
+ authConfigId: "ac_your_auth_config",
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
+ }
+ ],
+ { useComposioManagedAuth: true }
+);
+
+// Get server URLs for connected accounts
+const serverUrls = await mcpServer.getServer({
+ connectedAccountIds: {
+ "gmail": "your_connected_account_id"
+ }
+});
+
+// Initialize MCP client with the server URLs
+const mcpClient = new MCPClient({
+ servers: Object.fromEntries(
+ Object.entries(serverUrls).map(([key, value]) => [
+ key,
+ { url: new URL(value.url) }
+ ])
+ )
+});
+
+// Get available tools from MCP
+const tools = await mcpClient.getTools();
+
+// Create an AI agent with MCP tools
+const gmailAgent = new Agent({
+ name: 'Gmail Assistant',
+ instructions: 'You are a helpful Gmail assistant.',
+ model: openai('gpt-4'),
+ tools,
+});
+
+// Use the agent
+const response = await gmailAgent.generate('Fetch my latest emails');
+console.log(response.text);
+```
+
+## Best Practices
+
+1. **Toolkit Selection**: Only expose the tools that your AI agent needs to minimize the attack surface
+2. **Authentication**: Use Composio-managed authentication when possible for better security
+3. **Error Handling**: Always handle validation errors when creating or updating servers
+4. **Provider Choice**: Choose the appropriate provider based on your AI framework
+5. **Server Naming**: Use descriptive names that indicate the server's purpose
+6. **Tool Allowlisting**: Be specific about which tools to expose rather than exposing entire toolkits
+
+## Error Handling
+
+All MCP methods throw `ValidationError` when:
+- Input parameters fail Zod schema validation
+- API responses don't match expected schemas
+- Server operations fail (create, update, delete)
+- URL generation fails
+
+```typescript
+try {
+ const server = await composio.mcp.create("my-server", toolkitConfigs);
+} catch (error) {
+ if (error instanceof ValidationError) {
+ console.error('Validation failed:', error.message);
+ console.error('Cause:', error.cause);
+ }
+}
+```
\ No newline at end of file
diff --git a/ts/docs/core-concepts.md b/ts/docs/core-concepts.md
index 934b4566a..b2c3384e0 100644
--- a/ts/docs/core-concepts.md
+++ b/ts/docs/core-concepts.md
@@ -316,6 +316,84 @@ const composio = new Composio({
});
```
+## MCP (Model Control Protocol)
+
+MCP is a standardized protocol for exposing tools and capabilities to AI models. It acts as a bridge between AI agents and external services, providing secure and managed access to tools through MCP servers.
+
+### What is MCP?
+
+Model Control Protocol (MCP) is designed to solve the challenge of connecting AI models to external tools in a secure, scalable way. Instead of directly integrating tools into AI models, MCP provides:
+
+- **Standardized Communication**: A common protocol that different AI frameworks can understand
+- **Security Isolation**: Tools run in separate MCP servers, isolating them from the AI model
+- **Dynamic Tool Discovery**: AI models can discover available tools at runtime
+- **Provider Flexibility**: Works with multiple AI frameworks through provider adapters
+
+### MCP Servers
+
+MCP servers are the core component that expose tools to AI models. Each server:
+
+- **Hosts specific toolkits**: You choose which toolkits and tools to expose
+- **Manages authentication**: Handles auth for the tools it exposes
+- **Provides secure URLs**: Generates URLs that AI agents can connect to
+- **Supports multiple connections**: Can serve multiple users or AI agents
+
+```typescript
+// Example: Create an MCP server
+const mcpServer = await composio.mcp.create(
+ "email-assistant",
+ [
+ {
+ toolkit: "gmail",
+ authConfigId: "ac_gmail123",
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
+ }
+ ],
+ { useComposioManagedAuth: true }
+);
+
+// Get server URLs for AI agent to connect
+const serverUrls = await mcpServer.getServer({
+ connectedAccountIds: { gmail: "connected_account_id" }
+});
+```
+
+### MCP vs Direct Tool Execution
+
+There are two ways to use tools in Composio:
+
+1. **Direct Execution** (Traditional approach):
+ ```typescript
+ // Directly execute tools through the SDK
+ const result = await composio.tools.execute('GITHUB_GET_REPO', {
+ userId: 'user123',
+ arguments: { owner: 'example', repo: 'repo' }
+ });
+ ```
+
+2. **MCP Protocol** (Recommended for AI agents):
+ ```typescript
+ // Create MCP server and let AI agent discover/execute tools
+ const server = await composio.mcp.create("github-server", [...]);
+ const urls = await server.getServer({...});
+ // AI agent connects to URLs and executes tools autonomously
+ ```
+
+### When to Use MCP
+
+Use MCP when:
+- Building AI agents that need tool access
+- Working with frameworks that support MCP (Claude, Mastra, etc.)
+- You want standardized tool discovery and execution
+- Security isolation between AI and tools is important
+- You need to expose tools to multiple AI agents
+
+Use direct execution when:
+- Building traditional applications without AI
+- You need fine-grained control over tool execution
+- Working with simple scripts or automation
+- MCP overhead isn't necessary
+
## Custom Tools
Custom Tools allow you to extend Composio's functionality by creating your own tools. You define the input and output parameters and provide a handler function that implements the tool's behavior.
diff --git a/ts/examples/mastra/.env.example b/ts/examples/mastra/.env.example
index 0e728257c..a55e8a612 100644
--- a/ts/examples/mastra/.env.example
+++ b/ts/examples/mastra/.env.example
@@ -1,6 +1,7 @@
-# Composio API Key - Get it from https://app.composio.dev
-COMPOSIO_API_KEY=your_composio_api_key_here
-# Add other environment variables as needed for your example
-# OPENAI_API_KEY=your_openai_api_key_here
-# ANTHROPIC_API_KEY=your_anthropic_api_key_here
+# # Composio API Key - Get it from https://app.composio.dev
+# COMPOSIO_API_KEY=your_composio_api_key
+
+# # Add other environment variables as needed for your example
+# OPENAI_API_KEY=your_openai_api_key
+# # ANTHROPIC_API_KEY=your_anthropic_api_key_here
diff --git a/ts/examples/mastra/package.json b/ts/examples/mastra/package.json
index 746612eaa..1a414a689 100644
--- a/ts/examples/mastra/package.json
+++ b/ts/examples/mastra/package.json
@@ -9,6 +9,9 @@
"start": "bun src/index.ts",
"start:node": "tsx src/index.ts",
"dev": "bun --watch src/index.ts",
+ "start:mcp": "bun --watch src/mcp.ts",
+ "start:node:mcp": "tsx src/mcp.ts",
+ "dev:mcp": "tsx watch src/mcp.ts",
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [
@@ -24,6 +27,7 @@
"@composio/core": "workspace:*",
"@composio/mastra": "workspace:^",
"@mastra/core": "^0.10.0",
+ "@mastra/mcp": "^0.10.3",
"dotenv": "^16.4.1"
},
"devDependencies": {
diff --git a/ts/examples/mastra/src/mcp.ts b/ts/examples/mastra/src/mcp.ts
new file mode 100644
index 000000000..41e51b69a
--- /dev/null
+++ b/ts/examples/mastra/src/mcp.ts
@@ -0,0 +1,98 @@
+/**
+ * Mastra MCP Gmail Example
+ *
+ * This example demonstrates how to use Composio SDK with Mastra to:
+ * 1. Create an MCP server for Gmail toolkit
+ * 2. Connect to the server and fetch emails using tools
+ *
+ * Prerequisites:
+ * 1. Set up your COMPOSIO_API_KEY and OPENAI_API_KEY the .env file
+ * 2. Set up Gmail authentication in Composio dashboard
+ * 3. Run the example: pnpm tsx src/mcp.ts
+ */
+
+import { MastraProvider } from '@composio/mastra';
+import { Composio } from '@composio/core';
+import { MCPClient } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+import type { MastraMCPServerDefinition } from '@mastra/mcp';
+import 'dotenv/config';
+
+/**
+ * Initialize Composio
+ */
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new MastraProvider(),
+});
+
+// Create an MCP server with Gmail toolkit
+const mcpConfig = await composio.mcp.create(
+ "gmail-mcp-" + Date.now(),
+ [
+ {
+ toolkit: "gmail",
+ authConfigId: "<auth_config_id>", // Use your auth config ID
+ allowedTools: [
+ "GMAIL_FETCH_EMAILS"
+ ]
+ }
+ ],
+ { useComposioManagedAuth: true }
+);
+
+console.log(`✅ MCP server created: ${mcpConfig.id}`);
+console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(', ')}`);
+
+// Get server instance with connected accounts (using convenience method)
+const serverInstance = await mcpConfig.getServer({
+ connectedAccountIds: {
+ "gmail": "<connected_account_id>" // Replace it with the connected account id
+ }
+});
+
+// Alternative: You can also use the standalone method
+// const serverInstance = await composio.mcp.getServer(mcpConfig.id, {
+// connectedAccountIds: {
+// "gmail": "<connected_account_id>"
+// }
+// });
+
+console.log("Server instances for connected accounts:", serverInstance);
+
+// Initialize MCPClient with the server URLs
+const mcpClient = new MCPClient({
+ servers: Object.fromEntries(
+ Object.entries(serverInstance as Record<string, { url: string }>).map(([key, value]) => [
+ key,
+ { url: new URL(value.url) }
+ ])
+ ) satisfies Record<string, MastraMCPServerDefinition>
+});
+
+// Get available tools from MCP client
+const tools = await mcpClient.getTools();
+console.log(`🔧 Available tools: ${Object.keys(tools).join(', ')}`);
+
+// Create a Gmail agent with the MCP tools
+const gmailAgent = new Agent({
+ name: 'Gmail Assistant',
+ instructions: `
+ You are a helpful Gmail assistant that fetches and summarizes emails.
+ When fetching emails, provide a clear summary of the results including sender, subject, and date.
+ Be concise and provide actionable information based on the email content.
+ `,
+ model: openai('gpt-4o-mini'),
+ tools,
+});
+
+// Fetch and summarize recent emails
+console.log('\n=== Fetching and Summarizing Recent Emails ===');
+const emailResponse = await gmailAgent.generate(
+ 'Fetch the latest 10 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email'
+);
+console.log('\n📬 Email Summary:');
+console.log(emailResponse.text);
+
+console.log('\n✅ Gmail MCP Example completed successfully!');
diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.ts
index e5f84ba8f..70791ccec 100644
--- a/ts/packages/core/src/composio.ts
+++ b/ts/packages/core/src/composio.ts
@@ -4,6 +4,7 @@ import { Toolkits } from './models/Toolkits';
import { Triggers } from './models/Triggers';
import { AuthConfigs } from './models/AuthConfigs';
import { ConnectedAccounts } from './models/ConnectedAccounts';
+import { MCP } from './models/MCP';
import { BaseComposioProvider } from './provider/BaseProvider';
import { telemetry } from './telemetry/Telemetry';
import { getSDKConfig } from './utils/sdk';
@@ -15,9 +16,10 @@ import { version } from '../package.json';
import { getRandomUUID } from './utils/uuid';
import type { ComposioRequestHeaders } from './types/composio.types';
import { LogLevel } from '@composio/client/client';
+import { McpServerGetResponse } from './types/mcp.types';
export type ComposioConfig<
- TProvider extends BaseComposioProvider<unknown, unknown> = OpenAIProvider,
+ TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider,
> = {
/**
* The API key for the Composio API.
@@ -67,11 +69,19 @@ export type ComposioConfig<
defaultHeaders?: ComposioRequestHeaders;
};
+/**
+ * Extract the MCP response type from a provider
+ */
+type ExtractMcpResponseType<T> =
+ T extends BaseComposioProvider<unknown, unknown, infer TMcp> ? TMcp : McpServerGetResponse;
+
/**
* This is the core class for Composio.
* It is used to initialize the Composio SDK and provide a global configuration.
*/
-export class Composio<TProvider extends BaseComposioProvider<unknown, unknown> = OpenAIProvider> {
+export class Composio<
+ TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider,
+> {
/**
* The Composio API client.
* @type {ComposioClient}
@@ -96,6 +106,8 @@ export class Composio<TProvider extends BaseComposioProvider<unknown, unknown> =
// connected accounts
connectedAccounts: ConnectedAccounts;
+ mcp: MCP<ExtractMcpResponseType<TProvider>>;
+
/**
* Creates a new instance of the Composio SDK.
*
@@ -145,7 +157,9 @@ export class Composio<TProvider extends BaseComposioProvider<unknown, unknown> =
apiKey: apiKeyParsed,
baseURL: baseURLParsed,
defaultHeaders: config?.defaultHeaders,
- logLevel: (process.env.COMPOSIO_LOG_LEVEL as LogLevel) ?? undefined,
+ logLevel:
+ (process.env.COMPOSIO_LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error' | undefined) ??
+ undefined,
});
/**
@@ -163,6 +177,7 @@ export class Composio<TProvider extends BaseComposioProvider<unknown, unknown> =
*/
this.provider = (config?.provider ?? new OpenAIProvider()) as TProvider;
this.tools = new Tools(this.client, this.provider);
+ this.mcp = new MCP(this.client, this.provider);
this.toolkits = new Toolkits(this.client);
this.triggers = new Triggers(this.client);
diff --git a/ts/packages/core/src/index.ts b/ts/packages/core/src/index.ts
index 7abd715b0..a9c590554 100644
--- a/ts/packages/core/src/index.ts
+++ b/ts/packages/core/src/index.ts
@@ -1,11 +1,15 @@
// Core exports
export { Composio } from './composio';
-export { ComposioProvider } from './provider/ComposioProvider';
-export { BaseAgenticProvider, BaseNonAgenticProvider } from './provider/BaseProvider';
-export type { BaseComposioProvider } from './provider/BaseProvider';
export { OpenAIProvider } from './provider/OpenAIProvider';
+export { ComposioProvider } from './provider/ComposioProvider';
+export {
+ BaseNonAgenticProvider,
+ BaseAgenticProvider,
+ BaseComposioProvider,
+} from './provider/BaseProvider';
export { jsonSchemaToZodSchema, removeNonRequiredProperties } from './utils/jsonSchema';
export { AuthScheme } from './models/AuthScheme';
+export { MCP } from './models/MCP';
export * from './types/provider.types';
export * from './types/customTool.types';
export * from './types/tool.types';
@@ -14,6 +18,7 @@ export * from './types/modifiers.types';
export * from './types/connectedAccountAuthStates.types';
export * from './types/toolkit.types';
export * from './types/triggers.types';
+export * from './types/mcp.types';
export * as constants from './utils/constants';
export { default as logger } from './utils/logger';
diff --git a/ts/packages/core/src/models/MCP.ts b/ts/packages/core/src/models/MCP.ts
new file mode 100644
index 000000000..fedb6fe3f
--- /dev/null
+++ b/ts/packages/core/src/models/MCP.ts
@@ -0,0 +1,550 @@
+/**
+ * @fileoverview MCP class for Composio SDK, used to manage MCP servers.
+ *
+ * @author Apoorv Taneja <[email protected]>
+ * @date 2025-06-12
+ * @module MCP
+ */
+import ComposioClient from '@composio/client';
+import { telemetry } from '../telemetry/Telemetry';
+import {
+ MCPToolkitConfig,
+ MCPAuthOptions,
+ MCPGetServerParams,
+ MCPToolkitConfigsArraySchema,
+ MCPAuthOptionsSchema,
+ MCPGetServerParamsSchema,
+ CustomCreateResponseSchema,
+ GenerateURLResponseSchema,
+ GenerateURLParamsSnakeCaseSchema,
+ GenerateURLParamsValidated,
+ McpListResponseSchema,
+ McpRetrieveResponseSchema,
+ McpDeleteResponseSchema,
+ McpUpdateResponseSchema,
+ McpUrlResponse,
+ McpUrlResponseCamelCase,
+ McpServerGetResponse,
+ McpServerCreateResponse,
+} from '../types/mcp.types';
+import { CustomCreateResponse, GenerateURLParams } from '@composio/client/resources/mcp';
+import { ValidationError } from '../errors/ValidationErrors';
+import { BaseComposioProvider } from '../provider/BaseProvider';
+import {
+ transformMcpCreateResponse,
+ transformMcpListResponse,
+ transformMcpRetrieveResponse,
+ transformMcpDeleteResponse,
+ transformMcpUpdateResponse,
+ transformMcpGenerateUrlResponse,
+} from '../utils/transformers/mcp';
+
+/**
+ * MCP (Model Control Protocol) class
+ * Handles MCP server operations
+ */
+export class MCP<T = McpServerGetResponse> {
+ private client: ComposioClient;
+ private provider?: BaseComposioProvider<unknown, unknown, unknown>;
+
+ constructor(client: ComposioClient, provider?: BaseComposioProvider<unknown, unknown, unknown>) {
+ this.client = client;
+ this.provider = provider;
+ telemetry.instrument(this);
+ }
+
+ /**
+ * Validates toolkit configurations using Zod schema
+ * @private
+ * @param {MCPToolkitConfig[]} toolkitConfigs - Array of toolkit configurations to validate
+ * @param {MCPAuthOptions} [authOptions] - Authentication options to validate
+ * @throws {ValidationError} If validation fails
+ */
+ private validateInputs(toolkitConfigs: MCPToolkitConfig[], authOptions?: MCPAuthOptions): void {
+ // Validate toolkit configurations
+ const toolkitConfigsResult = MCPToolkitConfigsArraySchema.safeParse(toolkitConfigs);
+ if (toolkitConfigsResult.error) {
+ throw new ValidationError('Failed to parse toolkit configurations', {
+ cause: toolkitConfigsResult.error,
+ });
+ }
+
+ // Validate auth options if provided
+ if (authOptions !== undefined) {
+ const authOptionsResult = MCPAuthOptionsSchema.safeParse(authOptions);
+ if (authOptionsResult.error) {
+ throw new ValidationError('Failed to parse auth options', {
+ cause: authOptionsResult.error,
+ });
+ }
+ }
+ }
+
+ /**
+ * Create a new MCP server
+ * @param {string} name - Unique name for the MCP server
+ * @param {MCPToolkitConfig[]} toolkitConfigs - Array of toolkit configurations
+ * @param {MCPAuthOptions} [authOptions] - Authentication configuration options
+ * @returns {Promise<McpServerCreateResponse<T>>} Created server details with instance getter
+ *
+ * @example
+ * ```typescript
+ * const server = await composio.mcp.create(
+ * "personal-mcp-server",
+ * [
+ * {
+ * toolkit: "GMAIL",
+ * authConfigId: "ac_sdhkjfhjksdk",
+ * allowedTools: ["GMAIL_FETCH_EMAILS"],
+ * },
+ * ],
+ * { useComposioManagedAuth: true },
+ * );
+ *
+ * // Option 1: Use convenience method on response
+ * const urls = await server.getServer({
+ * connectedAccountIds: { gmail: "account_id" }
+ * });
+ *
+ * // Option 2: Use standalone method later
+ * const urlsLater = await composio.mcp.getServer(server.id, {
+ * connectedAccountIds: { gmail: "account_id" }
+ * });
+ * ```
+ */
+ async create(
+ name: string,
+ toolkitConfigs: MCPToolkitConfig[],
+ authOptions?: MCPAuthOptions
+ ): Promise<McpServerCreateResponse<T>> {
+ // Validate inputs using Zod schemas
+ this.validateInputs(toolkitConfigs, authOptions);
+
+ const toolkits = toolkitConfigs.map(config => config.toolkit);
+
+ // Create a custom MCP server with the toolkit configurations
+ let mcpServerCreatedResponse: CustomCreateResponse;
+ try {
+ mcpServerCreatedResponse = await this.client.mcp.custom.create({
+ name,
+ toolkits: toolkits,
+ custom_tools: toolkitConfigs.flatMap(config => config.allowedTools),
+ managed_auth_via_composio: authOptions?.useComposioManagedAuth || false,
+ auth_config_ids: toolkitConfigs.map(config => config.authConfigId),
+ });
+ } catch (error) {
+ throw new ValidationError('Failed to create MCP server', {
+ cause: error,
+ });
+ }
+
+ // Validate the server creation response
+ const serverResponseResult = CustomCreateResponseSchema.safeParse(mcpServerCreatedResponse);
+ if (serverResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP server creation response', {
+ cause: serverResponseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ const camelCaseResponse = transformMcpCreateResponse(mcpServerCreatedResponse);
+
+ // Return response with convenience getServer method
+ return {
+ ...camelCaseResponse,
+ toolkits,
+ getServer: async (params: MCPGetServerParams): Promise<T> => {
+ // Delegate to the standalone getServer method
+ return this.getServer(camelCaseResponse.id, params, authOptions);
+ },
+ } as McpServerCreateResponse<T>;
+ }
+
+ /**
+ * Get server URLs for an existing MCP server
+ * @param {string} id - Server UUID
+ * @param {MCPGetServerParams} params - Parameters for getting server URLs
+ * @param {MCPAuthOptions} [authOptions] - Authentication options (optional, will use server's default if not provided)
+ * @returns {Promise<T>} Transformed server URLs in provider-specific format
+ *
+ * @example
+ * ```typescript
+ * // Get URLs for an existing server
+ * const urls = await composio.mcp.getServer("server-id", {
+ * connectedAccountIds: {
+ * gmail: "connected_account_id"
+ * }
+ * });
+ * ```
+ */
+ async getServer(
+ id: string,
+ params: MCPGetServerParams,
+ authOptions?: MCPAuthOptions
+ ): Promise<T> {
+ // Get server details first
+ const serverDetails = await this.get(id);
+
+ // Validate params using Zod schema
+ const paramsResult = MCPGetServerParamsSchema.safeParse(params);
+ if (paramsResult.error) {
+ throw new ValidationError('Failed to parse get server parameters', {
+ cause: paramsResult.error,
+ });
+ }
+
+ // Extract toolkits from server details
+ const toolkits = serverDetails.toolkits || [];
+
+ // If connected_account_ids is provided, verify toolkit names
+ if (paramsResult.data.connectedAccountIds) {
+ const providedToolkits = Object.keys(paramsResult.data.connectedAccountIds);
+ const invalidToolkits = providedToolkits.filter(toolkit => !toolkits.includes(toolkit));
+ if (invalidToolkits.length > 0) {
+ throw new ValidationError(
+ `Invalid toolkits provided: ${invalidToolkits.join(', ')}. Available toolkits are: ${toolkits.join(', ')}`,
+ {}
+ );
+ }
+ }
+
+ // Generate URL with error handling
+ let data;
+ try {
+ data = await this.client.mcp.generate.url({
+ user_ids: paramsResult.data.userId ? [paramsResult.data.userId] : [],
+ connected_account_ids: paramsResult.data.connectedAccountIds
+ ? Object.values(paramsResult.data.connectedAccountIds)
+ : [],
+ mcp_server_id: id,
+ managed_auth_by_composio:
+ authOptions?.useComposioManagedAuth ?? serverDetails.managedAuthViaComposio ?? false,
+ });
+ } catch (error) {
+ throw new ValidationError('Failed to generate MCP server URL', {
+ cause: error,
+ });
+ }
+
+ // Validate the URL generation response
+ const urlResponseResult = GenerateURLResponseSchema.safeParse(data);
+ if (urlResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP URL generation response', {
+ cause: urlResponseResult.error,
+ });
+ }
+
+ // Transform to camelCase
+ const camelCaseData = transformMcpGenerateUrlResponse(data);
+
+ // Use the wrapMcpServerResponse method to transform the response
+ return this.wrapMcpServerResponse(
+ camelCaseData,
+ serverDetails.name,
+ paramsResult.data.connectedAccountIds
+ ? Object.values(paramsResult.data.connectedAccountIds)
+ : undefined,
+ paramsResult.data.userId ? [paramsResult.data.userId] : undefined,
+ paramsResult.data.connectedAccountIds
+ ? Object.keys(paramsResult.data.connectedAccountIds)
+ : undefined
+ );
+ }
+
+ /**
+ * List MCP server configurations with filtering options
+ * @param {Object} options - Filtering and pagination options
+ * @param {number} [options.page] - Page number for pagination
+ * @param {number} [options.limit] - Number of items per page
+ * @param {string[]} [options.toolkits] - Filter servers by toolkit names
+ * @param {string[]} [options.authConfigs] - Filter servers by auth config IDs
+ * @param {string} [options.name] - Filter servers by name
+ * @param {string} [options.user] - Filter servers by user ID
+ * @returns {Promise<McpListResponse>} List of MCP servers matching the filters
+ *
+ * @example
+ * ```typescript
+ * // List all servers with pagination
+ * const servers = await composio.mcp.list({
+ * page: 1,
+ * limit: 10
+ * });
+ *
+ * // List Gmail and Supabase servers
+ * const filteredServers = await composio.mcp.list({
+ * toolkits: ['GMAIL', 'SUPABASE'],
+ * authConfigIds: ['auth_123', 'auth_456']
+ * });
+ * ```
+ */
+ async list(options: {
+ page?: number;
+ limit?: number;
+ toolkits?: string[];
+ authConfigs?: string[];
+ name?: string;
+ }): Promise<ReturnType<typeof transformMcpListResponse>> {
+ // List MCP servers with error handling
+ let listResponse;
+ try {
+ listResponse = await this.client.mcp.list({
+ page_no: options.page || 1,
+ limit: options.limit || 10,
+ toolkits: options?.toolkits?.join(',') || '',
+ auth_config_ids: options?.authConfigs?.join(',') || '',
+ name: options?.name,
+ });
+ } catch (error) {
+ throw new ValidationError('Failed to list MCP servers', {
+ cause: error,
+ });
+ }
+
+ // Validate the list response
+ const listResponseResult = McpListResponseSchema.safeParse(listResponse);
+ if (listResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP server list response', {
+ cause: listResponseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ return transformMcpListResponse(listResponse);
+ }
+
+ /**
+ * Get details of a specific MCP server
+ * @param {string} id - Server UUID
+ * @returns {Promise<ReturnType<typeof transformMcpRetrieveResponse>>} Server details
+ *
+ * @example
+ * ```typescript
+ * const serverDetails = await composio.mcp.get('server-uuid');
+ * ```
+ */
+ async get(id: string): Promise<ReturnType<typeof transformMcpRetrieveResponse>> {
+ // Retrieve MCP server with error handling
+ let retrieveResponse;
+ try {
+ retrieveResponse = await this.client.mcp.retrieve(id);
+ } catch (error) {
+ throw new ValidationError('Failed to retrieve MCP server', {
+ cause: error,
+ });
+ }
+
+ // Validate the retrieve response
+ const retrieveResponseResult = McpRetrieveResponseSchema.safeParse(retrieveResponse);
+ if (retrieveResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP server retrieve response', {
+ cause: retrieveResponseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ return transformMcpRetrieveResponse(retrieveResponse);
+ }
+
+ /**
+ * Delete an MCP server
+ * @param {string} id - Server UUID
+ * @returns {Promise<ReturnType<typeof transformMcpDeleteResponse>>} Deletion response
+ *
+ * @example
+ * ```typescript
+ * const result = await composio.mcp.delete('server-uuid');
+ * ```
+ */
+ async delete(id: string): Promise<ReturnType<typeof transformMcpDeleteResponse>> {
+ // Delete MCP server with error handling
+ let deleteResponse;
+ try {
+ deleteResponse = await this.client.mcp.delete(id);
+ } catch (error) {
+ throw new ValidationError('Failed to delete MCP server', {
+ cause: error,
+ });
+ }
+
+ // Validate the delete response
+ const deleteResponseResult = McpDeleteResponseSchema.safeParse(deleteResponse);
+ if (deleteResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP server delete response', {
+ cause: deleteResponseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ return transformMcpDeleteResponse(deleteResponse);
+ }
+
+ /**
+ * Update an MCP server configuration
+ * @param {string} id - Server UUID
+ * @param {string} name - New unique name for the server
+ * @param {MCPToolkitConfig[]} toolkitConfigs - Array of toolkit configurations
+ * @param {MCPAuthOptions} [authOptions] - Updated authentication options
+ * @returns {Promise<ReturnType<typeof transformMcpUpdateResponse>>} Updated server details
+ *
+ * @example
+ * ```typescript
+ * const updatedServer = await composio.mcp.update(
+ * "server-uuid",
+ * "my-updated-server",
+ * [
+ * {
+ * toolkit: "GMAIL",
+ * authConfigId: "ac_sdhkjfhjksdk",
+ * allowedTools: ["GMAIL_FETCH_EMAILS"],
+ * },
+ * ],
+ * {
+ * useComposioManagedAuth: true,
+ * }
+ * );
+ * ```
+ */
+ async update(
+ id: string,
+ name: string,
+ toolkitConfigs: MCPToolkitConfig[],
+ authOptions?: MCPAuthOptions
+ ): Promise<ReturnType<typeof transformMcpUpdateResponse>> {
+ // Validate inputs using Zod schemas
+ this.validateInputs(toolkitConfigs, authOptions);
+
+ const toolkits = toolkitConfigs.map(config => config.toolkit);
+
+ // Update MCP server with error handling
+ let updateResponse;
+ try {
+ updateResponse = await this.client.mcp.update(id, {
+ name,
+ toolkits: toolkits,
+ allowed_tools: toolkitConfigs.flatMap(config => config.allowedTools),
+ managed_auth_via_composio: authOptions?.useComposioManagedAuth || false,
+ });
+ } catch (error) {
+ throw new ValidationError('Failed to update MCP server', {
+ cause: error,
+ });
+ }
+
+ // Validate the update response
+ const updateResponseResult = McpUpdateResponseSchema.safeParse(updateResponse);
+ if (updateResponseResult.error) {
+ throw new ValidationError('Failed to parse MCP server update response', {
+ cause: updateResponseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ return transformMcpUpdateResponse(updateResponse);
+ }
+
+ /**
+ * Generate URL for an MCP server
+ * @param {GenerateURLParams} params - Parameters for URL generation
+ * @returns {Promise<ReturnType<typeof transformMcpGenerateUrlResponse>>} Generated URL response
+ *
+ * @example
+ * ```typescript
+ * const urlResponse = await composio.mcp.generateUrl({
+ * user_ids: ['user123'],
+ * connected_account_ids: ['account456'],
+ * mcp_server_id: 'server-uuid',
+ * managed_auth_by_composio: true
+ * });
+ * ```
+ */
+ async generateUrl(
+ params: GenerateURLParams
+ ): Promise<ReturnType<typeof transformMcpGenerateUrlResponse>> {
+ // Validate parameters using Zod schema (snake_case)
+ const paramsResult = GenerateURLParamsSnakeCaseSchema.safeParse(params);
+ if (paramsResult.error) {
+ throw new ValidationError('Failed to parse generateUrl parameters', {
+ cause: paramsResult.error,
+ });
+ }
+
+ // No transformation needed - params are already in snake_case
+ let urlResponse;
+ try {
+ urlResponse = await this.client.mcp.generate.url(params);
+ } catch (error) {
+ throw new ValidationError('Failed to generate MCP URL', {
+ cause: error,
+ });
+ }
+
+ // Validate the response
+ const responseResult = GenerateURLResponseSchema.safeParse(urlResponse);
+ if (responseResult.error) {
+ throw new ValidationError('Failed to parse MCP URL generation response', {
+ cause: responseResult.error,
+ });
+ }
+
+ // Transform the response to camelCase
+ return transformMcpGenerateUrlResponse(urlResponse);
+ }
+
+ /**
+ * Transform MCP URL response into the appropriate format.
+ * If the provider has a custom transform method, use it.
+ * Otherwise, use the default transformation.
+ *
+ * @param data - The MCP URL response data (in camelCase)
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Transformed response in appropriate format
+ */
+ private wrapMcpServerResponse(
+ data: McpUrlResponseCamelCase,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): T {
+ // Check if provider has a custom transform method
+ if (this.provider && typeof this.provider.wrapMcpServerResponse === 'function') {
+ // Convert to snake_case for backward compatibility with providers
+ const snakeCaseData: McpUrlResponse = {
+ mcp_url: data.mcpUrl,
+ ...(data.connectedAccountUrls && { connected_account_urls: data.connectedAccountUrls }),
+ ...(data.userIdsUrl && { user_ids_url: data.userIdsUrl }),
+ };
+
+ const transformed = this.provider.wrapMcpServerResponse(
+ snakeCaseData,
+ serverName,
+ connectedAccountIds,
+ userIds,
+ toolkits
+ );
+ return transformed as T;
+ }
+
+ // Default transformation
+ if (connectedAccountIds?.length && data.connectedAccountUrls) {
+ return data.connectedAccountUrls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as T;
+ } else if (userIds?.length && data.userIdsUrl) {
+ return data.userIdsUrl.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as T;
+ }
+ return {
+ url: new URL(data.mcpUrl),
+ name: serverName,
+ } as T;
+ }
+}
diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.ts
index 0d137dce9..724935024 100644
--- a/ts/packages/core/src/models/Tools.ts
+++ b/ts/packages/core/src/models/Tools.ts
@@ -47,7 +47,7 @@ import { telemetry } from '../telemetry/Telemetry';
export class Tools<
TToolCollection,
TTool,
- TProvider extends BaseComposioProvider<TToolCollection, TTool>,
+ TProvider extends BaseComposioProvider<TToolCollection, TTool, unknown>,
> {
private client: ComposioClient;
private readonly customTools: CustomTools;
diff --git a/ts/packages/core/src/provider/BaseProvider.ts b/ts/packages/core/src/provider/BaseProvider.ts
index 051c5a02d..5a35c9c4a 100644
--- a/ts/packages/core/src/provider/BaseProvider.ts
+++ b/ts/packages/core/src/provider/BaseProvider.ts
@@ -2,13 +2,14 @@ import { ComposioGlobalExecuteToolFnNotSetError } from '../errors/ToolErrors';
import { ExecuteToolModifiers } from '../types/modifiers.types';
import type { Tool, ToolExecuteParams, ToolExecuteResponse } from '../types/tool.types';
import { ExecuteToolFn, GlobalExecuteToolFn } from '../types/provider.types';
+import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
/**
* @internal
* Base class for all toolsets.
* This class is not meant to be used directly, but rather to be extended by different provider implementations.
*/
-abstract class BaseProvider {
+abstract class BaseProvider<TMcpResponse = McpServerGetResponse> {
/**
* @public
* The name of the provider.
@@ -56,6 +57,27 @@ abstract class BaseProvider {
}
return this._globalExecuteToolFn(toolSlug, body, modifers);
}
+
+ /**
+ * @public
+ * Optional method to transform MCP URL response into provider-specific format.
+ * Providers can override this method to define custom transformation logic
+ * for MCP server responses.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Transformed response in provider-specific format, or undefined to use default transformation
+ */
+ wrapMcpServerResponse?(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): TMcpResponse;
}
/**
@@ -63,7 +85,11 @@ abstract class BaseProvider {
* Base class for all non-agentic toolsets.
* This class is not meant to be used directly, but rather to be extended by concrete provider implementations.
*/
-export abstract class BaseNonAgenticProvider<TToolCollection, TTool> extends BaseProvider {
+export abstract class BaseNonAgenticProvider<
+ TToolCollection,
+ TTool,
+ TMcpResponse = McpServerGetResponse,
+> extends BaseProvider<TMcpResponse> {
override readonly _isAgentic = false;
/**
@@ -85,18 +111,24 @@ export abstract class BaseNonAgenticProvider<TToolCollection, TTool> extends Bas
* Base class for all agentic toolsets.
* This class is not meant to be used directly, but rather to be extended by concrete provider implementations.
*/
-export abstract class BaseAgenticProvider<TToolCollection, TTool> extends BaseProvider {
+export abstract class BaseAgenticProvider<
+ TToolCollection,
+ TTool,
+ TMcpResponse = McpServerGetResponse,
+> extends BaseProvider<TMcpResponse> {
override readonly _isAgentic = true;
/**
* Wrap a tool in the provider specific format.
* @param tool - The tool to wrap.
+ * @param executeTool - The function to execute the tool.
* @returns The wrapped tool.
*/
abstract wrapTool(tool: Tool, executeTool: ExecuteToolFn): TTool;
/**
* Wrap a list of tools in the provider specific format.
* @param tools - The tools to wrap.
+ * @param executeTool - The function to execute the tool.
* @returns The wrapped tools.
*/
abstract wrapTools(tools: Tool[], executeTool: ExecuteToolFn): TToolCollection;
@@ -107,6 +139,6 @@ export abstract class BaseAgenticProvider<TToolCollection, TTool> extends BasePr
* Base type for all toolsets.
* This type is used to infer the type of the provider from the provider implementation.
*/
-export type BaseComposioProvider<TToolCollection, TTool> =
- | BaseNonAgenticProvider<TToolCollection, TTool>
- | BaseAgenticProvider<TToolCollection, TTool>;
+export type BaseComposioProvider<TToolCollection, TTool, TMcpResponse = McpServerGetResponse> =
+ | BaseNonAgenticProvider<TToolCollection, TTool, TMcpResponse>
+ | BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>;
diff --git a/ts/packages/core/src/provider/ComposioProvider.ts b/ts/packages/core/src/provider/ComposioProvider.ts
index c77f84a65..c66eb8b92 100644
--- a/ts/packages/core/src/provider/ComposioProvider.ts
+++ b/ts/packages/core/src/provider/ComposioProvider.ts
@@ -14,6 +14,10 @@ interface CustomTool {
export class ComposioProvider extends BaseNonAgenticProvider<Array<CustomTool>, CustomTool> {
readonly name = 'ComposioProvider';
+ constructor() {
+ super();
+ }
+
wrapTool = (tool: Tool): CustomTool => {
return tool as CustomTool;
};
diff --git a/ts/packages/core/src/provider/OpenAIProvider.ts b/ts/packages/core/src/provider/OpenAIProvider.ts
index d9c3eca8b..bc7788418 100644
--- a/ts/packages/core/src/provider/OpenAIProvider.ts
+++ b/ts/packages/core/src/provider/OpenAIProvider.ts
@@ -14,25 +14,27 @@ import { Tool, ToolExecuteParams } from '../types/tool.types';
import logger from '../utils/logger';
import { ExecuteToolModifiers } from '../types/modifiers.types';
import { ExecuteToolFnOptions } from '../types/provider.types';
+import { McpUrlResponse, McpServerGetResponse } from '../types/mcp.types';
export type OpenAiTool = OpenAI.ChatCompletionTool;
export type OpenAiToolCollection = Array<OpenAiTool>;
+
export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection, OpenAiTool> {
readonly name = 'openai';
-
+
/**
* Creates a new instance of the OpenAIProvider.
- *
+ *
* This is the default provider for the Composio SDK and is automatically
* available without additional installation.
- *
+ *
* @example
* ```typescript
* // The OpenAIProvider is used by default when initializing Composio
* const composio = new Composio({
* apiKey: 'your-api-key'
* });
- *
+ *
* // You can also explicitly specify it
* const composio = new Composio({
* apiKey: 'your-api-key',
@@ -43,16 +45,54 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
constructor() {
super();
}
-
+
+ /**
+ * Transform MCP URL response into OpenAI-specific format.
+ * OpenAI uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // OpenAI uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in the OpenAI function calling format.
- *
+ *
* This method transforms a Composio tool definition into the format
* expected by OpenAI's function calling API.
- *
+ *
* @param tool - The Composio tool to wrap
* @returns The wrapped tool in OpenAI format
- *
+ *
* @example
* ```typescript
* // Wrap a single tool for use with OpenAI
@@ -67,7 +107,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* required: ['query']
* }
* };
- *
+ *
* const openAITool = provider.wrapTool(composioTool);
* ```
*/
@@ -85,13 +125,13 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
/**
* Wraps multiple Composio tools in the OpenAI function calling format.
- *
+ *
* This method transforms a list of Composio tools into the format
* expected by OpenAI's function calling API.
- *
+ *
* @param tools - Array of Composio tools to wrap
* @returns Array of wrapped tools in OpenAI format
- *
+ *
* @example
* ```typescript
* // Wrap multiple tools for use with OpenAI
@@ -117,7 +157,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* }
* }
* ];
- *
+ *
* const openAITools = provider.wrapTools(composioTools);
* ```
*/
@@ -127,16 +167,16 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
/**
* Executes a tool call from OpenAI's chat completion.
- *
+ *
* This method processes a tool call from OpenAI's chat completion API,
* executes the corresponding Composio tool, and returns the result.
- *
+ *
* @param {string} userId - The user ID for authentication and tracking
* @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
* @returns {Promise<string>} The result of the tool call as a JSON string
- *
+ *
* @example
* ```typescript
* // Execute a tool call from OpenAI
@@ -148,7 +188,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* arguments: '{"query":"composio documentation"}'
* }
* };
- *
+ *
* const result = await provider.executeToolCall(
* 'user123',
* toolCall,
@@ -184,7 +224,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
* @returns {Promise<string[]>} Array of tool execution results as JSON strings
- *
+ *
* @example
* ```typescript
* // Handle tool calls from a chat completion response
@@ -206,7 +246,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* }
* ]
* };
- *
+ *
* const results = await provider.handleToolCalls(
* 'user123',
* chatCompletion,
@@ -243,7 +283,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
* @returns {Promise<OpenAI.Beta.Threads.Runs.RunSubmitToolOutputsParams.ToolOutput[]>} Array of tool outputs for submission
- *
+ *
* @example
* ```typescript
* // Handle tool calls from an OpenAI Assistant run
@@ -264,13 +304,13 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* }
* }
* };
- *
+ *
* const toolOutputs = await provider.handleAssistantMessage(
* 'user123',
* run,
* { connectedAccountId: 'conn_xyz456' }
* );
- *
+ *
* // Submit tool outputs back to OpenAI
* await openai.beta.threads.runs.submitToolOutputs(
* thread.id,
@@ -324,7 +364,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
* @returns {AsyncGenerator<OpenAI.Beta.Assistants.AssistantStreamEvent, void, unknown>} Generator yielding stream events
- *
+ *
* @example
* ```typescript
* // Process an OpenAI Assistant stream with tool calls
@@ -333,7 +373,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* assistant_id: 'asst_abc123',
* tools: provider.wrapTools(composioTools)
* });
- *
+ *
* // Process the stream and handle tool calls
* const streamProcessor = provider.waitAndHandleAssistantStreamToolCalls(
* 'user123',
@@ -342,7 +382,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* thread,
* { connectedAccountId: 'conn_xyz456' }
* );
- *
+ *
* // Consume the stream events
* for await (const event of streamProcessor) {
* if (event.event === 'thread.message.delta') {
@@ -440,7 +480,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* @param {ExecuteToolFnOptions} [options] - Optional execution options
* @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
* @returns {Promise<OpenAI.Beta.Threads.Run>} The final run object after completion
- *
+ *
* @example
* ```typescript
* // Process an OpenAI Assistant run with tool calls
@@ -449,12 +489,12 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* role: 'user',
* content: 'Find information about Composio'
* });
- *
+ *
* let run = await openai.beta.threads.runs.create(thread.id, {
* assistant_id: 'asst_abc123',
* tools: provider.wrapTools(composioTools)
* });
- *
+ *
* // Wait for the run to complete, handling any tool calls
* run = await provider.waitAndHandleAssistantToolCalls(
* 'user123',
@@ -463,7 +503,7 @@ export class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection,
* thread,
* { connectedAccountId: 'conn_xyz456' }
* );
- *
+ *
* // Get the final messages after run completion
* const messages = await openai.beta.threads.messages.list(thread.id);
* console.log(messages.data[0].content);
diff --git a/ts/packages/core/src/types/mcp.types.ts b/ts/packages/core/src/types/mcp.types.ts
new file mode 100644
index 000000000..4b986eba5
--- /dev/null
+++ b/ts/packages/core/src/types/mcp.types.ts
@@ -0,0 +1,321 @@
+import {
+ CustomCreateResponse,
+ McpCreateResponse,
+ GenerateURLResponse,
+} from '@composio/client/resources/mcp';
+import { z } from 'zod';
+
+/**
+ * MCP Create Method Input Types
+ */
+export const MCPToolkitConfigSchema = z.object({
+ toolkit: z.string().min(1, 'Toolkit name cannot be empty'),
+ authConfigId: z.string().min(1, 'Auth config ID cannot be empty'),
+ allowedTools: z
+ .array(z.string().min(1, 'Tool name cannot be empty'))
+ .min(1, 'At least one tool must be specified'),
+});
+
+export type MCPToolkitConfig = z.infer<typeof MCPToolkitConfigSchema>;
+
+export const MCPToolkitConfigsArraySchema = z
+ .array(MCPToolkitConfigSchema)
+ .min(1, 'At least one toolkit configuration is required')
+ .refine(configs => {
+ const toolkits = configs.map(config => config.toolkit);
+ const uniqueToolkits = new Set(toolkits);
+ return uniqueToolkits.size === toolkits.length;
+ }, 'Duplicate toolkits are not allowed. Each toolkit must be unique.');
+
+export const MCPAuthOptionsSchema = z.object({
+ useComposioManagedAuth: z.boolean().optional(),
+});
+
+export type MCPAuthOptions = z.infer<typeof MCPAuthOptionsSchema>;
+
+export const MCPGetServerParamsSchema = z
+ .object({
+ userId: z.string().min(1, 'User ID cannot be empty').optional(),
+ connectedAccountIds: z
+ .record(z.string(), z.string().min(1, 'Account ID cannot be empty'))
+ .optional(),
+ })
+ .refine(
+ data => {
+ // Ensure exactly one of userId or connectedAccountIds is provided
+ const hasUserId = !!data.userId;
+ const hasConnectedAccountIds =
+ !!data.connectedAccountIds && Object.keys(data.connectedAccountIds).length > 0;
+ return hasUserId !== hasConnectedAccountIds; // XOR: exactly one should be true
+ },
+ {
+ message: 'Must provide either userId or connectedAccountIds, but not both',
+ }
+ );
+
+export type MCPGetServerParams = z.infer<typeof MCPGetServerParamsSchema>;
+
+export type MCPInstanceParams = {
+ serverId: string;
+ userIds?: string[];
+ connectedAccountIds?: string[];
+ useComposioManagedAuth?: boolean;
+};
+
+export const MCPGenerateURLParamsSchema = z.object({
+ userIds: z.array(z.string()).optional(),
+ connectedAccountIds: z.array(z.string()).optional(),
+ useComposioManagedAuth: z.boolean().optional(),
+});
+export type MCPGenerateURLParams = z.infer<typeof MCPGenerateURLParamsSchema>;
+
+// Snake_case schema for validating the imported GenerateURLParams type
+export const GenerateURLParamsSnakeCaseSchema = z.object({
+ user_ids: z.array(z.string()).optional(),
+ connected_account_ids: z.array(z.string()).optional(),
+ mcp_server_id: z.string(),
+ managed_auth_by_composio: z.boolean().optional(),
+});
+
+export const GenerateURLParamsSchema = z.object({
+ userIds: z.array(z.string()).optional(),
+ connectedAccountIds: z.array(z.string()).optional(),
+ mcpServerId: z.string(),
+ managedAuthByComposio: z.boolean().optional(),
+});
+export type GenerateURLParamsValidated = z.infer<typeof GenerateURLParamsSchema>;
+
+// CamelCase response schema for generate URL
+export const GenerateURLResponseCamelCaseSchema = z.object({
+ connectedAccountUrls: z.array(z.string()).optional(),
+ userIdsUrl: z.array(z.string()).optional(),
+ mcpUrl: z.string().min(1, 'MCP URL cannot be empty'),
+});
+
+// Snake_case response schema for API
+export const GenerateURLResponseSchema = z.object({
+ connected_account_urls: z.array(z.string()).optional(),
+ user_ids_url: z.array(z.string()).optional(),
+ mcp_url: z.string().min(1, 'MCP URL cannot be empty'),
+});
+
+export type GenerateURLResponseValidated = z.infer<typeof GenerateURLResponseCamelCaseSchema>;
+
+/**
+ * MCP Server Type (Single App)
+ */
+export const MCPSingleAppServerSchema = z.object({
+ name: z.string().describe('Name of the MCP server'),
+ tools: z.array(z.string()).describe('List of allowed tools'),
+ authConfigId: z.string().optional().describe('Auth config ID for the server'),
+});
+export type MCPSingleAppServer = z.infer<typeof MCPSingleAppServerSchema>;
+
+/**
+ * MCP Server Type (Multi App)
+ */
+export const MCPMultiAppServerSchema = z.object({
+ name: z.string().describe('Name of the MCP server'),
+ tools: z.array(z.string()).describe('List of allowed tools across toolkits'),
+ toolkits: z.array(z.string()).describe('List of allowed toolkits'),
+});
+export type MCPMultiAppServer = z.infer<typeof MCPMultiAppServerSchema>;
+
+/**
+ * MCP Server Type (Combined)
+ */
+export const MCPServerSchema = z.object({
+ id: z.string().describe('Unique identifier for the MCP server'),
+ type: z.enum(['single', 'multi']).describe('Type of MCP server'),
+ createdAt: z.string().describe('Creation timestamp'),
+ updatedAt: z.string().describe('Last update timestamp'),
+ status: z.enum(['active', 'inactive', 'error']).default('active'),
+ config: z.union([MCPSingleAppServerSchema, MCPMultiAppServerSchema]),
+});
+export type MCPServer = z.infer<typeof MCPServerSchema>;
+
+/**
+ * MCP Server List Response
+ */
+export const MCPServerListResponseSchema = z.object({
+ items: z.array(MCPServerSchema),
+ total: z.number(),
+ page: z.number(),
+ pageSize: z.number(),
+});
+export type MCPServerListResponse = z.infer<typeof MCPServerListResponseSchema>;
+
+/**
+ * MCP Server Update Parameters
+ */
+export const MCPServerUpdateParamsSchema = z.object({
+ name: z.string().optional().describe('New name for the server'),
+ toolkits: z.array(z.string()).optional().describe('Updated list of toolkits'),
+ allowedTools: z.array(z.string()).optional().describe('Updated list of allowed tools'),
+});
+export type MCPServerUpdateParams = z.infer<typeof MCPServerUpdateParamsSchema>;
+
+/**
+ * MCP Server Create Response
+ */
+export const MCPServerCreateResponseSchema = MCPServerSchema;
+export type MCPServerCreateResponse = z.infer<typeof MCPServerCreateResponseSchema>;
+
+/**
+ * MCP Create Method Response Type
+ * Extends the API response with a getServer method for retrieving server instances
+ */
+export type MCPCreateMethodResponse<T = GenerateURLResponse> = (
+ | McpCreateResponse
+ | CustomCreateResponse
+) & {
+ toolkits: string[];
+ getServer: (params: MCPGetServerParams) => Promise<T>;
+};
+
+/**
+ * MCP Server URL Information
+ */
+export type McpServerUrlInfo = {
+ url: URL;
+ name: string;
+ toolkit?: string;
+};
+
+export type McpServerGetResponse = McpServerUrlInfo | McpServerUrlInfo[];
+
+// CamelCase URL response
+export type McpUrlResponseCamelCase = {
+ connectedAccountUrls?: string[];
+ userIdsUrl?: string[];
+ mcpUrl: string;
+};
+
+// Snake_case URL response (for internal API use)
+export type McpUrlResponse = {
+ connected_account_urls?: string[];
+ user_ids_url?: string[];
+ mcp_url: string;
+};
+
+export type McpServerCreateResponse<T> = (McpCreateResponse | CustomCreateResponse) & {
+ toolkits: string[];
+ getServer: (params: MCPGetServerParams) => Promise<T>;
+};
+
+// CamelCase create response schema
+export const CustomCreateResponseCamelCaseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ createdAt: z.string().nullish(),
+ updatedAt: z.string().nullish(),
+ status: z.string().nullish(),
+});
+
+// Snake_case create response schema (for API)
+export const CustomCreateResponseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ created_at: z.string().nullish(),
+ updated_at: z.string().nullish(),
+ status: z.string().nullish(),
+});
+
+export type CustomCreateResponseValidated = z.infer<typeof CustomCreateResponseCamelCaseSchema>;
+
+// CamelCase list response schema
+export const McpListResponseCamelCaseSchema = z.object({
+ items: z
+ .array(
+ z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ createdAt: z.string().optional(),
+ updatedAt: z.string().optional(),
+ status: z.string().optional(),
+ })
+ )
+ .optional(),
+});
+
+// Snake_case list response schema (for API)
+export const McpListResponseSchema = z.object({
+ items: z
+ .array(
+ z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ created_at: z.string().optional(),
+ updated_at: z.string().optional(),
+ status: z.string().optional(),
+ })
+ )
+ .optional(),
+});
+
+// CamelCase retrieve response schema
+export const McpRetrieveResponseCamelCaseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ createdAt: z.string().optional(),
+ updatedAt: z.string().optional(),
+ status: z.string().optional(),
+ toolkits: z.array(z.string()).optional(),
+ tools: z.array(z.string()).optional(),
+ managedAuthViaComposio: z.boolean().optional(),
+});
+
+// Snake_case retrieve response schema (for API)
+export const McpRetrieveResponseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ created_at: z.string().optional(),
+ updated_at: z.string().optional(),
+ status: z.string().optional(),
+ toolkits: z.array(z.string()).optional(),
+ tools: z.array(z.string()).optional(),
+ managed_auth_via_composio: z.boolean().optional(),
+});
+
+// CamelCase delete response schema
+export const McpDeleteResponseCamelCaseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ deleted: z.boolean().optional(),
+ message: z.string().optional(),
+});
+
+// Snake_case delete response schema (for API)
+export const McpDeleteResponseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ deleted: z.boolean().optional(),
+ message: z.string().optional(),
+});
+
+// CamelCase update response schema
+export const McpUpdateResponseCamelCaseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ createdAt: z.string().optional(),
+ updatedAt: z.string().optional(),
+ status: z.string().optional(),
+ toolkits: z.array(z.string()).optional(),
+ tools: z.array(z.string()).optional(),
+});
+
+// Snake_case update response schema (for API)
+export const McpUpdateResponseSchema = z.object({
+ id: z.string().min(1, 'Server ID cannot be empty'),
+ name: z.string().min(1, 'Server name cannot be empty'),
+ created_at: z.string().optional(),
+ updated_at: z.string().optional(),
+ status: z.string().optional(),
+ toolkits: z.array(z.string()).optional(),
+ tools: z.array(z.string()).optional(),
+});
+
+// Export camelCase response types
+export type McpListResponseCamelCase = z.infer<typeof McpListResponseCamelCaseSchema>;
+export type McpRetrieveResponseCamelCase = z.infer<typeof McpRetrieveResponseCamelCaseSchema>;
+export type McpDeleteResponseCamelCase = z.infer<typeof McpDeleteResponseCamelCaseSchema>;
+export type McpUpdateResponseCamelCase = z.infer<typeof McpUpdateResponseCamelCaseSchema>;
+export type GenerateURLResponseCamelCase = z.infer<typeof GenerateURLResponseCamelCaseSchema>;
diff --git a/ts/packages/core/src/types/modifiers.types.ts b/ts/packages/core/src/types/modifiers.types.ts
index 0ce28afd1..14b1dc9ce 100644
--- a/ts/packages/core/src/types/modifiers.types.ts
+++ b/ts/packages/core/src/types/modifiers.types.ts
@@ -310,8 +310,8 @@ export type AgenticToolOptions = ToolOptions & ExecuteToolModifiers;
* ```
*/
export type ProviderOptions<TProvider> =
- TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool>
- ? TProvider extends BaseAgenticProvider<TToolCollection, TTool>
+ TProvider extends BaseComposioProvider<infer TToolCollection, infer TTool, infer TMcpResponse>
+ ? TProvider extends BaseAgenticProvider<TToolCollection, TTool, TMcpResponse>
? AgenticToolOptions
: ToolOptions
: never;
diff --git a/ts/packages/core/src/utils/transformers/mcp.ts b/ts/packages/core/src/utils/transformers/mcp.ts
new file mode 100644
index 000000000..6f56257c1
--- /dev/null
+++ b/ts/packages/core/src/utils/transformers/mcp.ts
@@ -0,0 +1,148 @@
+import { ValidationError } from '../../errors/ValidationErrors';
+import {
+ CustomCreateResponseCamelCaseSchema,
+ GenerateURLResponseCamelCaseSchema,
+ McpListResponseCamelCaseSchema,
+ McpRetrieveResponseCamelCaseSchema,
+ McpDeleteResponseCamelCaseSchema,
+ McpUpdateResponseCamelCaseSchema,
+} from '../../types/mcp.types';
+import {
+ CustomCreateResponse,
+ GenerateURLResponse,
+ McpListResponse,
+ McpCreateResponse,
+ McpDeleteResponse,
+ McpUpdateResponse,
+} from '@composio/client/resources/mcp';
+
+/**
+ * Transform MCP create response from snake_case to camelCase
+ */
+export function transformMcpCreateResponse(response: CustomCreateResponse) {
+ const result = CustomCreateResponseCamelCaseSchema.safeParse({
+ id: response.id,
+ name: response.name,
+ createdAt: (response as unknown as Record<string, unknown>).created_at,
+ updatedAt: (response as unknown as Record<string, unknown>).updated_at,
+ status: (response as unknown as Record<string, unknown>).status,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP create response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
+
+/**
+ * Transform MCP list response from snake_case to camelCase
+ */
+export function transformMcpListResponse(response: McpListResponse) {
+ const transformedItems = response.items?.map(item => ({
+ id: item.id,
+ name: item.name,
+ createdAt: item.created_at,
+ updatedAt: item.updated_at,
+ status: (item as unknown as Record<string, unknown>).status,
+ }));
+
+ const result = McpListResponseCamelCaseSchema.safeParse({
+ items: transformedItems,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP list response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
+
+/**
+ * Transform MCP retrieve response from snake_case to camelCase
+ */
+export function transformMcpRetrieveResponse(response: McpCreateResponse) {
+ const result = McpRetrieveResponseCamelCaseSchema.safeParse({
+ id: response.id,
+ name: response.name,
+ createdAt: response.created_at,
+ updatedAt: response.updated_at,
+ status: (response as unknown as Record<string, unknown>).status,
+ toolkits: response.toolkits,
+ tools: (response as unknown as Record<string, unknown>).tools,
+ managedAuthViaComposio: response.managed_auth_via_composio,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP retrieve response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
+
+/**
+ * Transform MCP delete response from snake_case to camelCase
+ */
+export function transformMcpDeleteResponse(response: McpDeleteResponse) {
+ const result = McpDeleteResponseCamelCaseSchema.safeParse({
+ id: (response as unknown as Record<string, unknown>).id,
+ deleted: (response as unknown as Record<string, unknown>).deleted,
+ message: (response as unknown as Record<string, unknown>).message,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP delete response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
+
+/**
+ * Transform MCP update response from snake_case to camelCase
+ */
+export function transformMcpUpdateResponse(response: McpUpdateResponse) {
+ const result = McpUpdateResponseCamelCaseSchema.safeParse({
+ id: response.id,
+ name: response.name,
+ createdAt: response.created_at,
+ updatedAt: response.updated_at,
+ status: (response as unknown as Record<string, unknown>).status,
+ toolkits: response.toolkits,
+ tools: (response as unknown as Record<string, unknown>).tools,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP update response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
+
+/**
+ * Transform MCP generate URL response from snake_case to camelCase
+ */
+export function transformMcpGenerateUrlResponse(response: GenerateURLResponse) {
+ const result = GenerateURLResponseCamelCaseSchema.safeParse({
+ connectedAccountUrls: response.connected_account_urls,
+ userIdsUrl: response.user_ids_url,
+ mcpUrl: response.mcp_url,
+ });
+
+ if (!result.success) {
+ throw new ValidationError('Failed to parse MCP generate URL response', {
+ cause: result.error,
+ });
+ }
+
+ return result.data;
+}
diff --git a/ts/packages/core/test/models/mcp.test.ts b/ts/packages/core/test/models/mcp.test.ts
new file mode 100644
index 000000000..0f10dff23
--- /dev/null
+++ b/ts/packages/core/test/models/mcp.test.ts
@@ -0,0 +1,677 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MCP } from '../../src/models/MCP';
+import ComposioClient from '@composio/client';
+import { telemetry } from '../../src/telemetry/Telemetry';
+import { ValidationError } from '../../src/errors/ValidationErrors';
+import { BaseAgenticProvider } from '../../src/provider/BaseProvider';
+import { Tool } from '../../src/types/tool.types';
+import { ExecuteToolFn } from '../../src/types/provider.types';
+import { McpUrlResponse } from '../../src/types/mcp.types';
+import {
+ transformMcpCreateResponse,
+ transformMcpListResponse,
+ transformMcpRetrieveResponse,
+ transformMcpDeleteResponse,
+ transformMcpUpdateResponse,
+ transformMcpGenerateUrlResponse,
+} from '../../src/utils/transformers/mcp';
+
+// Mock dependencies
+vi.mock('../../src/telemetry/Telemetry', () => ({
+ telemetry: {
+ instrument: vi.fn(),
+ },
+}));
+
+// Define types for mock responses
+interface MockItem {
+ id: string;
+ name: string;
+ created_at?: string;
+ updated_at?: string;
+ status?: string;
+}
+
+interface MockListResponse {
+ items?: MockItem[];
+}
+
+vi.mock('../../src/utils/transformers/mcp', () => ({
+ transformMcpCreateResponse: vi.fn(response => ({
+ id: response.id,
+ name: response.name,
+ createdAt: response.created_at,
+ updatedAt: response.updated_at,
+ status: response.status,
+ })),
+ transformMcpListResponse: vi.fn((response: MockListResponse) => ({
+ items: response.items?.map(item => ({
+ id: item.id,
+ name: item.name,
+ createdAt: item.created_at,
+ updatedAt: item.updated_at,
+ status: item.status,
+ })),
+ })),
+ transformMcpRetrieveResponse: vi.fn(response => ({
+ id: response.id,
+ name: response.name,
+ createdAt: response.created_at,
+ updatedAt: response.updated_at,
+ status: response.status,
+ toolkits: response.toolkits,
+ tools: response.tools,
+ managedAuthViaComposio: response.managed_auth_via_composio,
+ })),
+ transformMcpDeleteResponse: vi.fn(response => ({
+ id: response.id,
+ deleted: response.deleted,
+ message: response.message,
+ })),
+ transformMcpUpdateResponse: vi.fn(response => ({
+ id: response.id,
+ name: response.name,
+ createdAt: response.created_at,
+ updatedAt: response.updated_at,
+ status: response.status,
+ toolkits: response.toolkits,
+ tools: response.tools,
+ })),
+ transformMcpGenerateUrlResponse: vi.fn(response => ({
+ connectedAccountUrls: response.connected_account_urls,
+ userIdsUrl: response.user_ids_url,
+ mcpUrl: response.mcp_url,
+ })),
+}));
+
+// Create mock client with MCP-related methods
+const createMockClient = () => ({
+ baseURL: 'https://api.composio.dev',
+ apiKey: 'test-api-key',
+ mcp: {
+ custom: {
+ create: vi.fn(),
+ },
+ generate: {
+ url: vi.fn(),
+ },
+ list: vi.fn(),
+ retrieve: vi.fn(),
+ delete: vi.fn(),
+ update: vi.fn(),
+ },
+});
+
+// Mock response data
+const mockCreateResponse = {
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-01T00:00:00Z',
+ status: 'active',
+};
+
+const mockListResponse = {
+ items: [
+ {
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-01T00:00:00Z',
+ status: 'active',
+ },
+ {
+ id: 'mcp_456',
+ name: 'another-mcp-server',
+ created_at: '2024-01-02T00:00:00Z',
+ updated_at: '2024-01-02T00:00:00Z',
+ status: 'active',
+ },
+ ],
+};
+
+const mockRetrieveResponse = {
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-01T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail', 'github'],
+ tools: ['GMAIL_FETCH_EMAILS', 'GITHUB_GET_REPO'],
+ managed_auth_via_composio: true,
+};
+
+const mockGenerateUrlResponse = {
+ connected_account_urls: ['https://mcp.example.com/account1', 'https://mcp.example.com/account2'],
+ user_ids_url: ['https://mcp.example.com/user1', 'https://mcp.example.com/user2'],
+ mcp_url: 'https://mcp.example.com/server',
+};
+
+// Define types for mock provider
+type MockTool = Tool & { mockWrapped: boolean };
+type MockToolCollection = MockTool[];
+type MockMcpResponse = {
+ customFormat: boolean;
+ serverName: string;
+ urls: string[];
+};
+
+// Mock provider
+class MockProvider extends BaseAgenticProvider<MockToolCollection, MockTool, MockMcpResponse> {
+ readonly name = 'mock-provider';
+
+ wrapTool(tool: Tool, executeTool: ExecuteToolFn): MockTool {
+ return { ...tool, mockWrapped: true };
+ }
+
+ wrapTools(tools: Tool[], executeTool: ExecuteToolFn): MockToolCollection {
+ return tools.map(tool => this.wrapTool(tool, executeTool));
+ }
+
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): MockMcpResponse {
+ return {
+ customFormat: true,
+ serverName,
+ urls: data.connected_account_urls || [data.mcp_url],
+ };
+ }
+}
+
+describe('MCP', () => {
+ let mcp: MCP;
+ let mockClient: ReturnType<typeof createMockClient>;
+ let mockProvider: MockProvider;
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mockClient = createMockClient();
+ mcp = new MCP(mockClient as unknown as ComposioClient);
+ });
+
+ describe('constructor', () => {
+ it('should create an instance successfully', () => {
+ expect(mcp).toBeInstanceOf(MCP);
+ expect(telemetry.instrument).toHaveBeenCalledWith(mcp);
+ });
+
+ it('should store the client reference', () => {
+ expect(mcp['client']).toBe(mockClient);
+ });
+
+ it('should accept an optional provider', () => {
+ mockProvider = new MockProvider();
+ const mcpWithProvider = new MCP(mockClient as unknown as ComposioClient, mockProvider);
+ expect(mcpWithProvider['provider']).toBe(mockProvider);
+ });
+ });
+
+ describe('create', () => {
+ const toolkitConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_gmail123',
+ allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
+ },
+ ];
+
+ it('should create an MCP server successfully', async () => {
+ mockClient.mcp.custom.create.mockResolvedValue(mockCreateResponse);
+
+ const result = await mcp.create('test-server', toolkitConfigs, {
+ useComposioManagedAuth: true,
+ });
+
+ expect(mockClient.mcp.custom.create).toHaveBeenCalledWith({
+ name: 'test-server',
+ toolkits: ['gmail'],
+ custom_tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
+ managed_auth_via_composio: true,
+ auth_config_ids: ['ac_gmail123'],
+ });
+
+ expect(result).toMatchObject({
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ toolkits: ['gmail'],
+ });
+
+ expect(result.getServer).toBeDefined();
+ expect(typeof result.getServer).toBe('function');
+ });
+
+ it('should validate toolkit configurations', async () => {
+ const invalidConfigs = [
+ {
+ toolkit: '', // Empty toolkit
+ authConfigId: 'ac_123',
+ allowedTools: ['TOOL_1'],
+ },
+ ];
+
+ await expect(mcp.create('test-server', invalidConfigs)).rejects.toThrow(ValidationError);
+ });
+
+ it('should validate auth options', async () => {
+ const invalidAuthOptions = {
+ useComposioManagedAuth: 'true' as unknown as boolean, // Should be boolean
+ };
+
+ await expect(mcp.create('test-server', toolkitConfigs, invalidAuthOptions)).rejects.toThrow(
+ ValidationError
+ );
+ });
+
+ it('should throw ValidationError when duplicate toolkits are provided', async () => {
+ const duplicateConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_gmail123',
+ allowedTools: ['GMAIL_FETCH_EMAILS'],
+ },
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_gmail456',
+ allowedTools: ['GMAIL_SEND_EMAIL'],
+ },
+ ];
+
+ await expect(mcp.create('test-server', duplicateConfigs)).rejects.toThrow(
+ 'Duplicate toolkits are not allowed'
+ );
+ });
+
+ it('should handle server creation errors', async () => {
+ mockClient.mcp.custom.create.mockRejectedValue(new Error('Server creation failed'));
+
+ await expect(mcp.create('test-server', toolkitConfigs)).rejects.toThrow(
+ 'Failed to create MCP server'
+ );
+ });
+ });
+
+ describe('getServer', () => {
+ beforeEach(() => {
+ // Mock the get method that getServer calls internally
+ vi.spyOn(mcp, 'get').mockResolvedValue({
+ id: mockRetrieveResponse.id,
+ name: mockRetrieveResponse.name,
+ createdAt: mockRetrieveResponse.created_at,
+ updatedAt: mockRetrieveResponse.updated_at,
+ status: mockRetrieveResponse.status,
+ toolkits: mockRetrieveResponse.toolkits,
+ tools: mockRetrieveResponse.tools,
+ managedAuthViaComposio: mockRetrieveResponse.managed_auth_via_composio,
+ });
+ });
+
+ it('should get server URLs with connected account IDs', async () => {
+ mockClient.mcp.generate.url.mockResolvedValue(mockGenerateUrlResponse);
+
+ const result = await mcp.getServer('mcp_123', {
+ connectedAccountIds: {
+ gmail: 'account_123',
+ github: 'account_456',
+ },
+ });
+
+ expect(mockClient.mcp.generate.url).toHaveBeenCalledWith({
+ user_ids: [],
+ connected_account_ids: ['account_123', 'account_456'],
+ mcp_server_id: 'mcp_123',
+ managed_auth_by_composio: true,
+ });
+
+ expect(result).toBeDefined();
+ });
+
+ it('should get server URLs with user ID', async () => {
+ mockClient.mcp.generate.url.mockResolvedValue(mockGenerateUrlResponse);
+
+ const result = await mcp.getServer('mcp_123', {
+ userId: 'user_123',
+ });
+
+ expect(mockClient.mcp.generate.url).toHaveBeenCalledWith({
+ user_ids: ['user_123'],
+ connected_account_ids: [],
+ mcp_server_id: 'mcp_123',
+ managed_auth_by_composio: true,
+ });
+ });
+
+ it('should validate that either userId or connectedAccountIds is provided', async () => {
+ await expect(mcp.getServer('mcp_123', {})).rejects.toThrow(
+ 'Must provide either userId or connectedAccountIds, but not both'
+ );
+ });
+
+ it('should validate that both userId and connectedAccountIds are not provided', async () => {
+ await expect(
+ mcp.getServer('mcp_123', {
+ userId: 'user_123',
+ connectedAccountIds: { gmail: 'account_123' },
+ })
+ ).rejects.toThrow('Must provide either userId or connectedAccountIds, but not both');
+ });
+
+ it('should validate toolkit names in connectedAccountIds', async () => {
+ await expect(
+ mcp.getServer('mcp_123', {
+ connectedAccountIds: {
+ slack: 'account_123', // Not in server's toolkits
+ },
+ })
+ ).rejects.toThrow('Invalid toolkits provided: slack');
+ });
+
+ it('should use custom provider transformation', async () => {
+ mockProvider = new MockProvider();
+ const mcpWithProvider = new MCP(mockClient as unknown as ComposioClient, mockProvider);
+ vi.spyOn(mcpWithProvider, 'get').mockResolvedValue({
+ id: mockRetrieveResponse.id,
+ name: mockRetrieveResponse.name,
+ createdAt: mockRetrieveResponse.created_at,
+ updatedAt: mockRetrieveResponse.updated_at,
+ status: mockRetrieveResponse.status,
+ toolkits: mockRetrieveResponse.toolkits,
+ tools: mockRetrieveResponse.tools,
+ managedAuthViaComposio: mockRetrieveResponse.managed_auth_via_composio,
+ });
+
+ mockClient.mcp.generate.url.mockResolvedValue(mockGenerateUrlResponse);
+
+ const result = await mcpWithProvider.getServer('mcp_123', {
+ userId: 'user_123',
+ });
+
+ expect(result).toMatchObject({
+ customFormat: true,
+ serverName: 'test-mcp-server',
+ });
+ });
+ });
+
+ describe('list', () => {
+ it('should list MCP servers with default options', async () => {
+ mockClient.mcp.list.mockResolvedValue(mockListResponse);
+
+ const result = await mcp.list({});
+
+ expect(mockClient.mcp.list).toHaveBeenCalledWith({
+ page_no: 1,
+ limit: 10,
+ toolkits: '',
+ auth_config_ids: '',
+ name: undefined,
+ });
+
+ expect(result).toMatchObject({
+ items: expect.arrayContaining([
+ expect.objectContaining({
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ }),
+ ]),
+ });
+ });
+
+ it('should list MCP servers with filters', async () => {
+ mockClient.mcp.list.mockResolvedValue(mockListResponse);
+
+ const result = await mcp.list({
+ page: 2,
+ limit: 20,
+ toolkits: ['gmail', 'github'],
+ authConfigs: ['auth_123', 'auth_456'],
+ name: 'production',
+ });
+
+ expect(mockClient.mcp.list).toHaveBeenCalledWith({
+ page_no: 2,
+ limit: 20,
+ toolkits: 'gmail,github',
+ auth_config_ids: 'auth_123,auth_456',
+ name: 'production',
+ });
+ });
+
+ it('should handle list errors', async () => {
+ mockClient.mcp.list.mockRejectedValue(new Error('List failed'));
+
+ await expect(mcp.list({})).rejects.toThrow('Failed to list MCP servers');
+ });
+ });
+
+ describe('get', () => {
+ it('should retrieve an MCP server by ID', async () => {
+ mockClient.mcp.retrieve.mockResolvedValue(mockRetrieveResponse);
+
+ const result = await mcp.get('mcp_123');
+
+ expect(mockClient.mcp.retrieve).toHaveBeenCalledWith('mcp_123');
+ expect(result).toMatchObject({
+ id: 'mcp_123',
+ name: 'test-mcp-server',
+ toolkits: ['gmail', 'github'],
+ });
+ });
+
+ it('should handle retrieval errors', async () => {
+ mockClient.mcp.retrieve.mockRejectedValue(new Error('Not found'));
+
+ await expect(mcp.get('mcp_123')).rejects.toThrow('Failed to retrieve MCP server');
+ });
+ });
+
+ describe('delete', () => {
+ it('should delete an MCP server', async () => {
+ const mockDeleteResponse = {
+ id: 'mcp_123',
+ deleted: true,
+ message: 'Server deleted successfully',
+ };
+
+ mockClient.mcp.delete.mockResolvedValue(mockDeleteResponse);
+
+ const result = await mcp.delete('mcp_123');
+
+ expect(mockClient.mcp.delete).toHaveBeenCalledWith('mcp_123');
+ expect(result).toMatchObject({
+ id: 'mcp_123',
+ deleted: true,
+ });
+ });
+
+ it('should handle deletion errors', async () => {
+ mockClient.mcp.delete.mockRejectedValue(new Error('Cannot delete'));
+
+ await expect(mcp.delete('mcp_123')).rejects.toThrow('Failed to delete MCP server');
+ });
+ });
+
+ describe('update', () => {
+ const updatedConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_gmail789',
+ allowedTools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'GMAIL_CREATE_DRAFT'],
+ },
+ ];
+
+ it('should update an MCP server', async () => {
+ const mockUpdateResponse = {
+ id: 'mcp_123',
+ name: 'updated-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-02T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail'],
+ tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'GMAIL_CREATE_DRAFT'],
+ };
+
+ mockClient.mcp.update.mockResolvedValue(mockUpdateResponse);
+
+ const result = await mcp.update('mcp_123', 'updated-server', updatedConfigs, {
+ useComposioManagedAuth: true,
+ });
+
+ expect(mockClient.mcp.update).toHaveBeenCalledWith('mcp_123', {
+ name: 'updated-server',
+ toolkits: ['gmail'],
+ allowed_tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL', 'GMAIL_CREATE_DRAFT'],
+ managed_auth_via_composio: true,
+ });
+
+ expect(result).toMatchObject({
+ id: 'mcp_123',
+ name: 'updated-server',
+ });
+ });
+
+ it('should validate update parameters', async () => {
+ const invalidConfigs = [
+ {
+ toolkit: '',
+ authConfigId: 'ac_123',
+ allowedTools: [],
+ },
+ ];
+
+ await expect(mcp.update('mcp_123', 'updated', invalidConfigs)).rejects.toThrow(
+ ValidationError
+ );
+ });
+
+ it('should handle update errors', async () => {
+ mockClient.mcp.update.mockRejectedValue(new Error('Update failed'));
+
+ await expect(mcp.update('mcp_123', 'updated', updatedConfigs)).rejects.toThrow(
+ 'Failed to update MCP server'
+ );
+ });
+ });
+
+ describe('generateUrl', () => {
+ it('should generate URLs with valid parameters', async () => {
+ mockClient.mcp.generate.url.mockResolvedValue(mockGenerateUrlResponse);
+
+ const params = {
+ user_ids: ['user123'],
+ connected_account_ids: ['account456'],
+ mcp_server_id: 'mcp_123',
+ managed_auth_by_composio: true,
+ };
+
+ const result = await mcp.generateUrl(params);
+
+ expect(mockClient.mcp.generate.url).toHaveBeenCalledWith({
+ user_ids: ['user123'],
+ connected_account_ids: ['account456'],
+ mcp_server_id: 'mcp_123',
+ managed_auth_by_composio: true,
+ });
+
+ expect(result).toMatchObject({
+ connectedAccountUrls: [
+ 'https://mcp.example.com/account1',
+ 'https://mcp.example.com/account2',
+ ],
+ userIdsUrl: ['https://mcp.example.com/user1', 'https://mcp.example.com/user2'],
+ mcpUrl: 'https://mcp.example.com/server',
+ });
+ });
+
+ it('should validate parameters', async () => {
+ const invalidParams = {
+ user_ids: 'not-an-array' as unknown as string[], // Should be an array
+ mcp_server_id: 'mcp_123',
+ };
+
+ await expect(mcp.generateUrl(invalidParams)).rejects.toThrow(ValidationError);
+ });
+
+ it('should handle URL generation errors', async () => {
+ mockClient.mcp.generate.url.mockRejectedValue(new Error('Generation failed'));
+
+ await expect(
+ mcp.generateUrl({
+ mcp_server_id: 'mcp_123',
+ user_ids: ['user123'],
+ })
+ ).rejects.toThrow('Failed to generate MCP URL');
+ });
+ });
+
+ describe('convenience getServer method', () => {
+ it('should work on create response', async () => {
+ mockClient.mcp.custom.create.mockResolvedValue(mockCreateResponse);
+ mockClient.mcp.retrieve.mockResolvedValue(mockRetrieveResponse);
+ mockClient.mcp.generate.url.mockResolvedValue(mockGenerateUrlResponse);
+
+ const toolkitConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_gmail123',
+ allowedTools: ['GMAIL_FETCH_EMAILS'],
+ },
+ ];
+
+ const server = await mcp.create('test-server', toolkitConfigs);
+
+ // Mock the internal get call
+ vi.spyOn(mcp, 'get').mockResolvedValue({
+ id: mockRetrieveResponse.id,
+ name: mockRetrieveResponse.name,
+ createdAt: mockRetrieveResponse.created_at,
+ updatedAt: mockRetrieveResponse.updated_at,
+ status: mockRetrieveResponse.status,
+ toolkits: mockRetrieveResponse.toolkits,
+ tools: mockRetrieveResponse.tools,
+ managedAuthViaComposio: mockRetrieveResponse.managed_auth_via_composio,
+ });
+
+ const urls = await server.getServer({
+ connectedAccountIds: { gmail: 'account_123' },
+ });
+
+ expect(urls).toBeDefined();
+ expect(mockClient.mcp.generate.url).toHaveBeenCalled();
+ });
+ });
+
+ describe('validation error messages', () => {
+ it('should provide meaningful error messages for toolkit config validation', async () => {
+ const invalidConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: '', // Empty auth config ID
+ allowedTools: ['GMAIL_FETCH_EMAILS'],
+ },
+ ];
+
+ await expect(mcp.create('test-server', invalidConfigs)).rejects.toThrow(
+ 'Auth config ID cannot be empty'
+ );
+ });
+
+ it('should provide meaningful error messages for empty allowed tools', async () => {
+ const invalidConfigs = [
+ {
+ toolkit: 'gmail',
+ authConfigId: 'ac_123',
+ allowedTools: [], // Empty tools array
+ },
+ ];
+
+ await expect(mcp.create('test-server', invalidConfigs)).rejects.toThrow(
+ 'At least one tool must be specified'
+ );
+ });
+ });
+});
diff --git a/ts/packages/core/test/utils/toolExecuteUtils.ts b/ts/packages/core/test/utils/toolExecuteUtils.ts
index fda940194..3b4da0552 100644
--- a/ts/packages/core/test/utils/toolExecuteUtils.ts
+++ b/ts/packages/core/test/utils/toolExecuteUtils.ts
@@ -6,7 +6,7 @@ import { connectedAccountMocks, toolkitMocks, toolMocks } from './mocks/data.moc
import ComposioClient from '@composio/client';
import { Tool } from '../../src/types/tool.types';
-export type TestTools = Tools<unknown, unknown, MockProvider>;
+export type TestTools = Tools<unknown, unknown, unknown, MockProvider>;
export interface TestContext {
tools: TestTools;
diff --git a/ts/packages/core/test/utils/transformers/mcp.test.ts b/ts/packages/core/test/utils/transformers/mcp.test.ts
new file mode 100644
index 000000000..52e2b6215
--- /dev/null
+++ b/ts/packages/core/test/utils/transformers/mcp.test.ts
@@ -0,0 +1,392 @@
+import { describe, it, expect } from 'vitest';
+import {
+ transformMcpCreateResponse,
+ transformMcpListResponse,
+ transformMcpRetrieveResponse,
+ transformMcpDeleteResponse,
+ transformMcpUpdateResponse,
+ transformMcpGenerateUrlResponse,
+} from '../../../src/utils/transformers/mcp';
+import { ValidationError } from '../../../src/errors/ValidationErrors';
+
+describe('MCP Transformers', () => {
+ describe('transformMcpCreateResponse', () => {
+ it('should transform snake_case create response to camelCase', () => {
+ const snakeCaseResponse = {
+ id: 'mcp_123',
+ name: 'test-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-02T00:00:00Z',
+ status: 'active',
+ } as any;
+
+ const result = transformMcpCreateResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ createdAt: '2024-01-01T00:00:00Z',
+ updatedAt: '2024-01-02T00:00:00Z',
+ status: 'active',
+ });
+ });
+
+ it('should handle missing optional fields', () => {
+ const minimalResponse = {
+ id: 'mcp_123',
+ name: 'test-server',
+ } as any;
+
+ const result = transformMcpCreateResponse(minimalResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ });
+ });
+
+ it('should throw ValidationError for invalid response', () => {
+ const invalidResponse = {
+ id: '', // Empty ID should fail validation
+ name: 'test-server',
+ } as any;
+
+ expect(() => transformMcpCreateResponse(invalidResponse)).toThrow(ValidationError);
+ expect(() => transformMcpCreateResponse(invalidResponse)).toThrow(
+ 'Failed to parse MCP create response'
+ );
+ });
+ });
+
+ describe('transformMcpListResponse', () => {
+ it('should transform list response with items', () => {
+ const snakeCaseResponse = {
+ items: [
+ {
+ id: 'mcp_123',
+ name: 'server-1',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-01T00:00:00Z',
+ status: 'active',
+ },
+ {
+ id: 'mcp_456',
+ name: 'server-2',
+ created_at: '2024-01-02T00:00:00Z',
+ updated_at: '2024-01-02T00:00:00Z',
+ status: 'inactive',
+ },
+ ],
+ } as any;
+
+ const result = transformMcpListResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ items: [
+ {
+ id: 'mcp_123',
+ name: 'server-1',
+ createdAt: '2024-01-01T00:00:00Z',
+ updatedAt: '2024-01-01T00:00:00Z',
+ status: 'active',
+ },
+ {
+ id: 'mcp_456',
+ name: 'server-2',
+ createdAt: '2024-01-02T00:00:00Z',
+ updatedAt: '2024-01-02T00:00:00Z',
+ status: 'inactive',
+ },
+ ],
+ });
+ });
+
+ it('should handle empty items array', () => {
+ const emptyResponse = {
+ items: [],
+ } as any;
+
+ const result = transformMcpListResponse(emptyResponse);
+
+ expect(result).toEqual({
+ items: [],
+ });
+ });
+
+ it('should handle missing items', () => {
+ const noItemsResponse = {} as any;
+
+ const result = transformMcpListResponse(noItemsResponse);
+
+ expect(result).toEqual({
+ items: undefined,
+ });
+ });
+ });
+
+ describe('transformMcpRetrieveResponse', () => {
+ it('should transform retrieve response with all fields', () => {
+ const snakeCaseResponse = {
+ id: 'mcp_123',
+ name: 'test-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-02T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail', 'github'],
+ tools: ['GMAIL_FETCH_EMAILS', 'GITHUB_GET_REPO'],
+ managed_auth_via_composio: true,
+ } as any;
+
+ const result = transformMcpRetrieveResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ createdAt: '2024-01-01T00:00:00Z',
+ updatedAt: '2024-01-02T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail', 'github'],
+ tools: ['GMAIL_FETCH_EMAILS', 'GITHUB_GET_REPO'],
+ managedAuthViaComposio: true,
+ });
+ });
+
+ it('should handle minimal response', () => {
+ const minimalResponse = {
+ id: 'mcp_123',
+ name: 'test-server',
+ } as any;
+
+ const result = transformMcpRetrieveResponse(minimalResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ });
+ });
+
+ it('should throw ValidationError for missing required fields', () => {
+ const invalidResponse = {
+ id: 'mcp_123',
+ // Missing required 'name' field
+ } as any;
+
+ expect(() => transformMcpRetrieveResponse(invalidResponse)).toThrow(ValidationError);
+ });
+ });
+
+ describe('transformMcpDeleteResponse', () => {
+ it('should transform delete response', () => {
+ const snakeCaseResponse = {
+ id: 'mcp_123',
+ deleted: true,
+ message: 'Server deleted successfully',
+ } as any;
+
+ const result = transformMcpDeleteResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ deleted: true,
+ message: 'Server deleted successfully',
+ });
+ });
+
+ it('should handle response without optional fields', () => {
+ const minimalResponse = {
+ id: 'mcp_123',
+ } as any;
+
+ const result = transformMcpDeleteResponse(minimalResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ });
+ });
+ });
+
+ describe('transformMcpUpdateResponse', () => {
+ it('should transform update response with all fields', () => {
+ const snakeCaseResponse = {
+ id: 'mcp_123',
+ name: 'updated-server',
+ created_at: '2024-01-01T00:00:00Z',
+ updated_at: '2024-01-03T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail', 'slack'],
+ tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE'],
+ } as any;
+
+ const result = transformMcpUpdateResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'updated-server',
+ createdAt: '2024-01-01T00:00:00Z',
+ updatedAt: '2024-01-03T00:00:00Z',
+ status: 'active',
+ toolkits: ['gmail', 'slack'],
+ tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE'],
+ });
+ });
+
+ it('should handle minimal update response', () => {
+ const minimalResponse = {
+ id: 'mcp_123',
+ name: 'updated-server',
+ } as any;
+
+ const result = transformMcpUpdateResponse(minimalResponse);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'updated-server',
+ });
+ });
+
+ it('should throw ValidationError for invalid response', () => {
+ const invalidResponse = {
+ id: 'mcp_123',
+ name: '', // Empty name should fail validation
+ } as any;
+
+ expect(() => transformMcpUpdateResponse(invalidResponse)).toThrow(ValidationError);
+ expect(() => transformMcpUpdateResponse(invalidResponse)).toThrow(
+ 'Failed to parse MCP update response'
+ );
+ });
+ });
+
+ describe('transformMcpGenerateUrlResponse', () => {
+ it('should transform URL response with all fields', () => {
+ const snakeCaseResponse = {
+ connected_account_urls: [
+ 'https://mcp.example.com/account1',
+ 'https://mcp.example.com/account2',
+ ],
+ user_ids_url: ['https://mcp.example.com/user1', 'https://mcp.example.com/user2'],
+ mcp_url: 'https://mcp.example.com/server',
+ };
+
+ const result = transformMcpGenerateUrlResponse(snakeCaseResponse);
+
+ expect(result).toEqual({
+ connectedAccountUrls: [
+ 'https://mcp.example.com/account1',
+ 'https://mcp.example.com/account2',
+ ],
+ userIdsUrl: ['https://mcp.example.com/user1', 'https://mcp.example.com/user2'],
+ mcpUrl: 'https://mcp.example.com/server',
+ });
+ });
+
+ it('should handle response with only mcp_url', () => {
+ const minimalResponse = {
+ mcp_url: 'https://mcp.example.com/server',
+ };
+
+ const result = transformMcpGenerateUrlResponse(minimalResponse);
+
+ expect(result).toEqual({
+ mcpUrl: 'https://mcp.example.com/server',
+ });
+ });
+
+ it('should handle response with some optional arrays', () => {
+ const partialResponse = {
+ connected_account_urls: ['https://mcp.example.com/account1'],
+ mcp_url: 'https://mcp.example.com/server',
+ };
+
+ const result = transformMcpGenerateUrlResponse(partialResponse);
+
+ expect(result).toEqual({
+ connectedAccountUrls: ['https://mcp.example.com/account1'],
+ mcpUrl: 'https://mcp.example.com/server',
+ });
+ });
+
+ it('should throw ValidationError for missing required mcp_url', () => {
+ const invalidResponse = {
+ connected_account_urls: ['https://mcp.example.com/account1'],
+ // Missing required mcp_url
+ };
+
+ expect(() => transformMcpGenerateUrlResponse(invalidResponse)).toThrow(ValidationError);
+ expect(() => transformMcpGenerateUrlResponse(invalidResponse)).toThrow(
+ 'Failed to parse MCP generate URL response'
+ );
+ });
+
+ it('should throw ValidationError for empty mcp_url', () => {
+ const invalidResponse = {
+ mcp_url: '', // Empty URL should fail validation
+ };
+
+ expect(() => transformMcpGenerateUrlResponse(invalidResponse)).toThrow(ValidationError);
+ expect(() => transformMcpGenerateUrlResponse(invalidResponse)).toThrow(
+ 'MCP URL cannot be empty'
+ );
+ });
+ });
+
+ describe('Edge cases', () => {
+ it('should handle null values gracefully', () => {
+ const responseWithNulls = {
+ id: 'mcp_123',
+ name: 'test-server',
+ created_at: null,
+ updated_at: null,
+ status: null,
+ } as any;
+
+ const result = transformMcpCreateResponse(responseWithNulls);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ createdAt: null,
+ updatedAt: null,
+ status: null,
+ });
+ });
+
+ it('should handle undefined values gracefully', () => {
+ const responseWithUndefined = {
+ id: 'mcp_123',
+ name: 'test-server',
+ created_at: undefined,
+ updated_at: undefined,
+ status: undefined,
+ } as any;
+
+ const result = transformMcpCreateResponse(responseWithUndefined);
+
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ });
+ });
+
+ it('should preserve additional unknown fields in responses', () => {
+ const responseWithExtraFields = {
+ id: 'mcp_123',
+ name: 'test-server',
+ created_at: '2024-01-01T00:00:00Z',
+ some_unknown_field: 'value',
+ nested_object: { key: 'value' },
+ } as any;
+
+ const result = transformMcpCreateResponse(responseWithExtraFields);
+
+ // Should only include known fields
+ expect(result).toEqual({
+ id: 'mcp_123',
+ name: 'test-server',
+ createdAt: '2024-01-01T00:00:00Z',
+ });
+ expect(result).not.toHaveProperty('some_unknown_field');
+ expect(result).not.toHaveProperty('nested_object');
+ });
+ });
+});
diff --git a/ts/packages/providers/anthropic/src/index.ts b/ts/packages/providers/anthropic/src/index.ts
index 3aa0ed3cb..6ca269fcb 100644
--- a/ts/packages/providers/anthropic/src/index.ts
+++ b/ts/packages/providers/anthropic/src/index.ts
@@ -14,6 +14,8 @@ import {
ExecuteToolFnOptions,
ToolExecuteParams,
logger,
+ McpUrlResponse,
+ McpServerGetResponse,
} from '@composio/core';
import Anthropic from '@anthropic-ai/sdk';
import { AnthropicTool, InputSchema } from './types';
@@ -289,4 +291,43 @@ export class AnthropicProvider extends BaseNonAgenticProvider<
return outputs;
}
+
+ /**
+ * Transform MCP URL response into Anthropic-specific format.
+ * By default, Anthropic uses the standard format (same as default),
+ * but this method is here to show providers can customize if needed.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // Anthropic uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
}
diff --git a/ts/packages/providers/cloudflare/src/index.ts b/ts/packages/providers/cloudflare/src/index.ts
index 5d8095460..f73592c4b 100644
--- a/ts/packages/providers/cloudflare/src/index.ts
+++ b/ts/packages/providers/cloudflare/src/index.ts
@@ -16,6 +16,8 @@ import {
BaseNonAgenticProvider,
ToolExecuteParams,
ExecuteToolFnOptions,
+ McpUrlResponse,
+ McpServerGetResponse,
} from '@composio/core';
type AiToolCollection = Record<string, AiTextGenerationToolInput>;
@@ -49,6 +51,44 @@ export class CloudflareProvider extends BaseNonAgenticProvider<
super();
}
+ /**
+ * Transform MCP URL response into Cloudflare-specific format.
+ * Cloudflare uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // Cloudflare uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in the Cloudflare AI format.
*
diff --git a/ts/packages/providers/google/src/index.ts b/ts/packages/providers/google/src/index.ts
index 94c87cce2..3888a3015 100644
--- a/ts/packages/providers/google/src/index.ts
+++ b/ts/packages/providers/google/src/index.ts
@@ -13,6 +13,8 @@ import {
ToolExecuteParams,
ExecuteToolModifiers,
ExecuteToolFnOptions,
+ McpUrlResponse,
+ McpServerGetResponse,
} from '@composio/core';
import { FunctionDeclaration, Schema } from '@google/genai';
@@ -45,21 +47,21 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
/**
* Creates a new instance of the GoogleProvider.
- *
+ *
* This provider enables integration with Google's GenAI API,
* supporting both the Gemini Developer API and Vertex AI implementations.
- *
+ *
* @example
* ```typescript
* // Initialize the Google provider
* const provider = new GoogleProvider();
- *
+ *
* // Use with Composio
* const composio = new Composio({
* apiKey: 'your-api-key',
* provider: new GoogleProvider()
* });
- *
+ *
* // Use the provider to wrap tools for Google GenAI
* const googleTools = provider.wrapTools(composioTools);
* ```
@@ -68,15 +70,53 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
super();
}
+ /**
+ * Transform MCP URL response into Google-specific format.
+ * Google uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // Google uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in the Google GenAI function declaration format.
- *
+ *
* This method transforms a Composio tool definition into the format
* expected by Google's GenAI API for function calling.
- *
+ *
* @param tool - The Composio tool to wrap
* @returns The wrapped tool in Google GenAI format
- *
+ *
* @example
* ```typescript
* // Wrap a single tool for use with Google GenAI
@@ -91,12 +131,12 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
* required: ['query']
* }
* };
- *
+ *
* const googleTool = provider.wrapTool(composioTool);
* // Use with Google GenAI SDK
* const genAI = new GoogleGenerativeAI('YOUR_API_KEY');
* const model = genAI.getGenerativeModel({ model: 'gemini-pro' });
- *
+ *
* const result = await model.generateContent({
* contents: [{ role: 'user', parts: [{ text: 'Search for Composio' }] }],
* tools: [googleTool]
@@ -118,13 +158,13 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
/**
* Wraps a list of Composio tools in the Google GenAI function declaration format.
- *
+ *
* This method transforms multiple Composio tool definitions into the format
* expected by Google's GenAI API for function calling.
- *
+ *
* @param tools - Array of Composio tools to wrap
* @returns Array of wrapped tools in Google GenAI format
- *
+ *
* @example
* ```typescript
* // Wrap multiple tools for use with Google GenAI
@@ -152,13 +192,13 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
* }
* }
* ];
- *
+ *
* const googleTools = provider.wrapTools(composioTools);
- *
+ *
* // Use with Google GenAI SDK
* const genAI = new GoogleGenerativeAI('YOUR_API_KEY');
* const model = genAI.getGenerativeModel({ model: 'gemini-pro' });
- *
+ *
* const result = await model.generateContent({
* contents: [{ role: 'user', parts: [{ text: 'How is the weather in New York?' }] }],
* tools: googleTools
@@ -171,16 +211,16 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
/**
* Executes a tool call from Google GenAI.
- *
+ *
* This method processes a function call from Google's GenAI API,
* executes the corresponding Composio tool, and returns the result.
- *
+ *
* @param userId - The user ID for authentication and tracking
* @param tool - The Google GenAI function call to execute
* @param options - Optional execution options like connected account ID
* @param modifiers - Optional execution modifiers for tool behavior
* @returns The result of the tool execution as a JSON string
- *
+ *
* @example
* ```typescript
* // Execute a tool call from Google GenAI
@@ -190,21 +230,21 @@ export class GoogleProvider extends BaseNonAgenticProvider<GoogleGenAIToolCollec
* query: 'composio documentation'
* }
* };
- *
+ *
* const result = await provider.executeToolCall(
* 'user123',
* functionCall,
* { connectedAccountId: 'conn_xyz456' }
* );
- *
+ *
* // Parse the result and use it in your application
* const searchResults = JSON.parse(result);
* console.log(searchResults);
- *
+ *
* // You can also use the result to continue the conversation
* const genAI = new GoogleGenerativeAI('YOUR_API_KEY');
* const model = genAI.getGenerativeModel({ model: 'gemini-pro' });
- *
+ *
* await model.generateContent({
* contents: [
* { role: 'user', parts: [{ text: 'Search for Composio' }] },
diff --git a/ts/packages/providers/langchain/src/index.ts b/ts/packages/providers/langchain/src/index.ts
index 550dff45c..d6f90131f 100644
--- a/ts/packages/providers/langchain/src/index.ts
+++ b/ts/packages/providers/langchain/src/index.ts
@@ -9,7 +9,14 @@
* @packageDocumentation
* @module providers/langchain
*/
-import { BaseAgenticProvider, jsonSchemaToZodSchema, Tool, ExecuteToolFn } from '@composio/core';
+import {
+ BaseAgenticProvider,
+ jsonSchemaToZodSchema,
+ Tool,
+ ExecuteToolFn,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
import { DynamicStructuredTool } from '@langchain/core/tools';
export type LangChainToolCollection = Array<DynamicStructuredTool>;
@@ -21,21 +28,21 @@ export class LangchainProvider extends BaseAgenticProvider<
/**
* Creates a new instance of the LangchainProvider.
- *
+ *
* This provider enables integration with the Langchain framework,
* allowing Composio tools to be used with Langchain agents and chains.
- *
+ *
* @example
* ```typescript
* // Initialize the Langchain provider
* const provider = new LangchainProvider();
- *
+ *
* // Use with Composio
* const composio = new Composio({
* apiKey: 'your-api-key',
* provider: new LangchainProvider()
* });
- *
+ *
* // Use the provider to wrap tools for Langchain
* const langchainTools = provider.wrapTools(composioTools, composio.tools.execute);
* ```
@@ -44,16 +51,54 @@ export class LangchainProvider extends BaseAgenticProvider<
super();
}
+ /**
+ * Transform MCP URL response into LangChain-specific format.
+ * LangChain uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // LangChain uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in the Langchain DynamicStructuredTool format.
- *
+ *
* This method transforms a Composio tool definition into a Langchain
* DynamicStructuredTool that can be used with Langchain agents and chains.
- *
+ *
* @param tool - The Composio tool to wrap
* @param executeTool - Function to execute the tool
* @returns The wrapped tool as a Langchain DynamicStructuredTool
- *
+ *
* @example
* ```typescript
* // Wrap a single tool for use with Langchain
@@ -69,28 +114,28 @@ export class LangchainProvider extends BaseAgenticProvider<
* required: ['query']
* }
* };
- *
+ *
* // Create a Langchain tool using the provider
* const langchainTool = provider.wrapTool(
* composioTool,
* composio.tools.execute
* );
- *
+ *
* // Use with Langchain
* import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
* import { ChatOpenAI } from '@langchain/openai';
- *
+ *
* const model = new ChatOpenAI({ temperature: 0 });
* const agent = await createOpenAIFunctionsAgent({
* llm: model,
* tools: [langchainTool]
* });
- *
+ *
* const executor = new AgentExecutor({
* agent,
* tools: [langchainTool]
* });
- *
+ *
* const result = await executor.invoke({
* input: "Search for information about Composio"
* });
@@ -121,14 +166,14 @@ export class LangchainProvider extends BaseAgenticProvider<
/**
* Wraps a list of Composio tools in the Langchain DynamicStructuredTool format.
- *
+ *
* This method transforms multiple Composio tool definitions into Langchain
* DynamicStructuredTools that can be used with Langchain agents and chains.
- *
+ *
* @param tools - Array of Composio tools to wrap
* @param executeTool - Function to execute the tools
* @returns Array of wrapped tools as Langchain DynamicStructuredTools
- *
+ *
* @example
* ```typescript
* // Wrap multiple tools for use with Langchain
@@ -158,23 +203,23 @@ export class LangchainProvider extends BaseAgenticProvider<
* }
* }
* ];
- *
+ *
* // Create Langchain tools using the provider
* const langchainTools = provider.wrapTools(
* composioTools,
* composio.tools.execute
* );
- *
+ *
* // Use with Langchain
* import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
* import { ChatOpenAI } from '@langchain/openai';
- *
+ *
* const model = new ChatOpenAI({ temperature: 0 });
* const agent = await createOpenAIFunctionsAgent({
* llm: model,
* tools: langchainTools
* });
- *
+ *
* const executor = new AgentExecutor({
* agent,
* tools: langchainTools
diff --git a/ts/packages/providers/mastra/src/index.ts b/ts/packages/providers/mastra/src/index.ts
index 162a46821..58e6fa7fb 100644
--- a/ts/packages/providers/mastra/src/index.ts
+++ b/ts/packages/providers/mastra/src/index.ts
@@ -6,7 +6,13 @@
* @packageDocumentation
* @module providers/mastra
*/
-import { BaseAgenticProvider, Tool, ExecuteToolFn, jsonSchemaToZodSchema } from '@composio/core';
+import {
+ BaseAgenticProvider,
+ Tool,
+ ExecuteToolFn,
+ jsonSchemaToZodSchema,
+ McpUrlResponse,
+} from '@composio/core';
import { createTool } from '@mastra/core';
export type MastraTool = ReturnType<typeof createTool>;
@@ -15,9 +21,62 @@ export interface MastraToolCollection {
[key: string]: MastraTool;
}
-export class MastraProvider extends BaseAgenticProvider<MastraToolCollection, MastraTool> {
+export interface MastraUrlMap {
+ [name: string]: { url: string };
+}
+
+export class MastraProvider extends BaseAgenticProvider<
+ MastraToolCollection,
+ MastraTool,
+ MastraUrlMap
+> {
readonly name = 'mastra';
+ constructor() {
+ super();
+ }
+
+ /**
+ * Transform MCP URL response into Mastra-specific format.
+ * Mastra expects URLs in a key-value map format.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @returns Transformed MastraUrlMap
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[]
+ ): MastraUrlMap {
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.reduce(
+ (prev: MastraUrlMap, url: string, index: number) => {
+ prev[`${serverName}-${index}`] = {
+ url: url,
+ };
+ return prev;
+ },
+ {}
+ );
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.reduce((prev: MastraUrlMap, url: string, index: number) => {
+ prev[`${serverName}-${index}`] = {
+ url: url,
+ };
+ return prev;
+ }, {});
+ }
+ return {
+ [serverName]: {
+ url: data.mcp_url,
+ },
+ };
+ }
+
wrapTool(tool: Tool, executeTool: ExecuteToolFn): MastraTool {
const mastraTool = createTool({
id: tool.slug,
diff --git a/ts/packages/providers/openai-agents/src/index.ts b/ts/packages/providers/openai-agents/src/index.ts
index 822f24e6e..d2aff2ba5 100644
--- a/ts/packages/providers/openai-agents/src/index.ts
+++ b/ts/packages/providers/openai-agents/src/index.ts
@@ -5,7 +5,7 @@
* Author: Musthaq Ahamad <[email protected]>
* Reference: https://openai.github.io/openai-agents-js/
*
- * This provider provides a set of tools for interacting with Vercel AI SDK.
+ * This provider provides a set of tools for interacting with OpenAI's Agents API.
*
* @packageDocumentation
* @module providers/openai-agents
@@ -15,6 +15,8 @@ import {
Tool as ComposioTool,
ExecuteToolFn,
jsonSchemaToZodSchema,
+ McpUrlResponse,
+ McpServerGetResponse,
} from '@composio/core';
import type { Tool as OpenAIAgentTool } from '@openai/agents';
import { tool as createOpenAIAgentTool } from '@openai/agents';
@@ -45,7 +47,7 @@ export class OpenAIAgentsProvider extends BaseAgenticProvider<
* });
*
* // Use the provider to wrap tools for @openai/agents
- * const vercelTools = provider.wrapTools(composioTools, composio.tools.execute);
+ * const agentTools = provider.wrapTools(composioTools, composio.tools.execute);
* ```
*/
constructor(options?: { strict?: boolean }) {
@@ -53,6 +55,44 @@ export class OpenAIAgentsProvider extends BaseAgenticProvider<
this.strict = options?.strict ?? false;
}
+ /**
+ * Transform MCP URL response into OpenAI Agents-specific format.
+ * OpenAI Agents uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // OpenAI Agents uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in a OpenAI Agents tool format.
*
diff --git a/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts b/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
index 2f1092c5b..4f28c29f6 100644
--- a/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
+++ b/ts/packages/providers/openai/src/OpenAIResponsesProvider.ts
@@ -1,20 +1,33 @@
/**
- * OpenAI ToolSet
+ * OpenAI Toolset
*
* Author: Musthaq Ahamad <[email protected]>
* Legacy Reference: https://github.com/ComposioHQ/composio/blob/master/js/src/toolsets/openai.ts
+ *
+ * This provider provides a set of tools for interacting with OpenAI's ChatCompletions API.
+ *
+ * @packageDocumentation
+ * @module providers/openai
*/
import { OpenAI } from 'openai';
-import { BaseNonAgenticProvider, removeNonRequiredProperties } from '@composio/core';
-import { Tool, ToolExecuteParams } from '@composio/core';
-import { ExecuteToolModifiers } from '@composio/core';
-import { ExecuteToolFnOptions } from '@composio/core';
+import {
+ BaseNonAgenticProvider,
+ Tool,
+ ToolExecuteParams,
+ ExecuteToolModifiers,
+ ExecuteToolFnOptions,
+ removeNonRequiredProperties,
+ logger,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
export type OpenAiTool = OpenAI.Responses.FunctionTool;
export type OpenAiToolCollection = Array<OpenAiTool>;
export type OpenAIResponsesProviderOptions = {
/**
- * Whether to enforce strict parameter validation. Default `false`.
+ * Whether to use strict mode for function calls
+ * @default false
*/
strict?: boolean;
};
@@ -55,6 +68,44 @@ export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
this.strict = options?.strict ?? false;
}
+ /**
+ * Transform MCP URL response into OpenAI Responses-specific format.
+ * OpenAI Responses uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // OpenAI Responses uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
+
/**
* Wraps a Composio tool in the OpenAI function calling format.
*
diff --git a/ts/packages/providers/vercel/src/index.ts b/ts/packages/providers/vercel/src/index.ts
index f3eb6f1b6..7f468c33c 100644
--- a/ts/packages/providers/vercel/src/index.ts
+++ b/ts/packages/providers/vercel/src/index.ts
@@ -10,11 +10,19 @@
* @packageDocumentation
* @module providers/vercel
*/
-import { BaseAgenticProvider, Tool as ComposioTool, ExecuteToolFn } from '@composio/core';
+import {
+ BaseAgenticProvider,
+ Tool,
+ ExecuteToolFn,
+ jsonSchemaToZodSchema,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
import type { Tool as VercelTool } from 'ai';
import { jsonSchema, tool } from 'ai';
+import { z } from 'zod';
-type VercelToolCollection = Record<string, VercelTool>;
+export type VercelToolCollection = Record<string, VercelTool>;
export class VercelProvider extends BaseAgenticProvider<VercelToolCollection, VercelTool> {
readonly name = 'vercel';
@@ -92,7 +100,7 @@ export class VercelProvider extends BaseAgenticProvider<VercelToolCollection, Ve
* }
* ```
*/
- wrapTool(composioTool: ComposioTool, executeTool: ExecuteToolFn): VercelTool {
+ wrapTool(composioTool: Tool, executeTool: ExecuteToolFn): VercelTool {
return tool({
description: composioTool.description,
parameters: jsonSchema((composioTool.inputParameters as Record<string, unknown>) ?? {}),
@@ -166,10 +174,48 @@ export class VercelProvider extends BaseAgenticProvider<VercelToolCollection, Ve
* }
* ```
*/
- wrapTools(tools: ComposioTool[], executeTool: ExecuteToolFn): VercelToolCollection {
+ wrapTools(tools: Tool[], executeTool: ExecuteToolFn): VercelToolCollection {
return tools.reduce((acc, tool) => {
acc[tool.slug] = this.wrapTool(tool, executeTool);
return acc;
}, {} as VercelToolCollection);
}
+
+ /**
+ * Transform MCP URL response into Vercel-specific format.
+ * Vercel uses the standard format by default.
+ *
+ * @param data - The MCP URL response data
+ * @param serverName - Name of the MCP server
+ * @param connectedAccountIds - Optional array of connected account IDs
+ * @param userIds - Optional array of user IDs
+ * @param toolkits - Optional array of toolkit names
+ * @returns Standard MCP server response format
+ */
+ wrapMcpServerResponse(
+ data: McpUrlResponse,
+ serverName: string,
+ connectedAccountIds?: string[],
+ userIds?: string[],
+ toolkits?: string[]
+ ): McpServerGetResponse {
+ // Vercel uses the standard format
+ if (connectedAccountIds?.length && data.connected_account_urls) {
+ return data.connected_account_urls.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${connectedAccountIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ } else if (userIds?.length && data.user_ids_url) {
+ return data.user_ids_url.map((url: string, index: number) => ({
+ url: new URL(url),
+ name: `${serverName}-${userIds[index]}`,
+ toolkit: toolkits?.[index],
+ })) as McpServerGetResponse;
+ }
+ return {
+ url: new URL(data.mcp_url),
+ name: serverName,
+ } as McpServerGetResponse;
+ }
}