Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 19:30 UTC
mcp docs revamp
Sushmithamallesh committed
Oct 12, 2025 at 19:20 UTC
15ff0d35a11353043bea46d637b363f78c2d40c2
19 files changed
+1414
-445
fern/assets/images/mcp_server_client.png
Binary files a/fern/assets/images/mcp_server_client.png and /dev/null differ
fern/assets/videos/mcp-claude-oauth.mp4
Binary files a/fern/assets/videos/mcp-claude-oauth.mp4 and /dev/null differ
fern/assets/videos/mcp-claude.mp4
Binary files a/fern/assets/videos/mcp-claude.mp4 and /dev/null differ
fern/assets/videos/mcp-cursor-oauth.mp4
Binary files a/fern/assets/videos/mcp-cursor-oauth.mp4 and /dev/null differ
fern/assets/videos/mcp-cursor.mp4
Binary files a/fern/assets/videos/mcp-cursor.mp4 and /dev/null differ
fern/docs.yml
+21
-9
@@ -159,18 +159,30 @@ navigation:
159
icon: server
160
skip-slug: true
161
contents:
162
- - page: Overview
163
- path: pages/dist/mcp/overview.mdx
164
- slug: mcp-overview
165
- - page: Developers
166
- path: pages/dist/mcp/developers.mdx
167
- slug: mcp-developers
168
- - page: Partner Program
169
- path: pages/dist/mcp/partner-api.mdx
170
- slug: mcp-partner-api
162
+ - page: Quickstart
163
+ path: pages/dist/mcp/quickstart.mdx
164
+ slug: mcp-quickstart
165
+ - page: Authentication
166
+ path: pages/dist/mcp/authentication.mdx
167
+ slug: mcp-authentication
168
+ - page: Server management
169
+ path: pages/dist/mcp/server-management.mdx
170
+ slug: mcp-server-management
171
- page: Providers
172
path: pages/dist/mcp/providers.mdx
173
slug: mcp-providers
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
186
- section: Tool Router (Beta)
187
icon: tools
188
skip-slug: true
fern/pages/src/mcp/authentication.mdx
new
+169
@@ -0,0 +1,169 @@
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/implementation.mdx
new
+192
@@ -0,0 +1,192 @@
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/overview.mdx
deleted
-130
@@ -1,130 +0,0 @@
1
----
2
-title: Composio MCP Servers
3
-subtitle: "Transform any app into an MCP server with powerful tools and seamless authentication"
4
-image: "https://og.composio.dev/api/og?title=Composio%20MCP%20Servers" # image for socials
5
-keywords: "MCP, Model Context Protocol, AI tools, authentication, SDK"
6
-hide-nav-links: true
7
----
8
-
9
-[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open protocol that standardizes how LLM-powered applications provide _tools_ and relevant context to the underlying models.
10
-
11
-The protocol follows a client-server model, where the MCP server provides the tools and context to the MCP client.
12
-
13
-**Composio MCP Servers** make all [Composio tools](/toolkits/introduction) available through this standardized protocol, enabling seamless integration with any MCP-compatible client.
14
-
15
-## ✨ Key Features
16
-
17
-Our MCP SDK features an intuitive, powerful, and developer-friendly API:
18
-
19
-- **⚡ Streamlined Authentication** - Simplified user auth flows with better error handling
20
-- **📊 Real-time Connection Monitoring** - Check user authentication status before using servers
21
-- **🛠 Enhanced Tool Management** - Fine-grained control over which tools are available
22
-- **Tool Limiting** - Restrict which tools are available per user or context
23
-- **TypeScript Support** - Full type safety and autocomplete, python support to come soon.
24
-
25
-
26
-## 🚀 Getting Started
27
-
28
-Choose your path based on your role:
29
-
30
-### For End Users
31
-If you are an individual looking to use composio mcp servers directly for yourself, this is all you have todo.
32
-
33
-1. Visit [mcp.composio.dev](https://mcp.composio.dev)
34
-2. Click on any app that you want the MCP server for.
35
-3. Use with Claude Desktop, Cursor, or any MCP client
36
-
37
-### For Developers
38
-If you are looking to build on top of composio MCP servers, have granual control over MCP servers and manage it seperately for each of your users - you can simply follow the below guide.
39
-
40
-<Steps>
41
- <Step title="Install the SDK">
42
- ```bash
43
- npm install @composio/core
44
- ```
45
- </Step>
46
- <Step title="Create your first server">
47
- ```typescript
48
- import { Composio } from '@composio/core';
49
-
50
- const composio = new Composio({
51
- apiKey: process.env.COMPOSIO_API_KEY,
52
- });
53
-
54
- const mcpServer = await composio.mcp.create({
55
- name: "personal-gmail-server",
56
- serverConfig: [
57
- {
58
- authConfigId: "your_auth_config_id",
59
- allowedTools: ["GMAIL_FETCH_EMAILS"]
60
- }
61
- ],
62
- options: {
63
- isChatAuth: true
64
- }
65
- });
66
- ```
67
- </Step>
68
- <Step title="Generate user-specific URLs">
69
- ```typescript
70
- // Check if user is authenticated
71
- const status = await composio.mcp.getUserConnectionStatus({
72
- id: mcpServer.id,
73
- userId: "user@example.com"
74
- });
75
-
76
- if (status.connected) {
77
- const urls = await mcpServer.getServer({
78
- userId: "user@example.com"
79
- });
80
- console.log("Ready to use:", urls);
81
- }
82
- ```
83
- </Step>
84
-</Steps>
85
-
86
-## 🏗 Architecture Overview
87
-
88
-```mermaid
89
-graph TB
90
- A[Your Application] --> B[Composio SDK]
91
- B --> C[MCP Server]
92
- C --> D[Tools & Authentication]
93
- E[MCP Clients] --> C
94
- E --> F[Claude Desktop]
95
- E --> G[Cursor IDE]
96
- E --> H[Custom Clients]
97
-
98
- style C fill:#4762DA,color:#fff
99
- style B fill:#9EB6FF,color:#000
100
-```
101
-
102
-1. **Your Application** creates and manages MCP servers via the Composio SDK
103
-2. **MCP Servers** expose your chosen tools with proper authentication
104
-3. **MCP Clients** (Claude, Cursor, etc.) connect to servers and use tools
105
-4. **Users** interact with tools through their preferred MCP client
106
-
107
-## 📚 Documentation Structure
108
-
109
-<Cards>
110
- <Card title="Developer Guide" href="/docs/mcp-developers" icon="code">
111
- Step-by-step guide to creating and managing MCP servers
112
- </Card>
113
- <Card title="Provider Examples" href="/docs/mcp-providers" icon="code">
114
- Framework-specific implementations for Anthropic, OpenAI, Mastra, and more
115
- </Card>
116
- <Card title="Partner Program" href="/docs/mcp-partner-api" icon="handshake">
117
- Enterprise integration options and white-label solutions
118
- </Card>
119
-</Cards>
120
-
121
-## 🔗 Quick Links
122
-
123
-- **[Tool Catalog](/toolkits/introduction)** - Browse 1000+ available tools
124
-- **[Dashboard](https://platform.composio.dev)** - Manage servers and auth configs
125
-- **[API Reference](/api-reference/mcp)** - Complete endpoint documentation
126
-
127
-<Tip>
128
-Need help getting started? Reach out on [Discord](https://discord.com/invite/composio) or [email](mailto:support@composio.dev) - our team is here to help!
129
-</Tip>
130
-
fern/pages/src/mcp/providers-dummy.mdx
new
+360
@@ -0,0 +1,360 @@
1
+---
2
+
3
+title: MCP Providers
4
+subtitle: "Guide to Using Composio MCP Servers with Your Agent Framework"
5
+image: "https://og.composio.dev/api/og?title=MCP%20Providers" # image for socials
6
+keywords: ""
7
+hide-nav-links: true
8
+
9
+---
10
+
11
+<Warning title="Only available for TypeScript SDK" icon="warning">At this time, MCP providers using the Composio SDK are only supported in the TypeScript SDK. Support for the Python SDK is coming soon.</Warning>
12
+
13
+Integrating external tools into agent frameworks can be a complex and time-consuming process. Composio MCP (Model Context Protocol) servers simplify this workflow, enabling you to connect your framework to a wide array of tools and services with minimal configuration.
14
+
15
+This guide introduces the primary MCP providers, each optimized for a popular agent framework. With these providers, you can focus on developing intelligent agent logic while Composio handles the integration details.
16
+
17
+---
18
+
19
+## 1. Anthropic Provider
20
+
21
+The **Anthropic Provider** is purpose-built for use with the Anthropic Claude API. It supports Model Context Protocol (MCP) tools via a lightweight client that exposes a `getServer` method for retrieving the appropriate Composio MCP Server URL, preconfigured for your user. This provider ensures seamless compatibility between Composio tools and Anthropic's function calling APIs.
22
+
23
+<CodeGroup>
24
+ <CodeGroupItem title="TypeScript">
25
+
26
+```typescript
27
+import { Composio } from '@composio/core';
28
+import { AnthropicProvider } from '@composio/anthropic';
29
+import Anthropic from '@anthropic-ai/sdk';
30
+
31
+// Initialize Anthropic client
32
+const anthropic = new Anthropic({
33
+ apiKey: process.env.ANTHROPIC_API_KEY,
34
+});
35
+
36
+// Initialize Composio with the Anthropic provider
37
+const composio = new Composio({
38
+ apiKey: process.env.COMPOSIO_API_KEY,
39
+ provider: new AnthropicProvider({ cacheTools: true }),
40
+});
41
+
42
+// Create MCP server with the new API structure
43
+const mcpConfig = await composio.mcp.create({
44
+ name: "Gmail Readonly Server",
45
+ serverConfig: [
46
+ {
47
+ authConfigId: "<auth_config_id>", // Your auth config ID
48
+ allowedTools: ["GMAIL_FETCH_EMAILS"]
49
+ }
50
+ ],
51
+ options: {
52
+ isChatAuth: true
53
+ }
54
+});
55
+
56
+console.log(`✅ MCP server created: ${mcpConfig.id}`);
57
+console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
58
+
59
+// Check user connection status before proceeding
60
+const connectionStatus = await composio.mcp.getUserConnectionStatus({
61
+ id: mcpConfig.id,
62
+ userId: "utkarsh-dixit"
63
+});
64
+
65
+if (!connectionStatus.connected) {
66
+ console.log("❌ User needs to connect required accounts");
67
+ // Handle authentication as needed
68
+ return;
69
+}
70
+
71
+// Retrieve server instances for connected accounts
72
+const serverInstances = await mcpConfig.getServer({
73
+ userId: "utkarsh-dixit",
74
+});
75
+
76
+console.log("Server instances for connected accounts:", serverInstances);
77
+
78
+console.log("\n=== Fetching and Summarizing Recent Emails ===");
79
+
80
+const stream = await anthropic.beta.messages.stream(
81
+{
82
+ model: "claude-3-5-sonnet-20241022",
83
+ max_tokens: 1000,
84
+ mcp_servers: serverInstances,
85
+ messages: [
86
+ {
87
+ role: "user",
88
+ content:
89
+ "Please fetch the latest 10 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email. Format the response in a clear, organized way.",
90
+ },
91
+ ],
92
+},
93
+{
94
+ headers: {
95
+ "anthropic-beta": "mcp-client-2025-04-04",
96
+ },
97
+}
98
+);
99
+
100
+console.log("\n📬 Email Summary:");
101
+for await (const event of stream) {
102
+ if (
103
+ event.type === "content_block_delta" &&
104
+ event.delta.type === "text_delta"
105
+ ) {
106
+ process.stdout.write(event.delta.text);
107
+ }
108
+}
109
+process.stdout.write("\n");
110
+
111
+console.log("\n✅ Anthropic MCP example completed successfully!");
112
+```
113
+
114
+ </CodeGroupItem>
115
+</CodeGroup>
116
+
117
+---
118
+
119
+## 2. Mastra Provider
120
+
121
+The **Mastra Provider** is tailored for the [Mastra](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools) TypeScript-native agent framework. This client provides a getServer method to obtain the Composio MCP Server URL, configured for your user.
122
+
123
+<CodeGroup>
124
+ <CodeGroupItem title="Mastra">
125
+
126
+```typescript
127
+import { MastraProvider } from '@composio/mastra';
128
+import { Composio } from '@composio/core';
129
+import { MCPClient } from '@mastra/mcp';
130
+import { Agent } from '@mastra/core/agent';
131
+import { openai } from '@ai-sdk/openai';
132
+import type { MastraMCPServerDefinition } from '@mastra/mcp';
133
+
134
+const composio = new Composio({
135
+ apiKey: process.env.COMPOSIO_API_KEY,
136
+ provider: new MastraProvider(),
137
+});
138
+
139
+// Create an MCP server with the Gmail toolkit using new API structure
140
+const mcpConfig = await composio.mcp.create({
141
+ name: "Gmail Readonly Server",
142
+ serverConfig: [
143
+ {
144
+ authConfigId: "<auth_config_id>", // Your auth config ID
145
+ allowedTools: ["GMAIL_FETCH_EMAILS"]
146
+ }
147
+ ],
148
+ options: {
149
+ isChatAuth: true
150
+ }
151
+});
152
+
153
+console.log(`✅ MCP server created: ${mcpConfig.id}`);
154
+console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
155
+
156
+// Check user connection status
157
+const connectionStatus = await composio.mcp.getUserConnectionStatus({
158
+ id: mcpConfig.id,
159
+ userId: "utkarsh-dixit"
160
+});
161
+
162
+console.log("Connection status:", connectionStatus.connected);
163
+
164
+if (!connectionStatus.connected) {
165
+ console.log("❌ User needs to authenticate with required services");
166
+ // Handle authentication flow
167
+ Object.entries(connectionStatus.connectedToolkits).forEach(([toolkit, status]) => {
168
+ if (!status.connected) {
169
+ console.log(`Please connect ${toolkit}`);
170
+ }
171
+ });
172
+ return;
173
+}
174
+
175
+// Retrieve server instance for connected accounts
176
+const serverInstance = await mcpConfig.getServer({
177
+ userId: "utkarsh-dixit"
178
+});
179
+
180
+console.log("Server instance for connected accounts:", serverInstance);
181
+
182
+// Initialize MCPClient with the server URLs
183
+const mcpClient = new MCPClient({
184
+servers: Object.fromEntries(
185
+ Object.entries(serverInstance as Record<string, { url: string }>).map(
186
+ ([key, value]) => [key, { url: new URL(value.url) }]
187
+ )
188
+) satisfies Record<string, MastraMCPServerDefinition>,
189
+});
190
+
191
+// List available tools from MCP client
192
+const tools = await mcpClient.getTools();
193
+console.log(`🔧 Available tools: ${Object.keys(tools).join(", ")}`);
194
+
195
+// Create a Gmail agent using the MCP tools
196
+const gmailAgent = new Agent({
197
+ name: "Gmail Assistant",
198
+ instructions: `
199
+ You are a helpful Gmail assistant that fetches and summarizes emails.
200
+ When fetching emails, provide a clear summary of the results including sender, subject, and date.
201
+ Be concise and provide actionable information based on the email content.
202
+ `,
203
+ model: openai("gpt-4o-mini"),
204
+ tools,
205
+});
206
+
207
+// Fetch and summarize recent emails
208
+console.log("\n=== Fetching and Summarizing Recent Emails ===");
209
+const emailResponse = await gmailAgent.generate(
210
+"Fetch the latest 10 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email"
211
+);
212
+console.log("\n📬 Email Summary:");
213
+console.log(emailResponse.text);
214
+
215
+console.log("\n✅ Gmail MCP example completed successfully!");
216
+```
217
+
218
+ </CodeGroupItem>
219
+</CodeGroup>
220
+
221
+---
222
+
223
+## 3. OpenAI SDK Provider
224
+
225
+The **OpenAI SDK Provider** is designed for use with the OpenAI SDK and supports MCP tools through a streamlined client. This client provides a `getServer` method to obtain the Composio MCP Server URL, configured for your user.
226
+
227
+<CodeGroup>
228
+ <CodeGroupItem title="TypeScript">
229
+
230
+```typescript
231
+import { Composio } from '@composio/core';
232
+import { OpenAIProvider } from '@composio/openai';
233
+import OpenAI from 'openai';
234
+
235
+const openai = new OpenAI({
236
+ apiKey: process.env.OPENAI_API_KEY,
237
+});
238
+
239
+const composio = new Composio({
240
+ apiKey: process.env.COMPOSIO_API_KEY,
241
+ provider: new OpenAIProvider(),
242
+});
243
+
244
+// Create MCP server with new API structure
245
+const mcpConfig = await composio.mcp.create({
246
+ name: "Gmail Readonly Server",
247
+ serverConfig: [
248
+ {
249
+ authConfigId: "<auth_config_id>", // Your auth config ID
250
+ allowedTools: ["GMAIL_FETCH_EMAILS"]
251
+ }
252
+ ],
253
+ options: {
254
+ isChatAuth: true
255
+ }
256
+});
257
+
258
+console.log(`✅ MCP server created: ${mcpConfig.id}`);
259
+console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
260
+
261
+// Check if user has necessary connections
262
+const connectionStatus = await composio.mcp.getUserConnectionStatus({
263
+ id: mcpConfig.id,
264
+ userId: "utkarsh-dixit"
265
+});
266
+
267
+if (!connectionStatus.connected) {
268
+ console.log("❌ User authentication required");
269
+ // Handle missing connections
270
+ for (const [toolkit, status] of Object.entries(connectionStatus.connectedToolkits)) {
271
+ if (!status.connected) {
272
+ const authParams = await composio.mcp.getConnectionParams({
273
+ id: mcpConfig.id,
274
+ toolkit
275
+ });
276
+
277
+ const authRequest = await composio.mcp.authorize({
278
+ id: mcpConfig.id,
279
+ userId: "utkarsh-dixit",
280
+ toolkit
281
+ });
282
+
283
+ if (authRequest.redirectUrl) {
284
+ console.log(`Please authenticate with ${toolkit}: ${authRequest.redirectUrl}`);
285
+ }
286
+ }
287
+ }
288
+ return;
289
+}
290
+
291
+// Retrieve server URLs for connected accounts
292
+const serverUrls = await mcpConfig.getServer({
293
+ userId: "utkarsh-dixit",
294
+ options: {
295
+ limitTools: ["GMAIL_FETCH_EMAILS"] // Optional: limit to specific tools
296
+ }
297
+});
298
+
299
+console.log("Server URLs for your MCP server:", serverUrls);
300
+
301
+// Use with OpenAI (example with hypothetical OpenAI MCP integration)
302
+const completion = await openai.chat.completions.create({
303
+ model: "gpt-4o-mini",
304
+ messages: [
305
+ {
306
+ role: "user",
307
+ content: "I've connected to Gmail and I want to fetch the latest email from my inbox and summarize it"
308
+ }
309
+ ],
310
+ // Note: This is a hypothetical integration - actual OpenAI MCP support may differ
311
+ tools: serverUrls,
312
+});
313
+
314
+console.log("\n📬 Email Summary:");
315
+console.log(completion.choices[0].message.content);
316
+
317
+console.log("\n✅ OpenAI MCP example completed successfully!");
318
+console.log("\n💡 Note: The MCP server URLs can also be used to connect from other MCP-compatible clients.");
319
+console.log(`📍 Server ID for future reference: ${mcpConfig.id}`);
320
+```
321
+
322
+ </CodeGroupItem>
323
+</CodeGroup>
324
+
325
+---
326
+
327
+## Managing Existing Servers
328
+
329
+You can also work with previously created MCP servers:
330
+
331
+```typescript
332
+// Find a server by name
333
+const existingServer = await composio.mcp.getByName("Gmail Readonly Server");
334
+
335
+// Check connection status for the existing server
336
+const status = await composio.mcp.getUserConnectionStatus({
337
+ id: existingServer.id,
338
+ userId: "user123@example.com"
339
+});
340
+
341
+// Generate URLs for the existing server
342
+const urls = await composio.mcp.getServer({
343
+ id: existingServer.id,
344
+ userId: "user123@example.com",
345
+ options: {
346
+ isChatAuth: true
347
+ }
348
+});
349
+```
350
+
351
+## Best Practices for Providers
352
+
353
+1. **Always check connection status** before using MCP servers to ensure users are authenticated
354
+2. **Handle authentication gracefully** by providing clear instructions and redirect URLs
355
+3. **Use meaningful server names** to make management easier
356
+4. **Limit tools appropriately** to only what your application needs
357
+5. **Cache server configurations** when possible to reduce API calls
358
+6. **Monitor connection health** and provide re-authentication flows when needed
359
+
360
+By using Composio MCP Servers with these providers, you can quickly connect your agent framework to a wide range of external tools with minimal effort. This lets you streamline integration, reduce setup time, and focus more on building your AI agent.
\ No newline at end of file
fern/pages/src/mcp/providers.mdx
+135
-306
@@ -1,360 +1,189 @@
1
---
2
-
3
-title: MCP Providers
4
-subtitle: "Guide to Using Composio MCP Servers with Your Agent Framework"
5
-image: "https://og.composio.dev/api/og?title=MCP%20Providers" # image for socials
6
-keywords: ""
7
-hide-nav-links: true
8
-
2
+title: MCP providers
3
+subtitle: Using MCP servers with AI frameworks
4
---
5
11
-<Warning title="Only available for TypeScript SDK" icon="warning">At this time, MCP providers using the Composio SDK are only supported in the TypeScript SDK. Support for the Python SDK is coming soon.</Warning>
12
-
13
-Integrating external tools into agent frameworks can be a complex and time-consuming process. Composio MCP (Model Context Protocol) servers simplify this workflow, enabling you to connect your framework to a wide array of tools and services with minimal configuration.
14
-
15
-This guide introduces the primary MCP providers, each optimized for a popular agent framework. With these providers, you can focus on developing intelligent agent logic while Composio handles the integration details.
16
-
17
----
6
+Connect your MCP servers to popular AI frameworks and agents.
7
19
-## 1. Anthropic Provider
8
+## Anthropic (Claude)
9
21
-The **Anthropic Provider** is purpose-built for use with the Anthropic Claude API. It supports Model Context Protocol (MCP) tools via a lightweight client that exposes a `getServer` method for retrieving the appropriate Composio MCP Server URL, preconfigured for your user. This provider ensures seamless compatibility between Composio tools and Anthropic's function calling APIs.
10
+Use MCP servers with Claude API and Claude Desktop.
11
12
<CodeGroup>
24
- <CodeGroupItem title="TypeScript">
25
-
13
+<CodeGroupItem title="Python">
14
+```python
15
+# Python SDK - Anthropic integration coming soon
16
+# Use the standard MCP server URL generation for now
17
+instance = server.generate("user@example.com")
18
+print(f"MCP URL for Claude: {instance['url']}")
19
+```
20
+</CodeGroupItem>
21
+<CodeGroupItem title="TypeScript">
22
```typescript
27
-import { Composio } from '@composio/core';
28
-import { AnthropicProvider } from '@composio/anthropic';
23
import Anthropic from '@anthropic-ai/sdk';
24
31
-// Initialize Anthropic client
25
const anthropic = new Anthropic({
26
apiKey: process.env.ANTHROPIC_API_KEY,
27
});
28
36
-// Initialize Composio with the Anthropic provider
37
-const composio = new Composio({
38
- apiKey: process.env.COMPOSIO_API_KEY,
39
- provider: new AnthropicProvider({ cacheTools: true }),
40
-});
41
-
42
-// Create MCP server with the new API structure
43
-const mcpConfig = await composio.mcp.create({
44
- name: "Gmail Readonly Server",
45
- serverConfig: [
46
- {
47
- authConfigId: "<auth_config_id>", // Your auth config ID
48
- allowedTools: ["GMAIL_FETCH_EMAILS"]
49
- }
50
- ],
51
- options: {
52
- isChatAuth: true
53
- }
54
-});
55
-
56
-console.log(`✅ MCP server created: ${mcpConfig.id}`);
57
-console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
58
-
59
-// Check user connection status before proceeding
60
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
61
- id: mcpConfig.id,
62
- userId: "utkarsh-dixit"
63
-});
64
-
65
-if (!connectionStatus.connected) {
66
- console.log("❌ User needs to connect required accounts");
67
- // Handle authentication as needed
68
- return;
69
-}
70
-
71
-// Retrieve server instances for connected accounts
72
-const serverInstances = await mcpConfig.getServer({
73
- userId: "utkarsh-dixit",
74
-});
75
-
76
-console.log("Server instances for connected accounts:", serverInstances);
77
-
78
-console.log("\n=== Fetching and Summarizing Recent Emails ===");
79
-
80
-const stream = await anthropic.beta.messages.stream(
81
-{
82
- model: "claude-3-5-sonnet-20241022",
83
- max_tokens: 1000,
84
- mcp_servers: serverInstances,
85
- messages: [
86
- {
87
- role: "user",
88
- content:
89
- "Please fetch the latest 10 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email. Format the response in a clear, organized way.",
90
- },
91
- ],
92
-},
93
-{
94
- headers: {
95
- "anthropic-beta": "mcp-client-2025-04-04",
96
- },
97
-}
29
+// Get MCP server URL
30
+const serverUrls = await composio.mcp.getServer(
31
+ server.id,
32
+ "user@example.com"
33
);
34
100
-console.log("\n📬 Email Summary:");
101
-for await (const event of stream) {
102
- if (
103
- event.type === "content_block_delta" &&
104
- event.delta.type === "text_delta"
105
- ) {
106
- process.stdout.write(event.delta.text);
107
- }
108
-}
109
-process.stdout.write("\n");
110
-
111
-console.log("\n✅ Anthropic MCP example completed successfully!");
35
+// Use with Claude (when MCP support is available)
36
+const stream = await anthropic.beta.messages.stream({
37
+ model: "claude-3-5-sonnet-20241022",
38
+ mcp_servers: serverUrls,
39
+ messages: [{
40
+ role: "user",
41
+ content: "Fetch my latest emails"
42
+ }]
43
+});
44
```
113
-
114
- </CodeGroupItem>
45
+</CodeGroupItem>
46
</CodeGroup>
47
117
----
118
-
119
-## 2. Mastra Provider
48
+## OpenAI
49
121
-The **Mastra Provider** is tailored for the [Mastra](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools) TypeScript-native agent framework. This client provides a getServer method to obtain the Composio MCP Server URL, configured for your user.
50
+Integrate MCP servers with OpenAI GPT models.
51
52
<CodeGroup>
124
- <CodeGroupItem title="Mastra">
125
-
126
-```typescript
127
-import { MastraProvider } from '@composio/mastra';
128
-import { Composio } from '@composio/core';
129
-import { MCPClient } from '@mastra/mcp';
130
-import { Agent } from '@mastra/core/agent';
131
-import { openai } from '@ai-sdk/openai';
132
-import type { MastraMCPServerDefinition } from '@mastra/mcp';
133
-
134
-const composio = new Composio({
135
- apiKey: process.env.COMPOSIO_API_KEY,
136
- provider: new MastraProvider(),
137
-});
138
-
139
-// Create an MCP server with the Gmail toolkit using new API structure
140
-const mcpConfig = await composio.mcp.create({
141
- name: "Gmail Readonly Server",
142
- serverConfig: [
143
- {
144
- authConfigId: "<auth_config_id>", // Your auth config ID
145
- allowedTools: ["GMAIL_FETCH_EMAILS"]
146
- }
147
- ],
148
- options: {
149
- isChatAuth: true
150
- }
151
-});
152
-
153
-console.log(`✅ MCP server created: ${mcpConfig.id}`);
154
-console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
155
-
156
-// Check user connection status
157
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
158
- id: mcpConfig.id,
159
- userId: "utkarsh-dixit"
160
-});
161
-
162
-console.log("Connection status:", connectionStatus.connected);
163
-
164
-if (!connectionStatus.connected) {
165
- console.log("❌ User needs to authenticate with required services");
166
- // Handle authentication flow
167
- Object.entries(connectionStatus.connectedToolkits).forEach(([toolkit, status]) => {
168
- if (!status.connected) {
169
- console.log(`Please connect ${toolkit}`);
170
- }
171
- });
172
- return;
173
-}
53
+<CodeGroupItem title="Python">
54
+```python
55
+from openai import OpenAI
56
175
-// Retrieve server instance for connected accounts
176
-const serverInstance = await mcpConfig.getServer({
177
- userId: "utkarsh-dixit"
178
-});
57
+client = OpenAI()
58
180
-console.log("Server instance for connected accounts:", serverInstance);
59
+# Get MCP server instance
60
+instance = server.generate("user@example.com")
61
182
-// Initialize MCPClient with the server URLs
183
-const mcpClient = new MCPClient({
184
-servers: Object.fromEntries(
185
- Object.entries(serverInstance as Record<string, { url: string }>).map(
186
- ([key, value]) => [key, { url: new URL(value.url) }]
187
- )
188
-) satisfies Record<string, MastraMCPServerDefinition>,
189
-});
62
+# Use the MCP URL with OpenAI (hypothetical integration)
63
+# OpenAI MCP support details coming soon
64
+```
65
+</CodeGroupItem>
66
+<CodeGroupItem title="TypeScript">
67
+```typescript
68
+import OpenAI from 'openai';
69
191
-// List available tools from MCP client
192
-const tools = await mcpClient.getTools();
193
-console.log(`🔧 Available tools: ${Object.keys(tools).join(", ")}`);
194
-
195
-// Create a Gmail agent using the MCP tools
196
-const gmailAgent = new Agent({
197
- name: "Gmail Assistant",
198
- instructions: `
199
- You are a helpful Gmail assistant that fetches and summarizes emails.
200
- When fetching emails, provide a clear summary of the results including sender, subject, and date.
201
- Be concise and provide actionable information based on the email content.
202
- `,
203
- model: openai("gpt-4o-mini"),
204
- tools,
70
+const openai = new OpenAI({
71
+ apiKey: process.env.OPENAI_API_KEY,
72
});
73
207
-// Fetch and summarize recent emails
208
-console.log("\n=== Fetching and Summarizing Recent Emails ===");
209
-const emailResponse = await gmailAgent.generate(
210
-"Fetch the latest 10 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email"
74
+// Get MCP server URL
75
+const serverUrls = await composio.mcp.getServer(
76
+ server.id,
77
+ "user@example.com"
78
);
212
-console.log("\n📬 Email Summary:");
213
-console.log(emailResponse.text);
79
215
-console.log("\n✅ Gmail MCP example completed successfully!");
80
+// Integration with OpenAI (when available)
81
+// Use serverUrls with OpenAI's MCP support
82
```
217
-
218
- </CodeGroupItem>
83
+</CodeGroupItem>
84
</CodeGroup>
85
221
----
222
-
223
-## 3. OpenAI SDK Provider
86
+## Vercel AI SDK
87
225
-The **OpenAI SDK Provider** is designed for use with the OpenAI SDK and supports MCP tools through a streamlined client. This client provides a `getServer` method to obtain the Composio MCP Server URL, configured for your user.
226
-
227
-<CodeGroup>
228
- <CodeGroupItem title="TypeScript">
88
+Use MCP servers with Vercel's AI SDK.
89
90
```typescript
231
-import { Composio } from '@composio/core';
232
-import { OpenAIProvider } from '@composio/openai';
233
-import OpenAI from 'openai';
91
+import { experimental_createMCPClient as createMCPClient } from 'ai';
92
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
93
235
-const openai = new OpenAI({
236
- apiKey: process.env.OPENAI_API_KEY,
237
-});
94
+// Get server URL
95
+const serverUrls = await composio.mcp.getServer(
96
+ server.id,
97
+ "user@example.com"
98
+);
99
239
-const composio = new Composio({
240
- apiKey: process.env.COMPOSIO_API_KEY,
241
- provider: new OpenAIProvider(),
100
+// Create MCP client
101
+const mcpClient = await createMCPClient({
102
+ name: 'composio-mcp-client',
103
+ transport: new SSEClientTransport(new URL(serverUrls.url)),
104
});
105
244
-// Create MCP server with new API structure
245
-const mcpConfig = await composio.mcp.create({
246
- name: "Gmail Readonly Server",
247
- serverConfig: [
248
- {
249
- authConfigId: "<auth_config_id>", // Your auth config ID
250
- allowedTools: ["GMAIL_FETCH_EMAILS"]
251
- }
252
- ],
253
- options: {
254
- isChatAuth: true
255
- }
256
-});
106
+// Use with Vercel AI
107
+const tools = await mcpClient.tools();
108
+```
109
258
-console.log(`✅ MCP server created: ${mcpConfig.id}`);
259
-console.log(`🔧 Available toolkits: ${mcpConfig.toolkits.join(", ")}`);
110
+## Cursor IDE
111
261
-// Check if user has necessary connections
262
-const connectionStatus = await composio.mcp.getUserConnectionStatus({
263
- id: mcpConfig.id,
264
- userId: "utkarsh-dixit"
265
-});
112
+Configure MCP servers in Cursor settings.
113
267
-if (!connectionStatus.connected) {
268
- console.log("❌ User authentication required");
269
- // Handle missing connections
270
- for (const [toolkit, status] of Object.entries(connectionStatus.connectedToolkits)) {
271
- if (!status.connected) {
272
- const authParams = await composio.mcp.getConnectionParams({
273
- id: mcpConfig.id,
274
- toolkit
275
- });
276
-
277
- const authRequest = await composio.mcp.authorize({
278
- id: mcpConfig.id,
279
- userId: "utkarsh-dixit",
280
- toolkit
281
- });
282
-
283
- if (authRequest.redirectUrl) {
284
- console.log(`Please authenticate with ${toolkit}: ${authRequest.redirectUrl}`);
285
- }
114
+```json
115
+{
116
+ "mcpServers": {
117
+ "composio": {
118
+ "command": "npx",
119
+ "args": [
120
+ "-y",
121
+ "@modelcontextprotocol/server-compose",
122
+ "YOUR_MCP_SERVER_URL"
123
+ ]
124
}
125
}
288
- return;
126
}
290
-
291
-// Retrieve server URLs for connected accounts
292
-const serverUrls = await mcpConfig.getServer({
293
- userId: "utkarsh-dixit",
294
- options: {
295
- limitTools: ["GMAIL_FETCH_EMAILS"] // Optional: limit to specific tools
296
- }
297
-});
298
-
299
-console.log("Server URLs for your MCP server:", serverUrls);
300
-
301
-// Use with OpenAI (example with hypothetical OpenAI MCP integration)
302
-const completion = await openai.chat.completions.create({
303
- model: "gpt-4o-mini",
304
- messages: [
305
- {
306
- role: "user",
307
- content: "I've connected to Gmail and I want to fetch the latest email from my inbox and summarize it"
308
- }
309
- ],
310
- // Note: This is a hypothetical integration - actual OpenAI MCP support may differ
311
- tools: serverUrls,
312
-});
313
-
314
-console.log("\n📬 Email Summary:");
315
-console.log(completion.choices[0].message.content);
316
-
317
-console.log("\n✅ OpenAI MCP example completed successfully!");
318
-console.log("\n💡 Note: The MCP server URLs can also be used to connect from other MCP-compatible clients.");
319
-console.log(`📍 Server ID for future reference: ${mcpConfig.id}`);
127
```
128
322
- </CodeGroupItem>
323
-</CodeGroup>
129
+## Claude Desktop
130
325
----
131
+Add to Claude Desktop configuration:
132
327
-## Managing Existing Servers
133
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
134
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
135
329
-You can also work with previously created MCP servers:
330
-
331
-```typescript
332
-// Find a server by name
333
-const existingServer = await composio.mcp.getByName("Gmail Readonly Server");
334
-
335
-// Check connection status for the existing server
336
-const status = await composio.mcp.getUserConnectionStatus({
337
- id: existingServer.id,
338
- userId: "user123@example.com"
339
-});
340
-
341
-// Generate URLs for the existing server
342
-const urls = await composio.mcp.getServer({
343
- id: existingServer.id,
344
- userId: "user123@example.com",
345
- options: {
346
- isChatAuth: true
136
+```json
137
+{
138
+ "mcpServers": {
139
+ "composio-gmail": {
140
+ "command": "node",
141
+ "args": [
142
+ "/path/to/mcp-server.js",
143
+ "YOUR_MCP_SERVER_URL"
144
+ ]
145
+ }
146
}
348
-});
147
+}
148
```
149
351
-## Best Practices for Providers
352
-
353
-1. **Always check connection status** before using MCP servers to ensure users are authenticated
354
-2. **Handle authentication gracefully** by providing clear instructions and redirect URLs
355
-3. **Use meaningful server names** to make management easier
356
-4. **Limit tools appropriately** to only what your application needs
357
-5. **Cache server configurations** when possible to reduce API calls
358
-6. **Monitor connection health** and provide re-authentication flows when needed
359
-
360
-By using Composio MCP Servers with these providers, you can quickly connect your agent framework to a wide range of external tools with minimal effort. This lets you streamline integration, reduce setup time, and focus more on building your AI agent.
\ No newline at end of file
150
+## Quick integration guide
151
+
152
+<Steps>
153
+ <Step title="Create MCP server">
154
+ Create your server with the required toolkits and auth configs.
155
+ </Step>
156
+
157
+ <Step title="Generate URLs">
158
+ Generate user-specific URLs for your MCP server.
159
+ </Step>
160
+
161
+ <Step title="Configure client">
162
+ Add the MCP server URL to your AI framework or client configuration.
163
+ </Step>
164
+
165
+ <Step title="Start using">
166
+ The AI can now access the tools exposed by your MCP server.
167
+ </Step>
168
+</Steps>
169
+
170
+## Supported clients
171
+
172
+- **Claude Desktop** - Native MCP support
173
+- **Cursor IDE** - Built-in MCP integration
174
+- **Vercel AI SDK** - Experimental MCP support
175
+- **Custom clients** - Any MCP-compatible client
176
+
177
+## Next steps
178
+
179
+<Cards>
180
+ <Card title="Quickstart" href="/docs/mcp-quickstart" icon="rocket">
181
+ Get started with MCP servers
182
+ </Card>
183
+ <Card title="Implementation guide" href="/docs/mcp-implementation" icon="book">
184
+ Complete development guide
185
+ </Card>
186
+ <Card title="Troubleshooting" href="/docs/troubleshooting/mcp" icon="wrench">
187
+ Common issues and solutions
188
+ </Card>
189
+</Cards>
\ No newline at end of file
fern/pages/src/mcp/quickstart.mdx
new
+98
@@ -0,0 +1,98 @@
1
+---
2
+title: MCP quickstart
3
+subtitle: Create your first MCP server
4
+---
5
+[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open-source standard for connecting AI applications to external tools. All the 500+ tools available in Composio are also available as MCP servers.
6
+
7
+Composio lets you create MCP servers that handle authentication (OAuth, API keys), generate unique URLs for each user, and control which tools are exposed. You can combine multiple toolkits in a single server.
8
+
9
+<Note>
10
+Composio MCP servers only support Streamable HTTP transport.
11
+</Note>
12
+
13
+## Install the SDK
14
+First, install the Composio SDK for your preferred language:
15
+
16
+<CodeGroup>
17
+```bash title="Python" for="python"
18
+pip install composio
19
+```
20
+```bash title="TypeScript" for="typescript"
21
+npm install @composio/core
22
+```
23
+</CodeGroup>
24
+
25
+## Create an MCP server
26
+
27
+<Steps>
28
+ <Step title="Initialize Composio">
29
+ <CodeGroup>
30
+ <SnippetCode src="fern/snippets/mcp/python/quickstart.py" title="Python" startLine={1} endLine={4} />
31
+ <SnippetCode src="fern/snippets/mcp/typescript/quickstart.ts" title="TypeScript" startLine={1} endLine={6} />
32
+ </CodeGroup>
33
+ </Step>
34
+
35
+ <Step title="Create server configuration">
36
+ <Warning>
37
+ **Before you begin:** [Create an auth configuration](/docs/authenticating-tools#creating-an-auth-config) for your toolkit.
38
+ </Warning>
39
+
40
+ Create an MCP server with your auth config. You can also set list of specific tools to enable across all toolkits
41
+
42
+ <CodeGroup>
43
+ <SnippetCode src="fern/snippets/mcp/python/quickstart.py" title="Python" startLine={6} endLine={22} />
44
+ <SnippetCode src="fern/snippets/mcp/typescript/quickstart.ts" title="TypeScript" startLine={8} endLine={23} />
45
+ </CodeGroup>
46
+
47
+ <Note>
48
+ **Alternative:** You can also create and manage MCP configs directly from the [Composio dashboard → MCP Configs](https://platform.composio.dev?next_page=/mcp-configs).
49
+ </Note>
50
+
51
+ </Step>
52
+
53
+ <Step title="Generate user URLs">
54
+ <Warning>
55
+ **Before generating URLs:** Users must authenticate with the toolkits configured in your MCP server. See [hosted authentication](/docs/authenticating-tools#hosted-authentication-connect-link) for how to connect user accounts.
56
+ </Warning>
57
+
58
+ Get server URLs for your users to connect:
59
+
60
+ <CodeGroup>
61
+ <SnippetCode src="fern/snippets/mcp/python/quickstart.py" title="Python" startLine={24} endLine={28} />
62
+ <SnippetCode src="fern/snippets/mcp/typescript/quickstart.ts" title="TypeScript" startLine={25} endLine={29} />
63
+ </CodeGroup>
64
+
65
+ <Note>
66
+ If users haven't authenticated, the MCP server will still generate a URL but tools requiring authentication won't work until the user connects their accounts.
67
+ </Note>
68
+ </Step>
69
+
70
+ <Step title="Use with AI providers">
71
+ Use the MCP server URL with your AI provider:
72
+
73
+ <CodeGroup>
74
+ <SnippetCode src="fern/snippets/mcp/python/openai-client.py" title="OpenAI (Python)" />
75
+ <SnippetCode src="fern/snippets/mcp/python/anthropic-client.py" title="Anthropic (Python)" />
76
+ <SnippetCode src="fern/snippets/mcp/typescript/mastra-client.ts" title="Mastra (TypeScript)" />
77
+ </CodeGroup>
78
+
79
+ </Step>
80
+</Steps>
81
+
82
+## Next steps
83
+
84
+<Cards>
85
+ <Card title="Authentication" href="/docs/mcp-authentication" icon="lock">
86
+ Handle user authentication and connections
87
+ </Card>
88
+ <Card title="Server management" href="/docs/mcp-server-management" icon="server">
89
+ Create and manage MCP servers
90
+ </Card>
91
+ <Card title="Providers" href="/docs/mcp-providers" icon="code">
92
+ Use with Anthropic, OpenAI, and other frameworks
93
+ </Card>
94
+</Cards>
95
+
96
+<Tip>
97
+Need help? Join our [Discord](https://discord.com/invite/composio) or [raise an issue on GitHub](https://github.com/ComposioHQ/composio/issues/new?labels=bug).
98
+</Tip>
\ No newline at end of file
fern/pages/src/mcp/server-management.mdx
new
+281
@@ -0,0 +1,281 @@
1
+---
2
+title: Server management
3
+subtitle: Create, update, and manage MCP servers
4
+---
5
+
6
+This guide covers all server management operations for MCP servers.
7
+
8
+## Create a server
9
+
10
+<CodeGroup>
11
+<CodeGroupItem title="Python">
12
+```python
13
+server = composio.mcp.create(
14
+ name="my-gmail-server",
15
+ toolkits=[{
16
+ "toolkit": "gmail",
17
+ "auth_config": "ac_xyz123"
18
+ }],
19
+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
20
+)
21
+
22
+print(f"Created server: {server.id}")
23
+```
24
+</CodeGroupItem>
25
+<CodeGroupItem title="TypeScript">
26
+```typescript
27
+const server = await composio.mcp.create(
28
+ "my-gmail-server",
29
+ [{
30
+ authConfigId: "ac_xyz123",
31
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
32
+ }],
33
+ { isChatAuth: true }
34
+);
35
+
36
+console.log(`Created server: ${server.id}`);
37
+```
38
+</CodeGroupItem>
39
+</CodeGroup>
40
+
41
+## List servers
42
+
43
+Find and filter your MCP servers.
44
+
45
+<CodeGroup>
46
+<CodeGroupItem title="Python">
47
+```python
48
+# List all servers
49
+servers = composio.mcp.list()
50
+print(f"Found {len(servers['items'])} servers")
51
+
52
+# Filter by toolkit
53
+gmail_servers = composio.mcp.list(
54
+ toolkits="gmail",
55
+ limit=20
56
+)
57
+
58
+# Filter by name
59
+production_servers = composio.mcp.list(
60
+ name="production"
61
+)
62
+```
63
+</CodeGroupItem>
64
+<CodeGroupItem title="TypeScript">
65
+```typescript
66
+// List all servers
67
+const servers = await composio.mcp.list();
68
+console.log(`Found ${servers.items.length} servers`);
69
+
70
+// Filter by toolkit
71
+const gmailServers = await composio.mcp.list({
72
+ toolkits: ["gmail"],
73
+ limit: 20
74
+});
75
+
76
+// Filter by name
77
+const productionServers = await composio.mcp.list({
78
+ name: "production"
79
+});
80
+```
81
+</CodeGroupItem>
82
+</CodeGroup>
83
+
84
+## Get server details
85
+
86
+<CodeGroup>
87
+<CodeGroupItem title="Python">
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']}")
93
+```
94
+</CodeGroupItem>
95
+<CodeGroupItem title="TypeScript">
96
+```typescript
97
+// Get by ID
98
+const server = await composio.mcp.get("mcp_server_id");
99
+
100
+// Get by name (TypeScript only)
101
+const namedServer = await composio.mcp.getByName("my-gmail-server");
102
+
103
+console.log(`Server: ${server.name}`);
104
+console.log(`Toolkits: ${server.toolkits}`);
105
+```
106
+</CodeGroupItem>
107
+</CodeGroup>
108
+
109
+## Update a server
110
+
111
+Modify server configuration, tools, or auth configs.
112
+
113
+<CodeGroup>
114
+<CodeGroupItem title="Python">
115
+```python
116
+updated = composio.mcp.update(
117
+ server_id="mcp_server_id",
118
+ name="updated-name",
119
+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
120
+)
121
+```
122
+</CodeGroupItem>
123
+<CodeGroupItem title="TypeScript">
124
+```typescript
125
+const updated = await composio.mcp.update(
126
+ "mcp_server_id",
127
+ "updated-name",
128
+ [{
129
+ toolkit: "gmail",
130
+ authConfigId: "ac_new_config",
131
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
132
+ }],
133
+ { isChatAuth: true }
134
+);
135
+```
136
+</CodeGroupItem>
137
+</CodeGroup>
138
+
139
+## Delete a server
140
+
141
+<CodeGroup>
142
+<CodeGroupItem title="Python">
143
+```python
144
+result = composio.mcp.delete("mcp_server_id")
145
+if result['deleted']:
146
+ print("Server deleted successfully")
147
+```
148
+</CodeGroupItem>
149
+<CodeGroupItem title="TypeScript">
150
+```typescript
151
+const result = await composio.mcp.delete("mcp_server_id");
152
+if (result.deleted) {
153
+ console.log("Server deleted successfully");
154
+}
155
+```
156
+</CodeGroupItem>
157
+</CodeGroup>
158
+
159
+## Multi-toolkit servers
160
+
161
+Combine multiple services in a single MCP server.
162
+
163
+<CodeGroup>
164
+<CodeGroupItem title="Python">
165
+```python
166
+server = composio.mcp.create(
167
+ name="productivity-suite",
168
+ toolkits=[
169
+ {"toolkit": "gmail", "auth_config": "ac_gmail"},
170
+ {"toolkit": "slack", "auth_config": "ac_slack"},
171
+ {"toolkit": "github", "auth_config": "ac_github"}
172
+ ],
173
+ allowed_tools=[
174
+ "GMAIL_FETCH_EMAILS",
175
+ "SLACK_SEND_MESSAGE",
176
+ "GITHUB_CREATE_ISSUE"
177
+ ]
178
+)
179
+```
180
+</CodeGroupItem>
181
+<CodeGroupItem title="TypeScript">
182
+```typescript
183
+const server = await composio.mcp.create(
184
+ "productivity-suite",
185
+ [
186
+ {
187
+ authConfigId: "ac_gmail",
188
+ allowedTools: ["GMAIL_FETCH_EMAILS"]
189
+ },
190
+ {
191
+ authConfigId: "ac_slack",
192
+ allowedTools: ["SLACK_SEND_MESSAGE"]
193
+ },
194
+ {
195
+ authConfigId: "ac_github",
196
+ allowedTools: ["GITHUB_CREATE_ISSUE"]
197
+ }
198
+ ],
199
+ { isChatAuth: true }
200
+);
201
+```
202
+</CodeGroupItem>
203
+</CodeGroup>
204
+
205
+## Generate user URLs
206
+
207
+After creating a server, generate unique URLs for each user.
208
+
209
+<CodeGroup>
210
+<CodeGroupItem title="Python">
211
+```python
212
+# Generate instance for user
213
+instance = server.generate("user@example.com")
214
+
215
+print(f"URL: {instance['url']}")
216
+print(f"Tools: {instance['allowed_tools']}")
217
+```
218
+</CodeGroupItem>
219
+<CodeGroupItem title="TypeScript">
220
+```typescript
221
+// Generate URLs for user
222
+const urls = await composio.mcp.getServer(
223
+ server.id,
224
+ "user@example.com"
225
+);
226
+
227
+// Or use convenience method from create response
228
+const urls2 = await server.getServer({
229
+ userId: "user@example.com"
230
+});
231
+
232
+console.log("URL:", urls);
233
+```
234
+</CodeGroupItem>
235
+</CodeGroup>
236
+
237
+## Best practices
238
+
239
+- **Use descriptive names** - Makes servers easy to find
240
+- **Limit tools appropriately** - Only include necessary tools
241
+- **Reuse servers** - Don't create duplicates for same configuration
242
+- **Store server IDs** - Keep track of created server IDs
243
+
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
fern/snippets/mcp/python/anthropic-client.py
new
+25
@@ -0,0 +1,25 @@
1
+from anthropic import Anthropic
2
+
3
+# Initialize Anthropic client
4
+client = Anthropic(api_key="your-anthropic-api-key")
5
+
6
+# Use the MCP server URL you generated
7
+mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"
8
+
9
+# Use MCP with Anthropic (beta feature)
10
+response = client.beta.messages.create(
11
+ model="claude-3-5-sonnet-20241022",
12
+ max_tokens=1000,
13
+ messages=[{
14
+ "role": "user",
15
+ "content": "What meetings do I have tomorrow? Also check if I have any urgent emails"
16
+ }],
17
+ mcp_servers=[{
18
+ "type": "url",
19
+ "url": mcp_server_url,
20
+ "name": "composio-gmail-calendar-mcp-server"
21
+ }],
22
+ betas=["mcp-client-2025-01-15"] # Enable MCP beta
23
+)
24
+
25
+print(response.content)
\ No newline at end of file
fern/snippets/mcp/python/openai-client.py
new
+24
@@ -0,0 +1,24 @@
1
+from openai import OpenAI
2
+
3
+# Initialize OpenAI client
4
+client = OpenAI(api_key="your-openai-api-key")
5
+
6
+# Use the MCP server URL you generated
7
+mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"
8
+
9
+# Use MCP with OpenAI Responses API
10
+response = client.responses.create(
11
+ model="gpt-5",
12
+ tools=[
13
+ {
14
+ "type": "mcp",
15
+ "server_label": "composio-server",
16
+ "server_description": "Composio MCP server for Gmail and Calendar integrations",
17
+ "server_url": mcp_server_url,
18
+ "require_approval": "never",
19
+ },
20
+ ],
21
+ input="What meetings do I have tomorrow? Also check if I have any urgent emails",
22
+)
23
+
24
+print("OpenAI MCP Response:", response.output_text)
\ No newline at end of file
fern/snippets/mcp/python/quickstart.py
new
+28
@@ -0,0 +1,28 @@
1
+from composio import Composio
2
+
3
+# Initialize Composio
4
+composio = Composio(api_key="YOUR_API_KEY")
5
+
6
+# Create MCP server with multiple toolkits
7
+server = composio.mcp.create(
8
+ name="mcp-config-73840", # Pick a unique name for your MCP server
9
+ toolkits=[
10
+ {
11
+ "toolkit": "gmail",
12
+ "auth_config": "ac_xyz123" # Your Gmail auth config ID
13
+ },
14
+ {
15
+ "toolkit": "googlecalendar",
16
+ "auth_config": "ac_abc456" # Your Google Calendar auth config ID
17
+ }
18
+ ],
19
+ allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
20
+)
21
+
22
+print(f"Server created: {server.id}")
23
+print(server.id)
24
+
25
+# Generate server instance for user
26
+instance = composio.mcp.generate(user_id="user-73840", mcp_config_id=server.id) # Use the user ID for which you created the connected account
27
+
28
+print(f"MCP Server URL: {instance['url']}")
\ No newline at end of file
fern/snippets/mcp/typescript/mastra-client.ts
new
+26
@@ -0,0 +1,26 @@
1
+import { MCPClient } from "@mastra/mcp";
2
+import { openai } from "@ai-sdk/openai";
3
+import { Agent } from "@mastra/core/agent";
4
+
5
+// Use the MCP server URL you generated
6
+const MCP_URL = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID";
7
+
8
+export const client = new MCPClient({
9
+ id: "docs-mcp-client",
10
+ servers: {
11
+ composio: { url: new URL(MCP_URL) },
12
+ }
13
+});
14
+
15
+export const agent = new Agent({
16
+ name: "Assistant",
17
+ description: "Helpful AI with MCP tools",
18
+ instructions: "Use the MCP tools to answer.",
19
+ model: openai("gpt-4-turbo"),
20
+ tools: await client.getTools()
21
+});
22
+
23
+(async () => {
24
+ const res = await agent.generate("What meetings do I have tomorrow? Also check if I have any urgent emails");
25
+ console.log(res.text);
26
+})();
\ No newline at end of file
fern/snippets/mcp/typescript/quickstart.ts
new
+29
@@ -0,0 +1,29 @@
1
+import { Composio } from '@composio/core';
2
+
3
+// Initialize Composio
4
+const composio = new Composio({
5
+ apiKey: process.env.COMPOSIO_API_KEY
6
+});
7
+
8
+// Create MCP server with multiple toolkits
9
+const server = await composio.mcp.create("mcp-config-73840", { // Pick a unique name for your MCP server
10
+ toolkits: [
11
+ {
12
+ authConfigId: "ac_xyz123", // Your Gmail auth config ID
13
+ toolkit: "gmail"
14
+ },
15
+ {
16
+ authConfigId: "ac_abc456", // Your Google Calendar auth config ID
17
+ toolkit: "googlecalendar"
18
+ }
19
+ ],
20
+ allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
21
+});
22
+
23
+console.log(`Server created: ${server.id}`);
24
+console.log(server.id);
25
+
26
+// Generate server instance for user
27
+const instance = await composio.mcp.generate("user-73840", server.id); // Use the user ID for which you created the connected account
28
+
29
+console.log("MCP Server URL:", instance.url);
\ No newline at end of file
fern/snippets/mcp/typescript/vercel-client.ts
new
+26
@@ -0,0 +1,26 @@
1
+import { experimental_createMCPClient as createMCPClient } from 'ai';
2
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
3
+
4
+// Use the MCP server URL you generated
5
+const mcpServerUrl = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID";
6
+
7
+// Create MCP client
8
+const mcpClient = await createMCPClient({
9
+ name: 'composio-mcp-client',
10
+ transport: new SSEClientTransport(new URL(mcpServerUrl)),
11
+});
12
+
13
+// Get available tools from the MCP server
14
+const tools = await mcpClient.tools();
15
+
16
+// Use with Vercel AI SDK
17
+import { generateText } from 'ai';
18
+import { openai } from '@ai-sdk/openai';
19
+
20
+const result = await generateText({
21
+ model: openai('gpt-4-turbo'),
22
+ tools: tools,
23
+ prompt: 'Send an email to john@example.com with meeting notes',
24
+});
25
+
26
+console.log(result.text);
\ No newline at end of file