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.

fix

Utkarsh Dixitf2caa0fbe00c
diff --git a/fern/pages/src/mcp/developers.mdx b/fern/pages/src/mcp/developers.mdx
index 28d0d85d6..f738f06be 100644
--- a/fern/pages/src/mcp/developers.mdx
+++ b/fern/pages/src/mcp/developers.mdx
@@ -11,6 +11,10 @@ hide-nav-links: true
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.
+<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">
@@ -32,9 +36,9 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
});
// Create an MCP server with the new API structure
- const mcpConfig = await composio.mcp.create({
- name: "Gmail MCP Server",
- serverConfig: [
+ const mcpConfig = await composio.mcp.create(
+ "Gmail MCP Server",
+ [
{
authConfigId: "ac_auth_12", // Your auth config ID
allowedTools: [
@@ -44,10 +48,10 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
]
}
],
- options: {
+ {
isChatAuth: true // Enable chat-based authentication
}
- });
+ );
console.log(`✅ MCP server created: ${mcpConfig.id}`);
console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
@@ -57,24 +61,21 @@ You can manage these servers via our [Dashboard](https://app.composio.dev), or u
**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
- }
- });
+ const serverUrls = await composio.mcp.getServer(
+ mcpConfig.id,
+ );
console.log("Server URLs:", serverUrls);
```
- **Using the convenience method (from create response):**
+ **Using the server ID (from create response):**
```typescript
- // Use the convenience method on the created server
- const serverUrls = await mcpConfig.getServer({
- userId: "[email protected]"
- });
+ // 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">
@@ -102,10 +103,10 @@ Before using an MCP server, you can check if a user has the necessary connected
```typescript
// Check if a user has connected accounts for all required toolkits
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
- id: mcpConfig.id,
- userId: "[email protected]"
-});
+const connectionStatus = await composio.mcp.getUserConnectionStatus(
+ mcpConfig.id
+);
console.log("Overall connection status:", connectionStatus.connected);
console.log("Individual toolkit status:", connectionStatus.connectedToolkits);
@@ -169,17 +170,17 @@ Authenticate users upfront via the Composio SDK/API before they use the MCP serv
```typescript
// Check what authentication is needed
-const authParams = await composio.mcp.getConnectionParams({
- id: mcpConfig.id,
- toolkit: "gmail"
-});
+const authParams = await composio.mcp.getConnectionParams(
+ mcpConfig.id,
+ "gmail"
+);
// Initiate authentication for a user
-const authRequest = await composio.mcp.authorize({
- id: mcpConfig.id,
- userId: "[email protected]",
- toolkit: "gmail"
-});
+const authRequest = await composio.mcp.authorize(
+ mcpConfig.id,
+ "gmail"
+);
if (authRequest.redirectUrl) {
console.log("Please complete authentication:", authRequest.redirectUrl);
@@ -191,10 +192,10 @@ if (authRequest.redirectUrl) {
Let the agent authenticate users on-demand by including helper actions:
```typescript
-const serverUrls = await composio.mcp.getServer({
- id: mcpConfig.id,
- userId: "[email protected]"
-});
+const serverUrls = await composio.mcp.getServer(
+ mcpConfig.id,
+);
// The server URLs will include helper actions that guide users through authentication
```
@@ -209,7 +210,7 @@ Pre-authentication is recommended for production applications as it provides bet
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.
+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.
diff --git a/fern/pages/src/mcp/introduction.mdx b/fern/pages/src/mcp/introduction.mdx
index 8e82a58f0..5695df01a 100644
--- a/fern/pages/src/mcp/introduction.mdx
+++ b/fern/pages/src/mcp/introduction.mdx
@@ -10,6 +10,10 @@ hide-nav-links: true
[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
@@ -37,23 +41,24 @@ const composio = new Composio({
});
// Create an MCP server
-const mcpServer = await composio.mcp.create({
- name: "My Gmail Server",
- serverConfig: [
+const mcpServer = await composio.mcp.create(
+ "My Gmail Server",
+ [
{
authConfigId: "ac_your_auth_config_id",
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
}
],
- options: {
+ {
isChatAuth: true
}
-});
+);
// Get server URLs for a user
-const serverUrls = await mcpServer.getServer({
- userId: "[email protected]"
-});
+const serverUrls = await composio.mcp.getServer(
+ mcpServer.id,
+);
console.log("MCP Server URLs:", serverUrls);
```
@@ -62,10 +67,10 @@ console.log("MCP Server URLs:", serverUrls);
### Creating MCP Servers
-The `create` method uses named object arguments for clear, readable configuration:
+The `create` method uses positional parameters for better performance:
```typescript
-const mcpServer = await composio.mcp.create({
+const mcpServer = await composio.mcp.create(
name: string, // Unique server name
serverConfig: Array<{ // Auth configurations
authConfigId: string, // Your auth config ID
@@ -74,15 +79,15 @@ const mcpServer = await composio.mcp.create({
options: {
isChatAuth?: boolean // Enable chat-based auth (default: false)
}
-});
+);
```
**Complete Example:**
```typescript
-const mcpServer = await composio.mcp.create({
- name: "Multi-Service Productivity Server",
- serverConfig: [
+const mcpServer = await composio.mcp.create(
+ "Multi-Service Productivity Server",
+ [
{
authConfigId: "ac_gmail_config",
allowedTools: [
@@ -99,10 +104,10 @@ const mcpServer = await composio.mcp.create({
]
}
],
- options: {
+ {
isChatAuth: true
}
-});
+);
console.log(`✅ Server created: ${mcpServer.id}`);
console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
@@ -113,39 +118,26 @@ console.log(`📦 Toolkits: ${mcpServer.toolkits.join(", ")}`);
The `getServer` method provides URLs for MCP clients to connect:
```typescript
-const serverUrls = await composio.mcp.getServer({
+const serverUrls = await composio.mcp.getServer(
id: string, // Server ID
- userId: string, // User identifier
- options?: {
- limitTools?: string[], // Subset of tools to include
- isChatAuth?: boolean // Override chat auth setting
- }
-});
+ userId: string // User identifier
+);
```
**Examples:**
```typescript
// Basic usage
-const basicUrls = await composio.mcp.getServer({
- id: "mcp_server_id",
- userId: "[email protected]"
-});
-
-// With tool limitations
-const limitedUrls = await composio.mcp.getServer({
- id: "mcp_server_id",
- userId: "[email protected]",
- options: {
- limitTools: ["GMAIL_FETCH_EMAILS"], // Only allow email fetching
- isChatAuth: false
- }
-});
+const basicUrls = await composio.mcp.getServer(
+ "mcp_server_id",
+);
-// Using convenience method (from create response)
-const convenientUrls = await mcpServer.getServer({
- userId: "[email protected]"
-});
+// Using server ID from create response
+const serverUrls = await composio.mcp.getServer(
+ mcpServer.id,
+);
```
### Checking User Connection Status
@@ -153,10 +145,10 @@ const convenientUrls = await mcpServer.getServer({
Before using an MCP server, check if users have the required connected accounts:
```typescript
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
- id: string, // Server ID
- userId: string // User identifier
-});
+const connectionStatus = await composio.mcp.getUserConnectionStatus(
+ userId: string, // User identifier
+ id: string // Server ID
+);
// Returns: McpUserConnectionStatus
{
@@ -176,10 +168,10 @@ const connectionStatus = await composio.mcp.getUserConnectionStatus({
**Complete Example:**
```typescript
-const status = await composio.mcp.getUserConnectionStatus({
- id: mcpServer.id,
- userId: "[email protected]"
-});
+const status = await composio.mcp.getUserConnectionStatus(
+ mcpServer.id
+);
console.log(`Overall status: ${status.connected ? "✅ Ready" : "❌ Needs auth"}`);
@@ -190,17 +182,17 @@ if (!status.connected) {
console.log(`❌ ${toolkit} requires authentication`);
// Get authentication parameters
- const authParams = await composio.mcp.getConnectionParams({
- id: mcpServer.id,
+ const authParams = await composio.mcp.getConnectionParams(
+ mcpServer.id,
toolkit
- });
+ );
// Initiate authentication
- const authRequest = await composio.mcp.authorize({
- id: mcpServer.id,
- userId: "[email protected]",
+ const authRequest = await composio.mcp.authorize(
+ mcpServer.id,
toolkit
- });
+ );
if (authRequest.redirectUrl) {
console.log(`🔗 Authenticate here: ${authRequest.redirectUrl}`);
@@ -274,19 +266,19 @@ Authenticate users before they use the MCP server:
```typescript
// 1. Check what's needed
-const authParams = await composio.mcp.getConnectionParams({
- id: mcpServer.id,
- toolkit: "gmail"
-});
+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({
- id: mcpServer.id,
- userId: "[email protected]",
- toolkit: "gmail"
-});
+const authRequest = await composio.mcp.authorize(
+ mcpServer.id,
+ "gmail"
+);
// 3. Direct user to authentication URL
if (authRequest.redirectUrl) {
@@ -294,10 +286,10 @@ if (authRequest.redirectUrl) {
}
// 4. Verify connection after user completes auth
-const finalStatus = await composio.mcp.getUserConnectionStatus({
- id: mcpServer.id,
- userId: "[email protected]"
-});
+const finalStatus = await composio.mcp.getUserConnectionStatus(
+ mcpServer.id
+);
if (finalStatus.connected) {
console.log("✅ All toolkits connected, ready to use!");
@@ -309,13 +301,10 @@ if (finalStatus.connected) {
Let the agent handle authentication on-demand:
```typescript
-const serverUrls = await composio.mcp.getServer({
- id: mcpServer.id,
- userId: "[email protected]",
- options: {
- isChatAuth: true // Include helper actions for authentication
- }
-});
+const serverUrls = await composio.mcp.getServer(
+ mcpServer.id,
+);
// The agent can now guide users through authentication as needed
```
@@ -338,9 +327,9 @@ async function setupGmailMCP(userId: string) {
} catch (error) {
// 2. Create new server if it doesn't exist
console.log("📦 Creating new Gmail server...");
- gmailServer = await composio.mcp.create({
- name: "Production Gmail Server",
- serverConfig: [
+ gmailServer = await composio.mcp.create(
+ "Production Gmail Server",
+ [
{
authConfigId: process.env.GMAIL_AUTH_CONFIG_ID!,
allowedTools: [
@@ -351,27 +340,27 @@ async function setupGmailMCP(userId: string) {
]
}
],
- options: {
+ {
isChatAuth: true
}
- });
+ );
}
// 3. Check user connection status
- const connectionStatus = await composio.mcp.getUserConnectionStatus({
- id: gmailServer.id,
- userId
- });
+ 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({
- id: gmailServer.id,
+ const authRequest = await composio.mcp.authorize(
userId,
- toolkit: "gmail"
- });
+ gmailServer.id,
+ "gmail"
+ );
return {
server: gmailServer,
@@ -381,12 +370,10 @@ async function setupGmailMCP(userId: string) {
}
// 5. Generate server URLs for MCP client
- const serverUrls = await gmailServer.getServer({
- userId,
- options: {
- limitTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
- }
- });
+ const serverUrls = await composio.mcp.getServer(
+ gmailServer.id,
+ userId
+ );
return {
server: gmailServer,
@@ -409,18 +396,18 @@ if (result.needsAuth) {
```typescript
try {
- const mcpServer = await composio.mcp.create({
- name: "Test Server",
- serverConfig: [
+ const mcpServer = await composio.mcp.create(
+ "Test Server",
+ [
{
authConfigId: "invalid_config",
allowedTools: ["INVALID_TOOL"]
}
],
- options: {
+ {
isChatAuth: true
}
- });
+ );
} catch (error) {
if (error instanceof ValidationError) {
console.error("Configuration error:", error.message);
@@ -439,7 +426,7 @@ try {
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. **Use the convenience methods** - The `getServer` method on create responses simplifies workflows
+7. **Store server IDs** - Keep track of server IDs from create responses for generating URLs
## Next Steps