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.

server management python

Sushmithamallesh720d364f1355
diff --git a/fern/docs.yml b/fern/docs.yml
index da3b3da2e..a65d0ea3a 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -174,15 +174,6 @@ navigation:
- page: Partner Program
path: pages/dist/mcp/partner-api.mdx
slug: mcp-partner-api
- - page: Developers (old)
- path: pages/dist/mcp/developers.mdx
- slug: mcp-developers-old
- - page: Introduction (old)
- path: pages/dist/mcp/introduction.mdx
- slug: mcp-introduction-old
- - page: Implementation (old)
- path: pages/dist/mcp/implementation.mdx
- slug: mcp-implementation-old
- section: Tool Router (Beta)
icon: tools
skip-slug: true
diff --git a/fern/pages/src/mcp/authentication.mdx b/fern/pages/src/mcp/authentication.mdx
deleted file mode 100644
index 98276a9c4..000000000
--- a/fern/pages/src/mcp/authentication.mdx
+++ /dev/null
@@ -1,169 +0,0 @@
----
-title: MCP authentication
-subtitle: Managing user authentication for MCP servers
----
-
-Before users can access tools through your MCP server, they need to authenticate with the external services.
-
-## Check connection status
-
-Verify if a user has the required connections before generating server URLs.
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-# Python SDK - connection checking coming soon
-# For now, the generate method handles auth automatically
-instance = server.generate("[email protected]")
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-const status = await composio.mcp.getUserConnectionStatus(
- server.id
-);
-
-if (status.connected) {
- console.log("✅ All toolkits connected");
-} else {
- console.log("❌ Missing connections:");
-
- for (const [toolkit, toolkitStatus] of Object.entries(status.connectedToolkits)) {
- if (!toolkitStatus.connected) {
- console.log(`- ${toolkit}: Not connected`);
- }
- }
-}
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## Authentication flows
-
-### Pre-authentication (Recommended)
-
-Authenticate users before they use the MCP server for a smoother experience.
-
-<CodeGroup>
-<CodeGroupItem title="TypeScript">
-```typescript
-// 1. Check what's needed
-const authParams = await composio.mcp.getConnectionParams(
- server.id,
- "gmail"
-);
-
-console.log("Required fields:", authParams.required_fields);
-
-// 2. Start authentication
-const authRequest = await composio.mcp.authorize(
- server.id,
- "gmail"
-);
-
-if (authRequest.redirectUrl) {
- // 3. Send user to authenticate
- console.log("Authenticate here:", authRequest.redirectUrl);
-
- // 4. After completion, verify
- const status = await composio.mcp.getUserConnectionStatus(
- server.id
- );
-
- if (status.connected) {
- console.log("✅ Ready to generate URLs");
- }
-}
-```
-</CodeGroupItem>
-</CodeGroup>
-
-### Chat-based authentication
-
-Let the AI agent guide users through authentication when needed.
-
-```typescript
-// Enable chat auth when creating the server
-const server = await composio.mcp.create(
- "assistant-server",
- [{ authConfigId: "ac_xyz", allowedTools: ["GMAIL_FETCH_EMAILS"] }],
- { isChatAuth: true } // Agent handles auth prompts
-);
-
-// Generate URLs directly - agent will handle missing auth
-const urls = await composio.mcp.getServer(
- server.id,
-);
-```
-
-## Auth config setup
-
-Auth configs define how users authenticate with external services. Create them in the [Composio dashboard](https://platform.composio.dev).
-
-### Types of auth
-
-- **OAuth** - Redirect-based flow (Gmail, Slack, GitHub)
-- **API Key** - Direct credential entry (OpenAI, Anthropic)
-- **Basic Auth** - Username/password
-
-### Creating auth configs
-
-1. Go to [Composio dashboard](https://platform.composio.dev)
-2. Navigate to Settings → Authentication
-3. Click "Create Auth Config"
-4. Select toolkit and auth type
-5. Configure scopes and permissions
-6. Save and copy the `authConfigId`
-
-## Handle authentication errors
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-try:
- instance = server.generate("[email protected]")
-except Exception as e:
- if "authentication" in str(e).lower():
- print("User needs to authenticate first")
- # Guide user to auth flow
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-try {
- const urls = await composio.mcp.getServer(
- server.id,
- );
-} catch (error) {
- if (error.message.includes("not connected")) {
- // Handle missing authentication
- const auth = await composio.mcp.authorize(
- server.id,
- "gmail"
- );
- console.log(`Please authenticate: ${auth.redirectUrl}`);
- }
-}
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## Next steps
-
-<Cards>
- <Card title="Server management" href="/docs/mcp-server-management" icon="server">
- Create and manage MCP servers
- </Card>
- <Card title="Quickstart" href="/docs/mcp-quickstart" icon="rocket">
- Get started quickly
- </Card>
- <Card title="Troubleshooting" href="/docs/troubleshooting/mcp" icon="wrench">
- Common auth issues
- </Card>
-</Cards>
\ No newline at end of file
diff --git a/fern/pages/src/mcp/developers.mdx b/fern/pages/src/mcp/developers.mdx
deleted file mode 100644
index 075b1d7c9..000000000
--- a/fern/pages/src/mcp/developers.mdx
+++ /dev/null
@@ -1,223 +0,0 @@
----
-title: MCP Servers for developers
-subtitle: "Guide to create and manage MCP servers"
-image: "https://og.composio.dev/api/og?title=MCP%20Servers%20for%20developers" # image for socials
-keywords: ""
-hide-nav-links: true
----
-
-<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>
-
-Composio MCP lets you build custom MCP servers that your users can connect to and use to perform actions.
-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.
-
-<Note>
-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.
-</Note>
-
-## Creating MCP Servers and Onboarding End Users
-<Steps>
- <Step title="Configure Authentication">
- - **Create and Configure Toolkit permissions:**
- - Select the specific scopes and permissions your integration requires for each connected application. This ensures your MCP server has the right level of access.
- - Check this guide on what auth config is and how to configue it - [Auth Config setup guide](/docs/custom-auth-configs)
-
- - **Customize the authentication experience (Optional):**
- - Create a seamless, branded experience by providing your own OAuth credentials and customizing the consent screens.
- - Learn more here - [Custom auth configs](/docs/custom-auth-configs)
- </Step>
- <Step title="Create and configure an MCP server">
-
- ```typescript
- import { Composio } from '@composio/core';
-
- const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
- });
-
- // Create an MCP server with the new API structure
- const mcpConfig = await composio.mcp.create(
- "Gmail MCP Server",
- [
- {
- authConfigId: "ac_auth_12", // Your auth config ID
- allowedTools: [
- "GMAIL_FETCH_EMAILS",
- "GMAIL_CREATE_EMAIL_DRAFT",
- "GMAIL_SEND_EMAIL"
- ]
- }
- ],
- {
- isChatAuth: true // Enable chat-based authentication
- }
- );
-
- console.log(`✅ MCP server created: ${mcpConfig.id}`);
- console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
- ```
- </Step>
- <Step title="Generate server URLs for users">
- **Using the SDK:**
- ```typescript
- // Get server URLs for a specific user
- const serverUrls = await composio.mcp.getServer(
- mcpConfig.id,
- );
-
- console.log("Server URLs:", serverUrls);
- ```
-
- **Using the server ID (from create response):**
- ```typescript
- // Get server URLs using the created server ID
- const serverUrls = await composio.mcp.getServer(
- mcpConfig.id,
- );
- ```
- </Step>
- <Step title="Client applications connect to the server">
- 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.
-
- **Example server URL structure:**
- ```
- https://mcp.composio.dev/composio/server/<UUID>/[email protected]
- ```
-
- **Optional query parameters:**
- | Query param | Purpose |
- |-------------|---------|
- | `user_id` | Bind the session to a user identifier from your app |
- | `connected_account_id` | Pin the session to a specific Composio connected account |
- | `include_composio_helper_actions=true` | Include helper tools for agent-guided authentication |
- </Step>
-</Steps>
-
-## Managing MCP Servers
-
-### Check User Connection Status
-
-Before using an MCP server, you can check if a user has the necessary connected accounts:
-
-```typescript
-// Check if a user has connected accounts for all required toolkits
-const connectionStatus = await composio.mcp.getUserConnectionStatus(
- mcpConfig.id
-);
-
-console.log("Overall connection status:", connectionStatus.connected);
-console.log("Individual toolkit status:", connectionStatus.connectedToolkits);
-
-// Handle missing connections
-if (!connectionStatus.connected) {
- Object.entries(connectionStatus.connectedToolkits).forEach(([toolkit, status]) => {
- if (!status.connected) {
- console.log(`❌ ${toolkit} not connected`);
- // Guide user through authentication
- }
- });
-}
-```
-
-### Find Servers by Name
-
-```typescript
-// Retrieve a server by its name
-const serverDetails = await composio.mcp.getByName("Gmail MCP Server");
-console.log("Server details:", serverDetails);
-```
-
-### List All Servers
-
-```typescript
-// List servers with filtering options
-const servers = await composio.mcp.list({
- page: 1,
- limit: 10,
- toolkits: ["gmail", "slack"], // Filter by toolkits
- name: "production" // Filter by name
-});
-
-console.log("Found servers:", servers.items);
-```
-
-### Update Server Configuration
-
-```typescript
-// Update an existing server (uses traditional API signature)
-const updatedServer = await composio.mcp.update(
- "server-uuid",
- "Updated Gmail Server",
- [
- {
- toolkit: "gmail",
- authConfigId: "ac_new_auth_config",
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
- }
- ],
- { isChatAuth: true }
-);
-```
-
-## Authentication Configuration
-
-### Option 1: Pre-authenticate Users (Recommended)
-
-Authenticate users upfront via the Composio SDK/API before they use the MCP server:
-
-```typescript
-// Check what authentication is needed
-const authParams = await composio.mcp.getConnectionParams(
- mcpConfig.id,
- "gmail"
-);
-
-// Initiate authentication for a user
-const authRequest = await composio.mcp.authorize(
- mcpConfig.id,
- "gmail"
-);
-
-if (authRequest.redirectUrl) {
- console.log("Please complete authentication:", authRequest.redirectUrl);
-}
-```
-
-### Option 2: Agent-guided Authentication
-
-Let the agent authenticate users on-demand by including helper actions:
-
-```typescript
-const serverUrls = await composio.mcp.getServer(
- mcpConfig.id,
-);
-
-// The server URLs will include helper actions that guide users through authentication
-```
-
-<Tip>
-Pre-authentication is recommended for production applications as it provides better user experience and more predictable behavior.
-</Tip>
-
-## Best Practices
-
-1. **Use meaningful server names** - This helps with organization and makes servers easier to find.
-2. **Limit tools appropriately** - Only include the tools your users actually need.
-3. **Check connection status** - Always verify user authentication before using server URLs.
-4. **Handle authentication gracefully** - Provide clear instructions when users need to authenticate.
-5. **Use the server ID** - Store the server ID from the create response for generating URLs.
-
-<Warning>
-SSE support is deprecated. If you're using `/sse` endpoints or `transport=sse` query parameters, migrate to the standard `/mcp` endpoints.
-</Warning>
-
-### Configuring Authentication
-You or your users need to authenticate against an app to use its MCP server through Composio. This can be done in two ways:
-
-* 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.
-* 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.
diff --git a/fern/pages/src/mcp/implementation.mdx b/fern/pages/src/mcp/implementation.mdx
deleted file mode 100644
index d79f37f0b..000000000
--- a/fern/pages/src/mcp/implementation.mdx
+++ /dev/null
@@ -1,192 +0,0 @@
----
-title: MCP implementation
-subtitle: Complete guide to MCP server development
----
-
-This guide covers everything you need to implement MCP servers in production.
-
-## Authentication
-
-MCP servers handle authentication for you. Configure OAuth, API keys, or custom auth through auth configs.
-
-### Check connection status
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-# Python SDK - connection checking coming soon
-# For now, use the generate method which handles auth
-instance = server.generate("[email protected]")
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-const status = await composio.mcp.getUserConnectionStatus(
- server.id
-);
-
-if (!status.connected) {
- // Handle missing authentication
- const auth = await composio.mcp.authorize(
- server.id,
- "gmail"
- );
- console.log(`Authenticate at: ${auth.redirectUrl}`);
-}
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## Server management
-
-### List servers
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-# List all servers
-servers = composio.mcp.list()
-
-# Filter by toolkit
-gmail_servers = composio.mcp.list(toolkits="gmail")
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-// List all servers
-const servers = await composio.mcp.list();
-
-// Filter by toolkit
-const gmailServers = await composio.mcp.list({
- toolkits: ["gmail"]
-});
-```
-</CodeGroupItem>
-</CodeGroup>
-
-### Update servers
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-updated = composio.mcp.update(
- server_id="mcp_server_id",
- name="updated-name",
- allowed_tools=["GMAIL_FETCH_EMAILS"]
-)
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-const updated = await composio.mcp.update(
- "mcp_server_id",
- "updated-name",
- [{ toolkit: "gmail", authConfigId: "ac_new" }]
-);
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## Multi-toolkit servers
-
-Combine multiple services in a single MCP server:
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-server = composio.mcp.create(
- name="productivity-suite",
- toolkits=[
- {"toolkit": "gmail", "auth_config": "ac_gmail"},
- {"toolkit": "slack", "auth_config": "ac_slack"},
- {"toolkit": "github", "auth_config": "ac_github"}
- ],
- allowed_tools=[
- "GMAIL_FETCH_EMAILS",
- "SLACK_SEND_MESSAGE",
- "GITHUB_CREATE_ISSUE"
- ]
-)
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-const server = await composio.mcp.create(
- "productivity-suite",
- [
- { authConfigId: "ac_gmail", allowedTools: ["GMAIL_FETCH_EMAILS"] },
- { authConfigId: "ac_slack", allowedTools: ["SLACK_SEND_MESSAGE"] },
- { authConfigId: "ac_github", allowedTools: ["GITHUB_CREATE_ISSUE"] }
- ],
- { isChatAuth: true }
-);
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## Error handling
-
-<CodeGroup>
-<CodeGroupItem title="Python">
-```python
-from composio.exceptions import ValidationError
-
-try:
- server = composio.mcp.create(
- name="test-server",
- toolkits=[{"toolkit": "gmail"}]
- )
-except ValidationError as e:
- print(f"Error: {e}")
-```
-</CodeGroupItem>
-<CodeGroupItem title="TypeScript">
-```typescript
-try {
- const server = await composio.mcp.create(
- "test-server",
- [{ authConfigId: "invalid" }]
- );
-} catch (error) {
- if (error instanceof ValidationError) {
- console.error("Validation failed:", error.message);
- }
-}
-```
-</CodeGroupItem>
-</CodeGroup>
-
-## API reference
-
-### Python methods
-
-| Method | Description |
-|--------|-------------|
-| `create()` | Create new MCP server |
-| `generate()` | Generate user instance |
-| `list()` | List servers |
-| `get()` | Get server details |
-| `update()` | Update server |
-| `delete()` | Delete server |
-
-### TypeScript methods
-
-| Method | Description |
-|--------|-------------|
-| `create()` | Create new MCP server |
-| `getServer()` | Generate user URLs |
-| `getUserConnectionStatus()` | Check auth status |
-| `list()` | List servers |
-| `get()` | Get server details |
-| `getByName()` | Find server by name |
-| `update()` | Update server |
-| `delete()` | Delete server |
-| `authorize()` | Start auth flow |
-
-## Next steps
-
-- [Quickstart guide](/docs/mcp-quickstart) - Get started quickly
-- [Provider integrations](/docs/mcp-providers) - Framework-specific implementations
-- [Troubleshooting](/docs/troubleshooting/mcp) - Common issues and solutions
\ No newline at end of file
diff --git a/fern/pages/src/mcp/introduction.mdx b/fern/pages/src/mcp/introduction.mdx
deleted file mode 100644
index 5695df01a..000000000
--- a/fern/pages/src/mcp/introduction.mdx
+++ /dev/null
@@ -1,437 +0,0 @@
----
-title: Composio MCP Introduction
-subtitle: "Complete guide to using Composio MCP servers"
-image: "https://og.composio.dev/api/og?title=Composio%20MCP%20Introduction"
-keywords: "MCP, Model Context Protocol, Composio, SDK, TypeScript"
-hide-nav-links: true
----
-
-## What is Composio MCP?
-
-[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.
-
-<Note>
-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.
-</Note>
-
-## Key Features
-
-- **🔧 1000+ Tools**: Access to all Composio tools through MCP
-- **🔐 Managed Authentication**: Streamlined user authentication and account management
-- **🌍 Multi-Framework Support**: Works with Claude, Anthropic, OpenAI, Mastra, and more
-- **📊 Connection Monitoring**: Real-time status tracking for user connections
-- **⚡ Easy Setup**: Simple SDK with intuitive named object arguments
-- **🎯 Flexible Configuration**: Fine-grained control over tools and permissions
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install @composio/core
-```
-
-### Basic Usage
-
-```typescript
-import { Composio } from '@composio/core';
-
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
-});
-
-// Create an MCP server
-const mcpServer = await composio.mcp.create(
- "My Gmail Server",
- [
- {
- authConfigId: "ac_your_auth_config_id",
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
- }
- ],
- {
- isChatAuth: true
- }
-);
-
-// Get server URLs for a user
-const serverUrls = await composio.mcp.getServer(
- mcpServer.id,
-);
-
-console.log("MCP Server URLs:", serverUrls);
-```
-
-## Complete API Reference
-
-### Creating MCP Servers
-
-The `create` method uses positional parameters for better performance:
-
-```typescript
-const mcpServer = await composio.mcp.create(
- name: string, // Unique server name
- serverConfig: Array<{ // Auth configurations
- authConfigId: string, // Your auth config ID
- allowedTools: string[] // List of tool names
- }>,
- options: {
- isChatAuth?: boolean // Enable chat-based auth (default: false)
- }
-);
-```
-
-**Complete Example:**
-
-```typescript
-const mcpServer = await composio.mcp.create(
- "Multi-Service Productivity Server",
- [
- {
- authConfigId: "ac_gmail_config",
- allowedTools: [
- "GMAIL_FETCH_EMAILS",
- "GMAIL_SEND_EMAIL",
- "GMAIL_CREATE_DRAFT"
- ]
- },
- {
- authConfigId: "ac_slack_config",
- allowedTools: [
- "SLACK_SEND_MESSAGE",
- "SLACK_GET_CHANNELS"
- ]
- }
- ],
- {
- isChatAuth: true
- }
-);
-
-console.log(`✅ Server created: ${mcpServer.id}`);
-console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
-```
-
-### Generating Server URLs
-
-The `getServer` method provides URLs for MCP clients to connect:
-
-```typescript
-const serverUrls = await composio.mcp.getServer(
- id: string, // Server ID
- userId: string // User identifier
-);
-```
-
-**Examples:**
-
-```typescript
-// Basic usage
-const basicUrls = await composio.mcp.getServer(
- "mcp_server_id",
-);
-
-// Using server ID from create response
-const serverUrls = await composio.mcp.getServer(
- mcpServer.id,
-);
-```
-
-### Checking User Connection Status
-
-Before using an MCP server, check if users have the required connected accounts:
-
-```typescript
-const connectionStatus = await composio.mcp.getUserConnectionStatus(
- userId: string, // User identifier
- id: string // Server ID
-);
-
-// Returns: McpUserConnectionStatus
-{
- type: "CONNECTED" | "DISCONNECTED",
- connected: boolean,
- connectedToolkits: {
- [toolkitName: string]: {
- type: "CONNECTED" | "DISCONNECTED",
- connected: boolean,
- toolkit: string,
- connectedAccountId?: string // Present if connected
- }
- }
-}
-```
-
-**Complete Example:**
-
-```typescript
-const status = await composio.mcp.getUserConnectionStatus(
- mcpServer.id
-);
-
-console.log(`Overall status: ${status.connected ? "✅ Ready" : "❌ Needs auth"}`);
-
-// Handle missing connections
-if (!status.connected) {
- for (const [toolkit, toolkitStatus] of Object.entries(status.connectedToolkits)) {
- if (!toolkitStatus.connected) {
- console.log(`❌ ${toolkit} requires authentication`);
-
- // Get authentication parameters
- const authParams = await composio.mcp.getConnectionParams(
- mcpServer.id,
- toolkit
- );
-
- // Initiate authentication
- const authRequest = await composio.mcp.authorize(
- mcpServer.id,
- toolkit
- );
-
- if (authRequest.redirectUrl) {
- console.log(`🔗 Authenticate here: ${authRequest.redirectUrl}`);
- }
- } else {
- console.log(`✅ ${toolkit} connected (${toolkitStatus.connectedAccountId})`);
- }
- }
-}
-```
-
-### Managing Existing Servers
-
-#### Find Servers by Name
-
-```typescript
-const server = await composio.mcp.getByName("My Gmail Server");
-console.log(`Found server: ${server.id}`);
-```
-
-#### List All Servers
-
-```typescript
-const servers = await composio.mcp.list({
- page: 1,
- limit: 10,
- toolkits: ["gmail", "slack"], // Filter by toolkits
- authConfigs: ["ac_123"], // Filter by auth configs
- name: "production" // Filter by name pattern
-});
-
-console.log(`Found ${servers.items?.length} servers`);
-```
-
-#### Get Server Details
-
-```typescript
-const serverDetails = await composio.mcp.get("mcp_server_id");
-console.log("Server details:", serverDetails);
-```
-
-#### Update Server Configuration
-
-```typescript
-const updatedServer = await composio.mcp.update(
- "mcp_server_id",
- "Updated Server Name",
- [
- {
- toolkit: "gmail",
- authConfigId: "ac_new_config",
- allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
- }
- ],
- { isChatAuth: true }
-);
-```
-
-#### Delete Server
-
-```typescript
-const deleteResult = await composio.mcp.delete("mcp_server_id");
-console.log("Server deleted:", deleteResult.deleted);
-```
-
-## Authentication Workflows
-
-### Pre-Authentication (Recommended)
-
-Authenticate users before they use the MCP server:
-
-```typescript
-// 1. Check what's needed
-const authParams = await composio.mcp.getConnectionParams(
- mcpServer.id,
- "gmail"
-);
-
-console.log("Required fields:", authParams.required_fields);
-
-// 2. Initiate authentication
-const authRequest = await composio.mcp.authorize(
- mcpServer.id,
- "gmail"
-);
-
-// 3. Direct user to authentication URL
-if (authRequest.redirectUrl) {
- console.log("Please visit:", authRequest.redirectUrl);
-}
-
-// 4. Verify connection after user completes auth
-const finalStatus = await composio.mcp.getUserConnectionStatus(
- mcpServer.id
-);
-
-if (finalStatus.connected) {
- console.log("✅ All toolkits connected, ready to use!");
-}
-```
-
-### Agent-Guided Authentication
-
-Let the agent handle authentication on-demand:
-
-```typescript
-const serverUrls = await composio.mcp.getServer(
- mcpServer.id,
-);
-
-// The agent can now guide users through authentication as needed
-```
-
-## Real-World Example: Complete Gmail Integration
-
-```typescript
-import { Composio } from '@composio/core';
-
-const composio = new Composio({
- apiKey: process.env.COMPOSIO_API_KEY,
-});
-
-async function setupGmailMCP(userId: string) {
- // 1. Check if server already exists
- let gmailServer;
- try {
- gmailServer = await composio.mcp.getByName("Production Gmail Server");
- console.log("✅ Using existing server");
- } catch (error) {
- // 2. Create new server if it doesn't exist
- console.log("📦 Creating new Gmail server...");
- gmailServer = await composio.mcp.create(
- "Production Gmail Server",
- [
- {
- authConfigId: process.env.GMAIL_AUTH_CONFIG_ID!,
- allowedTools: [
- "GMAIL_FETCH_EMAILS",
- "GMAIL_SEND_EMAIL",
- "GMAIL_CREATE_DRAFT",
- "GMAIL_SEARCH_EMAILS"
- ]
- }
- ],
- {
- isChatAuth: true
- }
- );
- }
-
- // 3. Check user connection status
- const connectionStatus = await composio.mcp.getUserConnectionStatus(
- userId,
- gmailServer.id
- );
-
- // 4. Handle authentication if needed
- if (!connectionStatus.connected) {
- console.log("🔐 User needs to authenticate with Gmail");
-
- const authRequest = await composio.mcp.authorize(
- userId,
- gmailServer.id,
- "gmail"
- );
-
- return {
- server: gmailServer,
- needsAuth: true,
- authUrl: authRequest.redirectUrl
- };
- }
-
- // 5. Generate server URLs for MCP client
- const serverUrls = await composio.mcp.getServer(
- gmailServer.id,
- userId
- );
-
- return {
- server: gmailServer,
- needsAuth: false,
- urls: serverUrls
- };
-}
-
-// Usage
-const result = await setupGmailMCP("[email protected]");
-
-if (result.needsAuth) {
- console.log(`Please authenticate: ${result.authUrl}`);
-} else {
- console.log("Ready to use:", result.urls);
-}
-```
-
-## Error Handling
-
-```typescript
-try {
- const mcpServer = await composio.mcp.create(
- "Test Server",
- [
- {
- authConfigId: "invalid_config",
- allowedTools: ["INVALID_TOOL"]
- }
- ],
- {
- isChatAuth: true
- }
- );
-} catch (error) {
- if (error instanceof ValidationError) {
- console.error("Configuration error:", error.message);
- console.error("Details:", error.meta);
- } else {
- console.error("Unexpected error:", error);
- }
-}
-```
-
-## Best Practices
-
-1. **Use descriptive server names** - Makes management and debugging easier
-2. **Check connection status first** - Always verify authentication before generating URLs
-3. **Handle authentication gracefully** - Provide clear instructions and error messages
-4. **Limit tools appropriately** - Only include tools your application actually needs
-5. **Cache server configurations** - Reuse existing servers when possible
-6. **Monitor connection health** - Regularly check and refresh user connections
-7. **Store server IDs** - Keep track of server IDs from create responses for generating URLs
-
-## Next Steps
-
-- **[Developer Guide](/docs/mcp-developers)** - Detailed implementation guide
-- **[Provider Examples](/docs/mcp-providers)** - Framework-specific implementations
-- **[Partner Program](/docs/mcp-partner-api)** - Enterprise integration options
-- **[API Reference](/api-reference/mcp)** - Complete API documentation
-
diff --git a/fern/pages/src/mcp/server-management.mdx b/fern/pages/src/mcp/server-management.mdx
index 198e80bff..35a1bc708 100644
--- a/fern/pages/src/mcp/server-management.mdx
+++ b/fern/pages/src/mcp/server-management.mdx
@@ -88,8 +88,8 @@ const productionServers = await composio.mcp.list({
```python
# Get by ID
server = composio.mcp.get("mcp_server_id")
-print(f"Server: {server['name']}")
-print(f"Toolkits: {server['toolkits']}")
+print(f"Server name: {server.name}")
+print(f"Toolkits: {server.toolkits}")
```
</CodeGroupItem>
<CodeGroupItem title="TypeScript">
@@ -214,6 +214,13 @@ instance = server.generate("[email protected]")
print(f"URL: {instance['url']}")
print(f"Tools: {instance['allowed_tools']}")
+
+# Chat-based authentication is enabled by default
+# Set manually_manage_connections=True to disable it:
+instance_manual = server.generate(
+ manually_manage_connections=True
+)
```
</CodeGroupItem>
<CodeGroupItem title="TypeScript">
@@ -230,10 +237,21 @@ const urls2 = await server.getServer({
});
console.log("URL:", urls);
+
+// Note: URLs include include_composio_helper_actions=true when
+// isChatAuth is enabled, allowing agents to guide authentication
```
</CodeGroupItem>
</CodeGroup>
+<Note>
+**Chat-based authentication:**
+- **TypeScript**: Set `isChatAuth: true` during server creation to enable
+- **Python**: Enabled by default (set `manually_manage_connections=False` or omit it)
+
+When enabled, the agent can authenticate users dynamically during conversation if they're missing required connections.
+</Note>
+
## Best practices
- **Use descriptive names** - Makes servers easy to find
@@ -241,41 +259,3 @@ console.log("URL:", urls);
- **Reuse servers** - Don't create duplicates for same configuration
- **Store server IDs** - Keep track of created server IDs
-## API reference
-
-### Python methods
-
-| Method | Description |
-|--------|-------------|
-| `create()` | Create new server |
-| `list()` | List servers |
-| `get()` | Get server by ID |
-| `update()` | Update server |
-| `delete()` | Delete server |
-| `generate()` | Generate user URL |
-
-### TypeScript methods
-
-| Method | Description |
-|--------|-------------|
-| `create()` | Create new server |
-| `list()` | List servers |
-| `get()` | Get server by ID |
-| `getByName()` | Find server by name |
-| `update()` | Update server |
-| `delete()` | Delete server |
-| `getServer()` | Generate user URL |
-
-## Next steps
-
-<Cards>
- <Card title="Authentication" href="/docs/mcp-authentication" icon="lock">
- Handle user authentication
- </Card>
- <Card title="Providers" href="/docs/mcp-providers" icon="code">
- Framework integrations
- </Card>
- <Card title="Troubleshooting" href="/docs/troubleshooting/mcp" icon="wrench">
- Common issues
- </Card>
-</Cards>
\ No newline at end of file