@devries-cameron20 / composio-1 / commits / 15ff0d35a
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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