Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Merge branch 'next' into 07-05-feat_update_mcp_flow_in_ts_sdk
Utkarsh Dixit44c689e3faf6
diff --cc fern/pages/src/mcp/developers.mdxindex 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: truComposio 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.+