Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 19:30 UTC
server management python
Sushmithamallesh committed
Oct 12, 2025 at 20:23 UTC
720d364f135597deed61b2ad3d25089943173d14
6 files changed
+20
-1070
fern/docs.yml
-9
@@ -174,15 +174,6 @@ navigation:
174
- page: Partner Program
175
path: pages/dist/mcp/partner-api.mdx
176
slug: mcp-partner-api
177
- - page: Developers (old)
178
- path: pages/dist/mcp/developers.mdx
179
- slug: mcp-developers-old
180
- - page: Introduction (old)
181
- path: pages/dist/mcp/introduction.mdx
182
- slug: mcp-introduction-old
183
- - page: Implementation (old)
184
- path: pages/dist/mcp/implementation.mdx
185
- slug: mcp-implementation-old
177
- section: Tool Router (Beta)
178
icon: tools
179
skip-slug: true
fern/pages/src/mcp/authentication.mdx
deleted
-169
@@ -1,169 +0,0 @@
1
----
2
-title: MCP authentication
3
-subtitle: Managing user authentication for MCP servers
4
----
5
-
6
-Before users can access tools through your MCP server, they need to authenticate with the external services.
7
-
8
-## Check connection status
9
-
10
-Verify if a user has the required connections before generating server URLs.
11
-
12
-<CodeGroup>
13
-<CodeGroupItem title="Python">
14
-```python
15
-# Python SDK - connection checking coming soon
16
-# For now, the generate method handles auth automatically
17
-instance = server.generate("user@example.com")
18
-```
19
-</CodeGroupItem>
20
-<CodeGroupItem title="TypeScript">
21
-```typescript
22
-const status = await composio.mcp.getUserConnectionStatus(
23
- "user@example.com",
24
- server.id
25
-);
26
-
27
-if (status.connected) {
28
- console.log("✅ All toolkits connected");
29
-} else {
30
- console.log("❌ Missing connections:");
31
-
32
- for (const [toolkit, toolkitStatus] of Object.entries(status.connectedToolkits)) {
33
- if (!toolkitStatus.connected) {
34
- console.log(`- ${toolkit}: Not connected`);
35
- }
36
- }
37
-}
38
-```
39
-</CodeGroupItem>
40
-</CodeGroup>
41
-
42
-## Authentication flows
43
-
44
-### Pre-authentication (Recommended)
45
-
46
-Authenticate users before they use the MCP server for a smoother experience.
47
-
48
-<CodeGroup>
49
-<CodeGroupItem title="TypeScript">
50
-```typescript
51
-// 1. Check what's needed
52
-const authParams = await composio.mcp.getConnectionParams(
53
- server.id,
54
- "gmail"
55
-);
56
-
57
-console.log("Required fields:", authParams.required_fields);
58
-
59
-// 2. Start authentication
60
-const authRequest = await composio.mcp.authorize(
61
- "user@example.com",
62
- server.id,
63
- "gmail"
64
-);
65
-
66
-if (authRequest.redirectUrl) {
67
- // 3. Send user to authenticate
68
- console.log("Authenticate here:", authRequest.redirectUrl);
69
-
70
- // 4. After completion, verify
71
- const status = await composio.mcp.getUserConnectionStatus(
72
- "user@example.com",
73
- server.id
74
- );
75
-
76
- if (status.connected) {
77
- console.log("✅ Ready to generate URLs");
78
- }
79
-}
80
-```
81
-</CodeGroupItem>
82
-</CodeGroup>
83
-
84
-### Chat-based authentication
85
-
86
-Let the AI agent guide users through authentication when needed.
87
-
88
-```typescript
89
-// Enable chat auth when creating the server
90
-const server = await composio.mcp.create(
91
- "assistant-server",
92
- [{ authConfigId: "ac_xyz", allowedTools: ["GMAIL_FETCH_EMAILS"] }],
93
- { isChatAuth: true } // Agent handles auth prompts
94
-);
95
-
96
-// Generate URLs directly - agent will handle missing auth
97
-const urls = await composio.mcp.getServer(
98
- server.id,
99
- "user@example.com"
100
-);
101
-```
102
-
103
-## Auth config setup
104
-
105
-Auth configs define how users authenticate with external services. Create them in the [Composio dashboard](https://platform.composio.dev).
106
-
107
-### Types of auth
108
-
109
-- **OAuth** - Redirect-based flow (Gmail, Slack, GitHub)
110
-- **API Key** - Direct credential entry (OpenAI, Anthropic)
111
-- **Basic Auth** - Username/password
112
-
113
-### Creating auth configs
114
-
115
-1. Go to [Composio dashboard](https://platform.composio.dev)
116
-2. Navigate to Settings → Authentication
117
-3. Click "Create Auth Config"
118
-4. Select toolkit and auth type
119
-5. Configure scopes and permissions
120
-6. Save and copy the `authConfigId`
121
-
122
-## Handle authentication errors
123
-
124
-<CodeGroup>
125
-<CodeGroupItem title="Python">
126
-```python
127
-try:
128
- instance = server.generate("user@example.com")
129
-except Exception as e:
130
- if "authentication" in str(e).lower():
131
- print("User needs to authenticate first")
132
- # Guide user to auth flow
133
-```
134
-</CodeGroupItem>
135
-<CodeGroupItem title="TypeScript">
136
-```typescript
137
-try {
138
- const urls = await composio.mcp.getServer(
139
- server.id,
140
- "user@example.com"
141
- );
142
-} catch (error) {
143
- if (error.message.includes("not connected")) {
144
- // Handle missing authentication
145
- const auth = await composio.mcp.authorize(
146
- "user@example.com",
147
- server.id,
148
- "gmail"
149
- );
150
- console.log(`Please authenticate: ${auth.redirectUrl}`);
151
- }
152
-}
153
-```
154
-</CodeGroupItem>
155
-</CodeGroup>
156
-
157
-## Next steps
158
-
159
-<Cards>
160
- <Card title="Server management" href="/docs/mcp-server-management" icon="server">
161
- Create and manage MCP servers
162
- </Card>
163
- <Card title="Quickstart" href="/docs/mcp-quickstart" icon="rocket">
164
- Get started quickly
165
- </Card>
166
- <Card title="Troubleshooting" href="/docs/troubleshooting/mcp" icon="wrench">
167
- Common auth issues
168
- </Card>
169
-</Cards>
\ No newline at end of file
fern/pages/src/mcp/developers.mdx
deleted
-223
@@ -1,223 +0,0 @@
1
----
2
-title: MCP Servers for developers
3
-subtitle: "Guide to create and manage MCP servers"
4
-image: "https://og.composio.dev/api/og?title=MCP%20Servers%20for%20developers" # image for socials
5
-keywords: ""
6
-hide-nav-links: true
7
----
8
-
9
-<iframe width="100%" height="420" style="border-radius: 12px" src="https://www.youtube.com/embed/kp9CQboTUvs?si=ZgXTlIAe_RCtNk6z" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
10
-
11
-Composio MCP lets you build custom MCP servers that your users can connect to and use to perform actions.
12
-You can manage these servers via our [Dashboard](https://platform.composio.dev), or use the [SDK/API](/api-reference/mcp) for greater control and flexibility.
13
-
14
-<Note>
15
-The MCP SDK has been updated to use positional parameters instead of object parameters for better performance and simpler usage. All examples below reflect the latest API structure.
16
-</Note>
17
-
18
-## Creating MCP Servers and Onboarding End Users
19
-<Steps>
20
- <Step title="Configure Authentication">
21
- - **Create and Configure Toolkit permissions:**
22
- - Select the specific scopes and permissions your integration requires for each connected application. This ensures your MCP server has the right level of access.
23
- - Check this guide on what auth config is and how to configue it - [Auth Config setup guide](/docs/custom-auth-configs)
24
-
25
- - **Customize the authentication experience (Optional):**
26
- - Create a seamless, branded experience by providing your own OAuth credentials and customizing the consent screens.
27
- - Learn more here - [Custom auth configs](/docs/custom-auth-configs)
28
- </Step>
29
- <Step title="Create and configure an MCP server">
30
-
31
- ```typescript
32
- import { Composio } from '@composio/core';
33
-
34
- const composio = new Composio({
35
- apiKey: process.env.COMPOSIO_API_KEY,
36
- });
37
-
38
- // Create an MCP server with the new API structure
39
- const mcpConfig = await composio.mcp.create(
40
- "Gmail MCP Server",
41
- [
42
- {
43
- authConfigId: "ac_auth_12", // Your auth config ID
44
- allowedTools: [
45
- "GMAIL_FETCH_EMAILS",
46
- "GMAIL_CREATE_EMAIL_DRAFT",
47
- "GMAIL_SEND_EMAIL"
48
- ]
49
- }
50
- ],
51
- {
52
- isChatAuth: true // Enable chat-based authentication
53
- }
54
- );
55
-
56
- console.log(`✅ MCP server created: ${mcpConfig.id}`);
57
- console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
58
- ```
59
- </Step>
60
- <Step title="Generate server URLs for users">
61
- **Using the SDK:**
62
- ```typescript
63
- // Get server URLs for a specific user
64
- const serverUrls = await composio.mcp.getServer(
65
- mcpConfig.id,
66
- "user123@example.com"
67
- );
68
-
69
- console.log("Server URLs:", serverUrls);
70
- ```
71
-
72
- **Using the server ID (from create response):**
73
- ```typescript
74
- // Get server URLs using the created server ID
75
- const serverUrls = await composio.mcp.getServer(
76
- mcpConfig.id,
77
- "user123@example.com"
78
- );
79
- ```
80
- </Step>
81
- <Step title="Client applications connect to the server">
82
- The generated server URLs can be used directly by MCP clients. The URLs automatically handle user authentication and tool access based on your server configuration.
83
-
84
- **Example server URL structure:**
85
- ```
86
- https://mcp.composio.dev/composio/server/<UUID>/mcp?user_id=user123@example.com
87
- ```
88
-
89
- **Optional query parameters:**
90
- | Query param | Purpose |
91
- |-------------|---------|
92
- | `user_id` | Bind the session to a user identifier from your app |
93
- | `connected_account_id` | Pin the session to a specific Composio connected account |
94
- | `include_composio_helper_actions=true` | Include helper tools for agent-guided authentication |
95
- </Step>
96
-</Steps>
97
-
98
-## Managing MCP Servers
99
-
100
-### Check User Connection Status
101
-
102
-Before using an MCP server, you can check if a user has the necessary connected accounts:
103
-
104
-```typescript
105
-// Check if a user has connected accounts for all required toolkits
106
-const connectionStatus = await composio.mcp.getUserConnectionStatus(
107
- "user123@example.com",
108
- mcpConfig.id
109
-);
110
-
111
-console.log("Overall connection status:", connectionStatus.connected);
112
-console.log("Individual toolkit status:", connectionStatus.connectedToolkits);
113
-
114
-// Handle missing connections
115
-if (!connectionStatus.connected) {
116
- Object.entries(connectionStatus.connectedToolkits).forEach(([toolkit, status]) => {
117
- if (!status.connected) {
118
- console.log(`❌ ${toolkit} not connected`);
119
- // Guide user through authentication
120
- }
121
- });
122
-}
123
-```
124
-
125
-### Find Servers by Name
126
-
127
-```typescript
128
-// Retrieve a server by its name
129
-const serverDetails = await composio.mcp.getByName("Gmail MCP Server");
130
-console.log("Server details:", serverDetails);
131
-```
132
-
133
-### List All Servers
134
-
135
-```typescript
136
-// List servers with filtering options
137
-const servers = await composio.mcp.list({
138
- page: 1,
139
- limit: 10,
140
- toolkits: ["gmail", "slack"], // Filter by toolkits
141
- name: "production" // Filter by name
142
-});
143
-
144
-console.log("Found servers:", servers.items);
145
-```
146
-
147
-### Update Server Configuration
148
-
149
-```typescript
150
-// Update an existing server (uses traditional API signature)
151
-const updatedServer = await composio.mcp.update(
152
- "server-uuid",
153
- "Updated Gmail Server",
154
- [
155
- {
156
- toolkit: "gmail",
157
- authConfigId: "ac_new_auth_config",
158
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
159
- }
160
- ],
161
- { isChatAuth: true }
162
-);
163
-```
164
-
165
-## Authentication Configuration
166
-
167
-### Option 1: Pre-authenticate Users (Recommended)
168
-
169
-Authenticate users upfront via the Composio SDK/API before they use the MCP server:
170
-
171
-```typescript
172
-// Check what authentication is needed
173
-const authParams = await composio.mcp.getConnectionParams(
174
- mcpConfig.id,
175
- "gmail"
176
-);
177
-
178
-// Initiate authentication for a user
179
-const authRequest = await composio.mcp.authorize(
180
- "user123@example.com",
181
- mcpConfig.id,
182
- "gmail"
183
-);
184
-
185
-if (authRequest.redirectUrl) {
186
- console.log("Please complete authentication:", authRequest.redirectUrl);
187
-}
188
-```
189
-
190
-### Option 2: Agent-guided Authentication
191
-
192
-Let the agent authenticate users on-demand by including helper actions:
193
-
194
-```typescript
195
-const serverUrls = await composio.mcp.getServer(
196
- mcpConfig.id,
197
- "user123@example.com"
198
-);
199
-
200
-// The server URLs will include helper actions that guide users through authentication
201
-```
202
-
203
-<Tip>
204
-Pre-authentication is recommended for production applications as it provides better user experience and more predictable behavior.
205
-</Tip>
206
-
207
-## Best Practices
208
-
209
-1. **Use meaningful server names** - This helps with organization and makes servers easier to find.
210
-2. **Limit tools appropriately** - Only include the tools your users actually need.
211
-3. **Check connection status** - Always verify user authentication before using server URLs.
212
-4. **Handle authentication gracefully** - Provide clear instructions when users need to authenticate.
213
-5. **Use the server ID** - Store the server ID from the create response for generating URLs.
214
-
215
-<Warning>
216
-SSE support is deprecated. If you're using `/sse` endpoints or `transport=sse` query parameters, migrate to the standard `/mcp` endpoints.
217
-</Warning>
218
-
219
-### Configuring Authentication
220
-You or your users need to authenticate against an app to use its MCP server through Composio. This can be done in two ways:
221
-
222
-* Authenticate users upfront via the Composio SDK/API. Follow [custom auth configs](/docs/custom-auth-configs) to learn how to connect users. This is recommended for most use cases.
223
-* Let the agent authenticate users on demand. Passing `include_composio_helper_actions=true` in the URL will include Composio's helper actions, and the agent will guide the user through authentication on demand.
fern/pages/src/mcp/implementation.mdx
deleted
-192
@@ -1,192 +0,0 @@
1
----
2
-title: MCP implementation
3
-subtitle: Complete guide to MCP server development
4
----
5
-
6
-This guide covers everything you need to implement MCP servers in production.
7
-
8
-## Authentication
9
-
10
-MCP servers handle authentication for you. Configure OAuth, API keys, or custom auth through auth configs.
11
-
12
-### Check connection status
13
-
14
-<CodeGroup>
15
-<CodeGroupItem title="Python">
16
-```python
17
-# Python SDK - connection checking coming soon
18
-# For now, use the generate method which handles auth
19
-instance = server.generate("user@example.com")
20
-```
21
-</CodeGroupItem>
22
-<CodeGroupItem title="TypeScript">
23
-```typescript
24
-const status = await composio.mcp.getUserConnectionStatus(
25
- "user@example.com",
26
- server.id
27
-);
28
-
29
-if (!status.connected) {
30
- // Handle missing authentication
31
- const auth = await composio.mcp.authorize(
32
- "user@example.com",
33
- server.id,
34
- "gmail"
35
- );
36
- console.log(`Authenticate at: ${auth.redirectUrl}`);
37
-}
38
-```
39
-</CodeGroupItem>
40
-</CodeGroup>
41
-
42
-## Server management
43
-
44
-### List servers
45
-
46
-<CodeGroup>
47
-<CodeGroupItem title="Python">
48
-```python
49
-# List all servers
50
-servers = composio.mcp.list()
51
-
52
-# Filter by toolkit
53
-gmail_servers = composio.mcp.list(toolkits="gmail")
54
-```
55
-</CodeGroupItem>
56
-<CodeGroupItem title="TypeScript">
57
-```typescript
58
-// List all servers
59
-const servers = await composio.mcp.list();
60
-
61
-// Filter by toolkit
62
-const gmailServers = await composio.mcp.list({
63
- toolkits: ["gmail"]
64
-});
65
-```
66
-</CodeGroupItem>
67
-</CodeGroup>
68
-
69
-### Update servers
70
-
71
-<CodeGroup>
72
-<CodeGroupItem title="Python">
73
-```python
74
-updated = composio.mcp.update(
75
- server_id="mcp_server_id",
76
- name="updated-name",
77
- allowed_tools=["GMAIL_FETCH_EMAILS"]
78
-)
79
-```
80
-</CodeGroupItem>
81
-<CodeGroupItem title="TypeScript">
82
-```typescript
83
-const updated = await composio.mcp.update(
84
- "mcp_server_id",
85
- "updated-name",
86
- [{ toolkit: "gmail", authConfigId: "ac_new" }]
87
-);
88
-```
89
-</CodeGroupItem>
90
-</CodeGroup>
91
-
92
-## Multi-toolkit servers
93
-
94
-Combine multiple services in a single MCP server:
95
-
96
-<CodeGroup>
97
-<CodeGroupItem title="Python">
98
-```python
99
-server = composio.mcp.create(
100
- name="productivity-suite",
101
- toolkits=[
102
- {"toolkit": "gmail", "auth_config": "ac_gmail"},
103
- {"toolkit": "slack", "auth_config": "ac_slack"},
104
- {"toolkit": "github", "auth_config": "ac_github"}
105
- ],
106
- allowed_tools=[
107
- "GMAIL_FETCH_EMAILS",
108
- "SLACK_SEND_MESSAGE",
109
- "GITHUB_CREATE_ISSUE"
110
- ]
111
-)
112
-```
113
-</CodeGroupItem>
114
-<CodeGroupItem title="TypeScript">
115
-```typescript
116
-const server = await composio.mcp.create(
117
- "productivity-suite",
118
- [
119
- { authConfigId: "ac_gmail", allowedTools: ["GMAIL_FETCH_EMAILS"] },
120
- { authConfigId: "ac_slack", allowedTools: ["SLACK_SEND_MESSAGE"] },
121
- { authConfigId: "ac_github", allowedTools: ["GITHUB_CREATE_ISSUE"] }
122
- ],
123
- { isChatAuth: true }
124
-);
125
-```
126
-</CodeGroupItem>
127
-</CodeGroup>
128
-
129
-## Error handling
130
-
131
-<CodeGroup>
132
-<CodeGroupItem title="Python">
133
-```python
134
-from composio.exceptions import ValidationError
135
-
136
-try:
137
- server = composio.mcp.create(
138
- name="test-server",
139
- toolkits=[{"toolkit": "gmail"}]
140
- )
141
-except ValidationError as e:
142
- print(f"Error: {e}")
143
-```
144
-</CodeGroupItem>
145
-<CodeGroupItem title="TypeScript">
146
-```typescript
147
-try {
148
- const server = await composio.mcp.create(
149
- "test-server",
150
- [{ authConfigId: "invalid" }]
151
- );
152
-} catch (error) {
153
- if (error instanceof ValidationError) {
154
- console.error("Validation failed:", error.message);
155
- }
156
-}
157
-```
158
-</CodeGroupItem>
159
-</CodeGroup>
160
-
161
-## API reference
162
-
163
-### Python methods
164
-
165
-| Method | Description |
166
-|--------|-------------|
167
-| `create()` | Create new MCP server |
168
-| `generate()` | Generate user instance |
169
-| `list()` | List servers |
170
-| `get()` | Get server details |
171
-| `update()` | Update server |
172
-| `delete()` | Delete server |
173
-
174
-### TypeScript methods
175
-
176
-| Method | Description |
177
-|--------|-------------|
178
-| `create()` | Create new MCP server |
179
-| `getServer()` | Generate user URLs |
180
-| `getUserConnectionStatus()` | Check auth status |
181
-| `list()` | List servers |
182
-| `get()` | Get server details |
183
-| `getByName()` | Find server by name |
184
-| `update()` | Update server |
185
-| `delete()` | Delete server |
186
-| `authorize()` | Start auth flow |
187
-
188
-## Next steps
189
-
190
-- [Quickstart guide](/docs/mcp-quickstart) - Get started quickly
191
-- [Provider integrations](/docs/mcp-providers) - Framework-specific implementations
192
-- [Troubleshooting](/docs/troubleshooting/mcp) - Common issues and solutions
\ No newline at end of file
fern/pages/src/mcp/introduction.mdx
deleted
-437
@@ -1,437 +0,0 @@
1
----
2
-title: Composio MCP Introduction
3
-subtitle: "Complete guide to using Composio MCP servers"
4
-image: "https://og.composio.dev/api/og?title=Composio%20MCP%20Introduction"
5
-keywords: "MCP, Model Context Protocol, Composio, SDK, TypeScript"
6
-hide-nav-links: true
7
----
8
-
9
-## What is Composio MCP?
10
-
11
-[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open protocol that standardizes how LLM-powered applications provide tools and context to underlying models. Composio MCP servers make all [Composio tools](/tools) available through this standardized protocol, enabling seamless integration with MCP-compatible clients.
12
-
13
-<Note>
14
-The MCP SDK has been updated to use positional parameters instead of object parameters for better performance and simpler usage. All examples below reflect the latest API structure.
15
-</Note>
16
-
17
-## Key Features
18
-
19
-- **🔧 1000+ Tools**: Access to all Composio tools through MCP
20
-- **🔐 Managed Authentication**: Streamlined user authentication and account management
21
-- **🌍 Multi-Framework Support**: Works with Claude, Anthropic, OpenAI, Mastra, and more
22
-- **📊 Connection Monitoring**: Real-time status tracking for user connections
23
-- **⚡ Easy Setup**: Simple SDK with intuitive named object arguments
24
-- **🎯 Flexible Configuration**: Fine-grained control over tools and permissions
25
-
26
-## Quick Start
27
-
28
-### Installation
29
-
30
-```bash
31
-npm install @composio/core
32
-```
33
-
34
-### Basic Usage
35
-
36
-```typescript
37
-import { Composio } from '@composio/core';
38
-
39
-const composio = new Composio({
40
- apiKey: process.env.COMPOSIO_API_KEY,
41
-});
42
-
43
-// Create an MCP server
44
-const mcpServer = await composio.mcp.create(
45
- "My Gmail Server",
46
- [
47
- {
48
- authConfigId: "ac_your_auth_config_id",
49
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
50
- }
51
- ],
52
- {
53
- isChatAuth: true
54
- }
55
-);
56
-
57
-// Get server URLs for a user
58
-const serverUrls = await composio.mcp.getServer(
59
- mcpServer.id,
60
- "user@example.com"
61
-);
62
-
63
-console.log("MCP Server URLs:", serverUrls);
64
-```
65
-
66
-## Complete API Reference
67
-
68
-### Creating MCP Servers
69
-
70
-The `create` method uses positional parameters for better performance:
71
-
72
-```typescript
73
-const mcpServer = await composio.mcp.create(
74
- name: string, // Unique server name
75
- serverConfig: Array<{ // Auth configurations
76
- authConfigId: string, // Your auth config ID
77
- allowedTools: string[] // List of tool names
78
- }>,
79
- options: {
80
- isChatAuth?: boolean // Enable chat-based auth (default: false)
81
- }
82
-);
83
-```
84
-
85
-**Complete Example:**
86
-
87
-```typescript
88
-const mcpServer = await composio.mcp.create(
89
- "Multi-Service Productivity Server",
90
- [
91
- {
92
- authConfigId: "ac_gmail_config",
93
- allowedTools: [
94
- "GMAIL_FETCH_EMAILS",
95
- "GMAIL_SEND_EMAIL",
96
- "GMAIL_CREATE_DRAFT"
97
- ]
98
- },
99
- {
100
- authConfigId: "ac_slack_config",
101
- allowedTools: [
102
- "SLACK_SEND_MESSAGE",
103
- "SLACK_GET_CHANNELS"
104
- ]
105
- }
106
- ],
107
- {
108
- isChatAuth: true
109
- }
110
-);
111
-
112
-console.log(`✅ Server created: ${mcpServer.id}`);
113
-console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
114
-```
115
-
116
-### Generating Server URLs
117
-
118
-The `getServer` method provides URLs for MCP clients to connect:
119
-
120
-```typescript
121
-const serverUrls = await composio.mcp.getServer(
122
- id: string, // Server ID
123
- userId: string // User identifier
124
-);
125
-```
126
-
127
-**Examples:**
128
-
129
-```typescript
130
-// Basic usage
131
-const basicUrls = await composio.mcp.getServer(
132
- "mcp_server_id",
133
- "user123@example.com"
134
-);
135
-
136
-// Using server ID from create response
137
-const serverUrls = await composio.mcp.getServer(
138
- mcpServer.id,
139
- "user123@example.com"
140
-);
141
-```
142
-
143
-### Checking User Connection Status
144
-
145
-Before using an MCP server, check if users have the required connected accounts:
146
-
147
-```typescript
148
-const connectionStatus = await composio.mcp.getUserConnectionStatus(
149
- userId: string, // User identifier
150
- id: string // Server ID
151
-);
152
-
153
-// Returns: McpUserConnectionStatus
154
-{
155
- type: "CONNECTED" | "DISCONNECTED",
156
- connected: boolean,
157
- connectedToolkits: {
158
- [toolkitName: string]: {
159
- type: "CONNECTED" | "DISCONNECTED",
160
- connected: boolean,
161
- toolkit: string,
162
- connectedAccountId?: string // Present if connected
163
- }
164
- }
165
-}
166
-```
167
-
168
-**Complete Example:**
169
-
170
-```typescript
171
-const status = await composio.mcp.getUserConnectionStatus(
172
- "user123@example.com",
173
- mcpServer.id
174
-);
175
-
176
-console.log(`Overall status: ${status.connected ? "✅ Ready" : "❌ Needs auth"}`);
177
-
178
-// Handle missing connections
179
-if (!status.connected) {
180
- for (const [toolkit, toolkitStatus] of Object.entries(status.connectedToolkits)) {
181
- if (!toolkitStatus.connected) {
182
- console.log(`❌ ${toolkit} requires authentication`);
183
-
184
- // Get authentication parameters
185
- const authParams = await composio.mcp.getConnectionParams(
186
- mcpServer.id,
187
- toolkit
188
- );
189
-
190
- // Initiate authentication
191
- const authRequest = await composio.mcp.authorize(
192
- "user123@example.com",
193
- mcpServer.id,
194
- toolkit
195
- );
196
-
197
- if (authRequest.redirectUrl) {
198
- console.log(`🔗 Authenticate here: ${authRequest.redirectUrl}`);
199
- }
200
- } else {
201
- console.log(`✅ ${toolkit} connected (${toolkitStatus.connectedAccountId})`);
202
- }
203
- }
204
-}
205
-```
206
-
207
-### Managing Existing Servers
208
-
209
-#### Find Servers by Name
210
-
211
-```typescript
212
-const server = await composio.mcp.getByName("My Gmail Server");
213
-console.log(`Found server: ${server.id}`);
214
-```
215
-
216
-#### List All Servers
217
-
218
-```typescript
219
-const servers = await composio.mcp.list({
220
- page: 1,
221
- limit: 10,
222
- toolkits: ["gmail", "slack"], // Filter by toolkits
223
- authConfigs: ["ac_123"], // Filter by auth configs
224
- name: "production" // Filter by name pattern
225
-});
226
-
227
-console.log(`Found ${servers.items?.length} servers`);
228
-```
229
-
230
-#### Get Server Details
231
-
232
-```typescript
233
-const serverDetails = await composio.mcp.get("mcp_server_id");
234
-console.log("Server details:", serverDetails);
235
-```
236
-
237
-#### Update Server Configuration
238
-
239
-```typescript
240
-const updatedServer = await composio.mcp.update(
241
- "mcp_server_id",
242
- "Updated Server Name",
243
- [
244
- {
245
- toolkit: "gmail",
246
- authConfigId: "ac_new_config",
247
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
248
- }
249
- ],
250
- { isChatAuth: true }
251
-);
252
-```
253
-
254
-#### Delete Server
255
-
256
-```typescript
257
-const deleteResult = await composio.mcp.delete("mcp_server_id");
258
-console.log("Server deleted:", deleteResult.deleted);
259
-```
260
-
261
-## Authentication Workflows
262
-
263
-### Pre-Authentication (Recommended)
264
-
265
-Authenticate users before they use the MCP server:
266
-
267
-```typescript
268
-// 1. Check what's needed
269
-const authParams = await composio.mcp.getConnectionParams(
270
- mcpServer.id,
271
- "gmail"
272
-);
273
-
274
-console.log("Required fields:", authParams.required_fields);
275
-
276
-// 2. Initiate authentication
277
-const authRequest = await composio.mcp.authorize(
278
- "user@example.com",
279
- mcpServer.id,
280
- "gmail"
281
-);
282
-
283
-// 3. Direct user to authentication URL
284
-if (authRequest.redirectUrl) {
285
- console.log("Please visit:", authRequest.redirectUrl);
286
-}
287
-
288
-// 4. Verify connection after user completes auth
289
-const finalStatus = await composio.mcp.getUserConnectionStatus(
290
- "user@example.com",
291
- mcpServer.id
292
-);
293
-
294
-if (finalStatus.connected) {
295
- console.log("✅ All toolkits connected, ready to use!");
296
-}
297
-```
298
-
299
-### Agent-Guided Authentication
300
-
301
-Let the agent handle authentication on-demand:
302
-
303
-```typescript
304
-const serverUrls = await composio.mcp.getServer(
305
- mcpServer.id,
306
- "user@example.com"
307
-);
308
-
309
-// The agent can now guide users through authentication as needed
310
-```
311
-
312
-## Real-World Example: Complete Gmail Integration
313
-
314
-```typescript
315
-import { Composio } from '@composio/core';
316
-
317
-const composio = new Composio({
318
- apiKey: process.env.COMPOSIO_API_KEY,
319
-});
320
-
321
-async function setupGmailMCP(userId: string) {
322
- // 1. Check if server already exists
323
- let gmailServer;
324
- try {
325
- gmailServer = await composio.mcp.getByName("Production Gmail Server");
326
- console.log("✅ Using existing server");
327
- } catch (error) {
328
- // 2. Create new server if it doesn't exist
329
- console.log("📦 Creating new Gmail server...");
330
- gmailServer = await composio.mcp.create(
331
- "Production Gmail Server",
332
- [
333
- {
334
- authConfigId: process.env.GMAIL_AUTH_CONFIG_ID!,
335
- allowedTools: [
336
- "GMAIL_FETCH_EMAILS",
337
- "GMAIL_SEND_EMAIL",
338
- "GMAIL_CREATE_DRAFT",
339
- "GMAIL_SEARCH_EMAILS"
340
- ]
341
- }
342
- ],
343
- {
344
- isChatAuth: true
345
- }
346
- );
347
- }
348
-
349
- // 3. Check user connection status
350
- const connectionStatus = await composio.mcp.getUserConnectionStatus(
351
- userId,
352
- gmailServer.id
353
- );
354
-
355
- // 4. Handle authentication if needed
356
- if (!connectionStatus.connected) {
357
- console.log("🔐 User needs to authenticate with Gmail");
358
-
359
- const authRequest = await composio.mcp.authorize(
360
- userId,
361
- gmailServer.id,
362
- "gmail"
363
- );
364
-
365
- return {
366
- server: gmailServer,
367
- needsAuth: true,
368
- authUrl: authRequest.redirectUrl
369
- };
370
- }
371
-
372
- // 5. Generate server URLs for MCP client
373
- const serverUrls = await composio.mcp.getServer(
374
- gmailServer.id,
375
- userId
376
- );
377
-
378
- return {
379
- server: gmailServer,
380
- needsAuth: false,
381
- urls: serverUrls
382
- };
383
-}
384
-
385
-// Usage
386
-const result = await setupGmailMCP("user@example.com");
387
-
388
-if (result.needsAuth) {
389
- console.log(`Please authenticate: ${result.authUrl}`);
390
-} else {
391
- console.log("Ready to use:", result.urls);
392
-}
393
-```
394
-
395
-## Error Handling
396
-
397
-```typescript
398
-try {
399
- const mcpServer = await composio.mcp.create(
400
- "Test Server",
401
- [
402
- {
403
- authConfigId: "invalid_config",
404
- allowedTools: ["INVALID_TOOL"]
405
- }
406
- ],
407
- {
408
- isChatAuth: true
409
- }
410
- );
411
-} catch (error) {
412
- if (error instanceof ValidationError) {
413
- console.error("Configuration error:", error.message);
414
- console.error("Details:", error.meta);
415
- } else {
416
- console.error("Unexpected error:", error);
417
- }
418
-}
419
-```
420
-
421
-## Best Practices
422
-
423
-1. **Use descriptive server names** - Makes management and debugging easier
424
-2. **Check connection status first** - Always verify authentication before generating URLs
425
-3. **Handle authentication gracefully** - Provide clear instructions and error messages
426
-4. **Limit tools appropriately** - Only include tools your application actually needs
427
-5. **Cache server configurations** - Reuse existing servers when possible
428
-6. **Monitor connection health** - Regularly check and refresh user connections
429
-7. **Store server IDs** - Keep track of server IDs from create responses for generating URLs
430
-
431
-## Next Steps
432
-
433
-- **[Developer Guide](/docs/mcp-developers)** - Detailed implementation guide
434
-- **[Provider Examples](/docs/mcp-providers)** - Framework-specific implementations
435
-- **[Partner Program](/docs/mcp-partner-api)** - Enterprise integration options
436
-- **[API Reference](/api-reference/mcp)** - Complete API documentation
437
-
fern/pages/src/mcp/server-management.mdx
+20
-40
@@ -88,8 +88,8 @@ const productionServers = await composio.mcp.list({
88
```python
89
# Get by ID
90
server = composio.mcp.get("mcp_server_id")
91
-print(f"Server: {server['name']}")
92
-print(f"Toolkits: {server['toolkits']}")
91
+print(f"Server name: {server.name}")
92
+print(f"Toolkits: {server.toolkits}")
93
```
94
</CodeGroupItem>
95
<CodeGroupItem title="TypeScript">
@@ -214,6 +214,13 @@ instance = server.generate("user@example.com")
214
215
print(f"URL: {instance['url']}")
216
print(f"Tools: {instance['allowed_tools']}")
217
+
218
+# Chat-based authentication is enabled by default
219
+# Set manually_manage_connections=True to disable it:
220
+instance_manual = server.generate(
221
+ "user@example.com",
222
+ manually_manage_connections=True
223
+)
224
```
225
</CodeGroupItem>
226
<CodeGroupItem title="TypeScript">
@@ -230,10 +237,21 @@ const urls2 = await server.getServer({
237
});
238
239
console.log("URL:", urls);
240
+
241
+// Note: URLs include include_composio_helper_actions=true when
242
+// isChatAuth is enabled, allowing agents to guide authentication
243
```
244
</CodeGroupItem>
245
</CodeGroup>
246
247
+<Note>
248
+**Chat-based authentication:**
249
+- **TypeScript**: Set `isChatAuth: true` during server creation to enable
250
+- **Python**: Enabled by default (set `manually_manage_connections=False` or omit it)
251
+
252
+When enabled, the agent can authenticate users dynamically during conversation if they're missing required connections.
253
+</Note>
254
+
255
## Best practices
256
257
- **Use descriptive names** - Makes servers easy to find
@@ -241,41 +259,3 @@ console.log("URL:", urls);
259
- **Reuse servers** - Don't create duplicates for same configuration
260
- **Store server IDs** - Keep track of created server IDs
261
244
-## API reference
245
-
246
-### Python methods
247
-
248
-| Method | Description |
249
-|--------|-------------|
250
-| `create()` | Create new server |
251
-| `list()` | List servers |
252
-| `get()` | Get server by ID |
253
-| `update()` | Update server |
254
-| `delete()` | Delete server |
255
-| `generate()` | Generate user URL |
256
-
257
-### TypeScript methods
258
-
259
-| Method | Description |
260
-|--------|-------------|
261
-| `create()` | Create new server |
262
-| `list()` | List servers |
263
-| `get()` | Get server by ID |
264
-| `getByName()` | Find server by name |
265
-| `update()` | Update server |
266
-| `delete()` | Delete server |
267
-| `getServer()` | Generate user URL |
268
-
269
-## Next steps
270
-
271
-<Cards>
272
- <Card title="Authentication" href="/docs/mcp-authentication" icon="lock">
273
- Handle user authentication
274
- </Card>
275
- <Card title="Providers" href="/docs/mcp-providers" icon="code">
276
- Framework integrations
277
- </Card>
278
- <Card title="Troubleshooting" href="/docs/troubleshooting/mcp" icon="wrench">
279
- Common issues
280
- </Card>
281
-</Cards>
\ No newline at end of file