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.

Merge branch 'next' into 07-05-feat_update_mcp_flow_in_ts_sdk

Utkarsh Dixit44c689e3faf6
diff --cc fern/pages/src/mcp/developers.mdx
index e16942312,f656a1ba7..8c3202d3c
--- a/fern/pages/src/mcp/developers.mdx
+++ b/fern/pages/src/mcp/developers.mdx
@@@ -9,70 -9,58 +9,70 @@@ hide-nav-links: tru
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://app.composio.dev), or use the [SDK/API](/api-reference/mcp) for greater control and flexibility.
- ## Creating MCP Servers and Onboarding End users
+ ## Creating MCP Servers and Onboarding End Users
<Steps>
<Step title="Configure Authentication">
- - **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.
+ - **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:**
- - [Integration setup guide](/docs/custom-auth-configs) - Detailed walkthrough of configuring app integrations
- - [Custom auth configs](/docs/custom-auth-configs) - Instructions for customizing the authentication
+ - 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">
- Making the following request:
- ```bash
- curl -X POST https://backend.composio.dev/api/v3/mcp/servers \
- -H "x-api-key: <YOUR_API_KEY>" \
- -H "Content-Type: application/json" \
- -d '{
- "name": "Gmail MCP Server",
- "allowed_tools": [
- "GMAIL_FETCH_EMAIL",
- "GMAIL_CREATE_EMAIL_DRAFT",
- ],
- "auth_config_ids": ["ac_auth_12"]
- }'
- ```
- The response looks like:
+
+ ```typescript
+ import { Composio } from '@composio/core';
- ```json
- {
- "id": "5bc757cc-7a8e-431c-8616-7f57cbed2423",
- "name": "Gmail MCP Server",
- "auth_config_ids": ["ac_auth_12"],
- "allowed_tools": [
- "GMAIL_FETCH_EMAIL",
- "GMAIL_CREATE_EMAIL_DRAFT",
+ 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({
+ name: "Gmail MCP Server",
+ serverConfig: [
+ {
+ authConfigId: "ac_auth_12", // Your auth config ID
+ allowedTools: [
+ "GMAIL_FETCH_EMAILS",
+ "GMAIL_CREATE_EMAIL_DRAFT",
+ "GMAIL_SEND_EMAIL"
+ ]
+ }
],
- "mcp_url": "https://mcp.composio.dev/composio/server/5bc757cc-7a8z-431c-8616-7f57cbed2421?transport=sse",
- "commands": {
- "cursor": "npx @composio/mcp@latest setup \"<mcp_url>\" --client cursor",
- "claude": "npx @composio/mcp@latest setup \"<mcp_url>\" --client claude",
- "windsurf": "npx @composio/mcp@latest setup \"<mcp_url>\" --client windsurf"
- },
- "created_at": "2025-05-18T22:15:25.926Z",
- "updated_at": "2025-05-18T22:15:25.926Z",
- "managed_auth_via_composio": false
- }
+ options: {
+ 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({
+ id: mcpConfig.id,
+ userId: "[email protected]",
+ options: {
+ limitTools: ["GMAIL_FETCH_EMAILS"], // Optional: limit to specific tools
+ isChatAuth: true
+ }
+ });
+
+ console.log("Server URLs:", serverUrls);
+ ```
+
+ **Using the convenience method (from create response):**
+ ```typescript
+ // Use the convenience method on the created server
+ const serverUrls = await mcpConfig.getServer({
+ userId: "[email protected]"
+ });
```
</Step>
<Step title="Client applications connect to the server">
@@@ -92,124 -76,14 +92,131 @@@
</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({
+ id: mcpConfig.id,
+ userId: "[email protected]"
+});
+
+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"]
+ }
+ ],
+ { useComposioManagedAuth: 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({
+ id: mcpConfig.id,
+ toolkit: "gmail"
+});
+
+// Initiate authentication for a user
+const authRequest = await composio.mcp.authorize({
+ id: mcpConfig.id,
+ userId: "[email protected]",
+ toolkit: "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({
+ id: mcpConfig.id,
+ userId: "[email protected]"
+});
+
+// The server URLs will include helper actions that guide users through authentication
+```
+
<Tip>
- SSE support will be deprecated soon. To use the latest protocol, if you are using `/sse` or the `transport=sse` query parameter, change your endpoint to use `/mcp` and remove the transport query parameter.
+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 convenience methods** - The `getServer` method on create responses simplifies URL generation
+
+<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 auth on demand.
+