@devries-cameron20 / composio-1 / commits / 720d364f1
Fork 0

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

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