@devries-cameron20 / composio Mirror · read-only / commits / dac857cb3
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 15:45 UTC

Add MCP, Resources, Migration Guide, and Troubleshooting sections

MCP Section: - Quickstart - Creating MCP servers and user URLs - Server management - CRUD operations for MCP servers - Providers - Anthropic, OpenAI, Mastra integrations Resources Section: - CLI - Installation, authentication, type generation - Debugging Info - Project/org IDs for support Migration Guide Section: - Overview - Links to available guides - New SDK migration - Comprehensive SDK v3 migration guide - Toolkit versioning - Breaking change migration Troubleshooting Section: - Overview with quick links - API, Authentication, CLI, Dashboard, MCP - SDKs, Tools & Toolkits, Triggers 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Dec 30, 2025 at 13:52 UTC dac857cb343ba925323a8025784eb9d738d8eabf
22 files changed +2836 -1
fumadocs/content/docs/cli.mdx new
+131
@@ -0,0 +1,131 @@
1 +---
2 +title: CLI
3 +description: Generate type definitions and manage authentication
4 +---
5 +
6 +The Composio CLI helps you generate type-safe code and manage your Composio workspace.
7 +
8 +## Installation
9 +
10 +Install the Composio CLI using the installation script:
11 +
12 +```bash
13 +curl -fsSL https://composio.dev/install | bash
14 +```
15 +
16 +Or using wget:
17 +```bash
18 +wget -qO- https://composio.dev/install | bash
19 +```
20 +
21 +## Authentication
22 +
23 +Manage your Composio authentication directly from the terminal.
24 +
25 +### Login
26 +
27 +Authenticate with your Composio account:
28 +
29 +```bash
30 +composio login
31 +```
32 +
33 +This opens your browser to complete authentication and stores your API key locally.
34 +
35 +To authenticate without opening a browser (useful for SSH/remote sessions):
36 +
37 +```bash
38 +composio login --no-browser
39 +```
40 +
41 +This displays a URL to manually open in your browser.
42 +
43 +### Check authentication status
44 +
45 +Verify your current authentication:
46 +
47 +```bash
48 +composio whoami
49 +```
50 +
51 +This displays your current API key or indicates if you're not authenticated.
52 +
53 +### Logout
54 +
55 +Remove stored authentication:
56 +
57 +```bash
58 +composio logout
59 +```
60 +
61 +## Generate type definitions
62 +
63 +Generate TypeScript or Python type definitions for all Composio tools. These types provide type safety when using direct tool execution (`composio.tools.execute()`), helping you pass the correct parameters and catch errors early.
64 +
65 +### Auto-detect and generate
66 +
67 +The CLI auto-detects your project language.
68 +In your project directory:
69 +
70 +```bash
71 +composio generate
72 +```
73 +
74 +For TypeScript projects only, include individual tool types:
75 +```bash
76 +composio generate --type-tools
77 +```
78 +
79 +The CLI automatically:
80 +- Detects your project type (Python or TypeScript)
81 +- Generates appropriate type definitions
82 +
83 +### Specify output directory
84 +
85 +```bash
86 +composio generate --output-dir ./my-types
87 +```
88 +
89 +### Language-specific commands
90 +
91 +For explicit control, use language-specific commands:
92 +
93 +<Tabs items={['TypeScript', 'Python']}>
94 + <Tab value="TypeScript">
95 + Basic generation:
96 + ```bash
97 + composio ts generate
98 + ```
99 +
100 + Generate as single file:
101 + ```bash
102 + composio ts generate --compact
103 + ```
104 +
105 + Include individual tool types:
106 + ```bash
107 + composio ts generate --type-tools
108 + ```
109 +
110 + Generate both .ts and .js files:
111 + ```bash
112 + composio ts generate --transpiled
113 + ```
114 +
115 + Custom output directory:
116 + ```bash
117 + composio ts generate --output-dir ./my-types
118 + ```
119 + </Tab>
120 + <Tab value="Python">
121 + Basic generation:
122 + ```bash
123 + composio py generate
124 + ```
125 +
126 + Custom output directory:
127 + ```bash
128 + composio py generate --output-dir ./my_types
129 + ```
130 + </Tab>
131 +</Tabs>
fumadocs/content/docs/debugging-info.mdx new
+45
@@ -0,0 +1,45 @@
1 +---
2 +title: Debugging Info
3 +description: Share your debugging info with Composio team for faster issue resolution
4 +---
5 +
6 +Your debugging info is tied to your project and it helps us trace what happened and debug the issue faster.
7 +
8 +## Finding Your Debugging Info
9 +
10 +Navigate to your project settings to find your debugging information:
11 +
12 +<Figure src="/images/project-settings.jpeg" alt="Project Settings Debugging Info" />
13 +
14 +<Figure src="/images/debugging-info.png" alt="Debugging Info Location" />
15 +
16 +## What to Share
17 +
18 +When reaching out for support, share these identifiers:
19 +
20 +```
21 +@project_id: pr_xxxxxxxxxxxxx
22 +@org_id: ok_xxxxxxxxxxxxx
23 +@org_member_email: your-email@example.com
24 +```
25 +
26 +The identifiers with `pr_` (project) and `ok_` (organization) prefixes let us quickly check your logs inside our internal tracing tools, helping us resolve issues faster.
27 +
28 +## Getting Help
29 +
30 +import { MessageCircle, Github, Bug, Mail } from 'lucide-react';
31 +
32 +<Cards>
33 + <Card title="Join Discord" href="https://discord.gg/composio" icon={<MessageCircle />}>
34 + Get basic support from the community and Composio team
35 + </Card>
36 + <Card title="GitHub Discussions" href="https://github.com/ComposioHQ/composio/discussions" icon={<Github />}>
37 + Request new tools and share feedback
38 + </Card>
39 + <Card title="File an Issue" href="https://github.com/ComposioHQ/composio/issues" icon={<Bug />}>
40 + Report SDK issues and bugs
41 + </Card>
42 + <Card title="Contact Support" href="mailto:support@composio.dev" icon={<Mail />}>
43 + Reach out for dedicated support channels on Growth and Enterprise plans
44 + </Card>
45 +</Cards>
fumadocs/content/docs/mcp-providers.mdx new
+254
@@ -0,0 +1,254 @@
1 +---
2 +title: Providers
3 +description: Connect MCP servers to AI frameworks
4 +---
5 +
6 +Integrate your MCP servers with popular AI SDKs and frameworks.
7 +
8 +<Callout type="info">
9 +Composio MCP servers only support Streamable HTTP transport.
10 +</Callout>
11 +
12 +## Anthropic SDK
13 +
14 +Use MCP servers with the Anthropic Claude API.
15 +
16 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
17 + <Tab value="Python">
18 +```python
19 +from anthropic import Anthropic
20 +from composio import Composio
21 +
22 +# Initialize clients
23 +composio = Composio()
24 +anthropic = Anthropic(api_key="your-anthropic-api-key")
25 +
26 +# Create MCP server with GitHub and Linear tools
27 +server = composio.mcp.create(
28 + name="dev-workflow-server",
29 + toolkits=[
30 + {"toolkit": "github", "auth_config": "ac_github_id"},
31 + {"toolkit": "linear", "auth_config": "ac_linear_id"}
32 + ],
33 + allowed_tools=["GITHUB_LIST_PRS", "GITHUB_CREATE_COMMENT", "LINEAR_CREATE_ISSUE"]
34 +)
35 +
36 +# Generate MCP instance for user
37 +instance = server.generate("user@example.com")
38 +
39 +# Use MCP with Anthropic to manage development workflow
40 +response = anthropic.beta.messages.create(
41 + model="claude-sonnet-4-5",
42 + system="You are a helpful assistant with access to GitHub and Linear tools. Use these tools to help manage development workflows. Do not ask for confirmation before using the tools.",
43 + max_tokens=1000,
44 + messages=[{
45 + "role": "user",
46 + "content": "Check my GitHub PRs for review comments, create Linear tasks for any requested changes, and update the PR descriptions with task links"
47 + }],
48 + mcp_servers=[{
49 + "type": "url",
50 + "url": instance['url'],
51 + "name": "composio-mcp-server"
52 + }],
53 + betas=["mcp-client-2025-04-04"] # Enable MCP beta
54 +)
55 +
56 +print(response.content)
57 +```
58 + </Tab>
59 + <Tab value="TypeScript">
60 +```typescript
61 +import Anthropic from '@anthropic-ai/sdk';
62 +import { Composio } from '@composio/core';
63 +
64 +// Initialize clients
65 +const composio = new Composio();
66 +const anthropic = new Anthropic({
67 + apiKey: process.env.ANTHROPIC_API_KEY,
68 +});
69 +
70 +// Create MCP server with Google Sheets tools
71 +const server = await composio.mcp.create(
72 + "analytics-server",
73 + {
74 + toolkits: [
75 + { toolkit: "googlesheets", authConfigId: "ac_sheets_id" }
76 + ],
77 + allowedTools: ["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "GOOGLESHEETS_CREATE_SHEET"]
78 + }
79 +);
80 +
81 +// Generate MCP instance for user
82 +const instance = await server.generate("user@example.com");
83 +
84 +// Use MCP with Anthropic for spreadsheet operations
85 +const response = await anthropic.beta.messages.create({
86 + model: "claude-sonnet-4-5",
87 + system: "You are a helpful assistant with access to Google Sheets tools. Use these tools to analyze and manage spreadsheet data. Do not ask for confirmation before using the tools.",
88 + max_tokens: 1000,
89 + messages: [{
90 + role: "user",
91 + content: "Analyze the sales data in my Google Sheets 'Q4 Revenue' spreadsheet, calculate month-over-month growth, and add a new summary sheet with visualizations"
92 + }],
93 + mcp_servers: [{
94 + type: "url",
95 + url: instance.url,
96 + name: "composio-mcp-server"
97 + }],
98 + betas: ["mcp-client-2025-04-04"] // Enable MCP beta
99 +});
100 +
101 +console.log(response.content);
102 +```
103 + </Tab>
104 +</Tabs>
105 +
106 +## OpenAI SDK
107 +
108 +Integrate MCP servers with OpenAI GPT models.
109 +
110 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
111 + <Tab value="Python">
112 +```python
113 +from openai import OpenAI
114 +from composio import Composio
115 +
116 +# Initialize clients
117 +composio = Composio()
118 +openai = OpenAI(api_key="your-openai-api-key")
119 +
120 +# Create MCP server with Google Sheets and Notion tools
121 +server = composio.mcp.create(
122 + name="data-docs-server",
123 + toolkits=[
124 + {"toolkit": "googlesheets", "auth_config": "ac_sheets_id"},
125 + {"toolkit": "notion", "auth_config": "ac_notion_id"}
126 + ],
127 + allowed_tools=["GOOGLESHEETS_GET_DATA", "GOOGLESHEETS_UPDATE_DATA", "NOTION_CREATE_PAGE"]
128 +)
129 +
130 +# Generate MCP instance for user
131 +instance = server.generate("user@example.com")
132 +
133 +# Use MCP with OpenAI for data management
134 +response = openai.responses.create(
135 + model="gpt-5",
136 + tools=[
137 + {
138 + "type": "mcp",
139 + "server_label": "composio-server",
140 + "server_description": "Composio MCP server with Google Sheets and Notion integrations",
141 + "server_url": instance['url'],
142 + "require_approval": "never",
143 + },
144 + ],
145 + input="Export the Q4 metrics from Google Sheets and create a comprehensive Notion page with charts and analysis",
146 +)
147 +
148 +print("OpenAI MCP Response:", response.output_text)
149 +```
150 + </Tab>
151 + <Tab value="TypeScript">
152 +```typescript
153 +import OpenAI from 'openai';
154 +import { Composio } from '@composio/core';
155 +
156 +// Initialize clients
157 +const composio = new Composio();
158 +const openai = new OpenAI({
159 + apiKey: process.env.OPENAI_API_KEY,
160 +});
161 +
162 +// Create MCP server with Linear and Notion tools
163 +const server = await composio.mcp.create(
164 + "project-docs-server",
165 + {
166 + toolkits: [
167 + { toolkit: "linear", authConfigId: "ac_linear_id" },
168 + { toolkit: "notion", authConfigId: "ac_notion_id" }
169 + ],
170 + allowedTools: ["LINEAR_LIST_ISSUES", "LINEAR_GET_ISSUE", "NOTION_CREATE_PAGE"]
171 + }
172 +);
173 +
174 +// Generate MCP instance for user
175 +const instance = await server.generate("user@example.com");
176 +
177 +// Use MCP with OpenAI for project documentation
178 +const response = await openai.responses.create({
179 + model: "gpt-5",
180 + tools: [
181 + {
182 + type: "mcp",
183 + server_label: "composio-server",
184 + server_description: "Composio MCP server with Linear and Notion integrations",
185 + server_url: instance.url,
186 + require_approval: "never",
187 + },
188 + ],
189 + input: "Find all completed Linear issues from this sprint and create a Notion page documenting the release notes",
190 +});
191 +
192 +console.log("OpenAI MCP Response:", response.output_text);
193 +```
194 + </Tab>
195 +</Tabs>
196 +
197 +## Mastra
198 +
199 +Use MCP servers with Mastra framework.
200 +
201 +```typescript
202 +import { MCPClient } from "@mastra/mcp";
203 +import { openai } from "@ai-sdk/openai";
204 +import { Agent } from "@mastra/core/agent";
205 +import { Composio } from "@composio/core";
206 +
207 +// Initialize Composio
208 +const composio = new Composio();
209 +
210 +// Create MCP server with GitHub, Linear, and Notion tools
211 +const server = await composio.mcp.create(
212 + "dev-automation-server",
213 + {
214 + toolkits: [
215 + { toolkit: "github", authConfigId: "ac_github_id" },
216 + { toolkit: "linear", authConfigId: "ac_linear_id" },
217 + { toolkit: "notion", authConfigId: "ac_notion_id" }
218 + ],
219 + allowedTools: [
220 + "GITHUB_LIST_ISSUES", "GITHUB_CREATE_ISSUE",
221 + "LINEAR_CREATE_ISSUE", "LINEAR_UPDATE_ISSUE",
222 + "NOTION_CREATE_PAGE", "NOTION_UPDATE_PAGE"
223 + ]
224 + }
225 +);
226 +
227 +// Generate MCP instance for user
228 +const instance = await server.generate("user@example.com");
229 +
230 +// Create MCP client with Composio server
231 +export const mcpClient = new MCPClient({
232 + id: "composio-mcp-client",
233 + servers: {
234 + composio: { url: new URL(instance.url) },
235 + }
236 +});
237 +
238 +// Create a development workflow agent
239 +export const devAgent = new Agent({
240 + name: "Dev Assistant",
241 + description: "AI assistant for development workflow automation",
242 + instructions: "Help manage GitHub repos, Linear issues, and Notion documentation.",
243 + model: openai("gpt-4-turbo"),
244 + tools: await mcpClient.getTools()
245 +});
246 +
247 +// Example: Automate development workflow
248 +(async () => {
249 + const response = await devAgent.generate(
250 + "Review open GitHub issues, create Linear tasks for bugs labeled 'priority', and update the Notion roadmap page"
251 + );
252 + console.log(response.text);
253 +})();
254 +```
fumadocs/content/docs/mcp-quickstart.mdx new
+263
@@ -0,0 +1,263 @@
1 +---
2 +title: Quickstart
3 +description: Create your first MCP server
4 +---
5 +
6 +[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.
7 +
8 +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.
9 +
10 +<Callout type="info">
11 +Composio MCP servers only support Streamable HTTP transport.
12 +</Callout>
13 +
14 +## Install the SDK
15 +
16 +First, install the Composio SDK for your preferred language:
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 + <Tab value="Python">
20 +```bash
21 +pip install composio
22 +```
23 + </Tab>
24 + <Tab value="TypeScript">
25 +```bash
26 +npm install @composio/core
27 +```
28 + </Tab>
29 +</Tabs>
30 +
31 +## Create an MCP server
32 +
33 +<Steps>
34 + <Step>
35 + ### Initialize Composio
36 +
37 + <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
38 + <Tab value="Python">
39 +```python
40 +from composio import Composio
41 +
42 +# Initialize Composio
43 +composio = Composio(api_key="YOUR_API_KEY")
44 +```
45 + </Tab>
46 + <Tab value="TypeScript">
47 +```typescript
48 +import { Composio } from '@composio/core';
49 +
50 +// Initialize Composio
51 +const composio = new Composio({
52 + apiKey: process.env.COMPOSIO_API_KEY
53 +});
54 +```
55 + </Tab>
56 + </Tabs>
57 + </Step>
58 +
59 + <Step>
60 + ### Create server configuration
61 +
62 + <Callout type="warn">
63 + **Before you begin:** [Create an auth configuration](/docs/authenticating-tools#creating-an-auth-config) for your toolkit.
64 + </Callout>
65 +
66 + Create an MCP server with your auth config. You can also set list of specific tools to enable across all toolkits.
67 +
68 + <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
69 + <Tab value="Python">
70 +```python
71 +# Create MCP server with multiple toolkits
72 +server = composio.mcp.create(
73 + name="mcp-config-73840", # Pick a unique name for your MCP server
74 + toolkits=[
75 + {
76 + "toolkit": "gmail",
77 + "auth_config": "ac_xyz123" # Your Gmail auth config ID
78 + },
79 + {
80 + "toolkit": "googlecalendar",
81 + "auth_config": "ac_abc456" # Your Google Calendar auth config ID
82 + }
83 + ],
84 + allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
85 +)
86 +
87 +print(f"Server created: {server.id}")
88 +print(server.id)
89 +```
90 + </Tab>
91 + <Tab value="TypeScript">
92 +```typescript
93 +// Create MCP server with multiple toolkits
94 +const server = await composio.mcp.create("mcp-config-73840", { // Pick a unique name for your MCP server
95 + toolkits: [
96 + {
97 + authConfigId: "ac_xyz123", // Your Gmail auth config ID
98 + toolkit: "gmail"
99 + },
100 + {
101 + authConfigId: "ac_abc456", // Your Google Calendar auth config ID
102 + toolkit: "googlecalendar"
103 + }
104 + ],
105 + allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL", "GOOGLECALENDAR_EVENTS_LIST"]
106 +});
107 +
108 +console.log(`Server created: ${server.id}`);
109 +console.log(server.id);
110 +```
111 + </Tab>
112 + </Tabs>
113 +
114 + <Callout type="info">
115 + **Alternative:** You can also create and manage MCP configs directly from the [Composio dashboard → MCP Configs](https://platform.composio.dev?next_page=/mcp-configs).
116 + </Callout>
117 + </Step>
118 +
119 + <Step>
120 + ### Generate user URLs
121 +
122 + <Callout type="warn">
123 + **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.
124 + </Callout>
125 +
126 + Get server URLs for your users to connect:
127 +
128 + <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
129 + <Tab value="Python">
130 +```python
131 +# Generate server instance for user
132 +instance = composio.mcp.generate(user_id="user-73840", mcp_config_id=server.id) # Use the user ID for which you created the connected account
133 +
134 +print(f"MCP Server URL: {instance['url']}")
135 +```
136 + </Tab>
137 + <Tab value="TypeScript">
138 +```typescript
139 +// Generate server instance for user
140 +const instance = await composio.mcp.generate("user-73840", server.id); // Use the user ID for which you created the connected account
141 +
142 +console.log("MCP Server URL:", instance.url);
143 +```
144 + </Tab>
145 + </Tabs>
146 +
147 + <Callout type="info">
148 + 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.
149 + </Callout>
150 + </Step>
151 +
152 + <Step>
153 + ### Use with AI providers
154 +
155 + Use the MCP server URL with your AI provider:
156 +
157 + <Tabs items={['OpenAI (Python)', 'Anthropic (Python)', 'Mastra (TypeScript)']}>
158 + <Tab value="OpenAI (Python)">
159 +```python
160 +from openai import OpenAI
161 +
162 +# Initialize OpenAI client
163 +client = OpenAI(api_key="your-openai-api-key")
164 +
165 +# Use the MCP server URL you generated
166 +mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"
167 +
168 +# Use MCP with OpenAI Responses API
169 +response = client.responses.create(
170 + model="gpt-5",
171 + tools=[
172 + {
173 + "type": "mcp",
174 + "server_label": "composio-server",
175 + "server_description": "Composio MCP server for Gmail and Calendar integrations",
176 + "server_url": mcp_server_url,
177 + "require_approval": "never",
178 + },
179 + ],
180 + input="What meetings do I have tomorrow? Also check if I have any urgent emails",
181 +)
182 +
183 +print("OpenAI MCP Response:", response.output_text)
184 +```
185 + </Tab>
186 + <Tab value="Anthropic (Python)">
187 +```python
188 +from anthropic import Anthropic
189 +
190 +# Initialize Anthropic client
191 +client = Anthropic(api_key="your-anthropic-api-key")
192 +
193 +# Use the MCP server URL you generated
194 +mcp_server_url = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID"
195 +
196 +# Use MCP with Anthropic (beta feature)
197 +response = client.beta.messages.create(
198 + model="claude-sonnet-4-5",
199 + system="You are a helpful assistant with access to various tools through MCP. Use these tools to help the user. Do not ask for confirmation before using the tools.",
200 + max_tokens=1000,
201 + messages=[{
202 + "role": "user",
203 + "content": "What meetings do I have tomorrow? Also check if I have any urgent emails"
204 + }],
205 + mcp_servers=[{
206 + "type": "url",
207 + "url": mcp_server_url,
208 + "name": "composio-gmail-calendar-mcp-server"
209 + }],
210 + betas=["mcp-client-2025-04-04"] # Enable MCP beta
211 +)
212 +
213 +print(response.content)
214 +```
215 + </Tab>
216 + <Tab value="Mastra (TypeScript)">
217 +```typescript
218 +import { MCPClient } from "@mastra/mcp";
219 +import { openai } from "@ai-sdk/openai";
220 +import { Agent } from "@mastra/core/agent";
221 +
222 +// Use the MCP server URL you generated
223 +const MCP_URL = "https://backend.composio.dev/v3/mcp/YOUR_SERVER_ID?include_composio_helper_actions=true&user_id=YOUR_USER_ID";
224 +
225 +export const client = new MCPClient({
226 + id: "docs-mcp-client",
227 + servers: {
228 + composio: { url: new URL(MCP_URL) },
229 + }
230 +});
231 +
232 +export const agent = new Agent({
233 + name: "Assistant",
234 + description: "Helpful AI with MCP tools",
235 + instructions: "Use the MCP tools to answer.",
236 + model: openai("gpt-4-turbo"),
237 + tools: await client.getTools()
238 +});
239 +
240 +(async () => {
241 + const res = await agent.generate("What meetings do I have tomorrow? Also check if I have any urgent emails");
242 + console.log(res.text);
243 +})();
244 +```
245 + </Tab>
246 + </Tabs>
247 + </Step>
248 +</Steps>
249 +
250 +## Next steps
251 +
252 +<Cards>
253 + <Card title="Server management" href="/docs/mcp-server-management">
254 + Create and manage MCP servers
255 + </Card>
256 + <Card title="Providers" href="/docs/mcp-providers">
257 + Use with Anthropic, OpenAI, and other frameworks
258 + </Card>
259 +</Cards>
260 +
261 +<Callout type="info">
262 +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).
263 +</Callout>
fumadocs/content/docs/mcp-server-management.mdx new
+284
@@ -0,0 +1,284 @@
1 +---
2 +title: Server management
3 +description: 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 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
11 + <Tab value="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 + </Tab>
25 + <Tab value="TypeScript">
26 +```typescript
27 +const server = await composio.mcp.create(
28 + "my-gmail-server",
29 + {
30 + toolkits: [
31 + {
32 + authConfigId: "ac_xyz123",
33 + toolkit: "gmail"
34 + }
35 + ],
36 + allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
37 + manuallyManageConnections: false
38 + }
39 +);
40 +
41 +console.log(`Created server: ${server.id}`);
42 +```
43 + </Tab>
44 +</Tabs>
45 +
46 +## List servers
47 +
48 +Find and filter your MCP servers.
49 +
50 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
51 + <Tab value="Python">
52 +```python
53 +# List all servers
54 +servers = composio.mcp.list()
55 +print(f"Found {len(servers['items'])} servers")
56 +
57 +# Filter by toolkit
58 +gmail_servers = composio.mcp.list(
59 + toolkits="gmail",
60 + limit=20
61 +)
62 +
63 +# Filter by name
64 +production_servers = composio.mcp.list(
65 + name="production"
66 +)
67 +```
68 + </Tab>
69 + <Tab value="TypeScript">
70 +```typescript
71 +// List all servers
72 +const servers = await composio.mcp.list({
73 + limit: 10,
74 + page: 1,
75 + authConfigs: [],
76 + toolkits: []
77 +});
78 +console.log(`Found ${servers.items.length} servers`);
79 +
80 +// Filter by toolkit
81 +const gmailServers = await composio.mcp.list({
82 + limit: 20,
83 + page: 1,
84 + authConfigs: [],
85 + toolkits: ["gmail"]
86 +});
87 +
88 +// Filter by name
89 +const productionServers = await composio.mcp.list({
90 + limit: 10,
91 + page: 1,
92 + authConfigs: [],
93 + toolkits: [],
94 + name: "production"
95 +});
96 +```
97 + </Tab>
98 +</Tabs>
99 +
100 +## Get server details
101 +
102 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
103 + <Tab value="Python">
104 +```python
105 +# Get by ID
106 +server = composio.mcp.get("mcp_server_id")
107 +print(f"Server name: {server.name}")
108 +print(f"Toolkits: {server.toolkits}")
109 +```
110 + </Tab>
111 + <Tab value="TypeScript">
112 +```typescript
113 +// Get by ID
114 +const server = await composio.mcp.get("mcp_server_id");
115 +
116 +console.log(`Server: ${server.name}`);
117 +console.log(`Toolkits: ${server.toolkits}`);
118 +```
119 + </Tab>
120 +</Tabs>
121 +
122 +## Update a server
123 +
124 +Modify server configuration, tools, or auth configs.
125 +
126 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
127 + <Tab value="Python">
128 +```python
129 +updated = composio.mcp.update(
130 + server_id="mcp_server_id",
131 + name="updated-name",
132 + allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
133 +)
134 +```
135 + </Tab>
136 + <Tab value="TypeScript">
137 +```typescript
138 +const updated = await composio.mcp.update(
139 + "mcp_server_id",
140 + {
141 + name: "updated-name",
142 + toolkits: [
143 + {
144 + toolkit: "gmail",
145 + authConfigId: "ac_new_config"
146 + }
147 + ],
148 + allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"],
149 + manuallyManageConnections: false
150 + }
151 +);
152 +
153 +console.log(updated);
154 +```
155 + </Tab>
156 +</Tabs>
157 +
158 +## Delete a server
159 +
160 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
161 + <Tab value="Python">
162 +```python
163 +result = composio.mcp.delete("mcp_server_id")
164 +if result['deleted']:
165 + print("Server deleted successfully")
166 +```
167 + </Tab>
168 + <Tab value="TypeScript">
169 +```typescript
170 +const result = await composio.mcp.delete("mcp_server_id");
171 +if (result.deleted) {
172 + console.log("Server deleted successfully");
173 +}
174 +```
175 + </Tab>
176 +</Tabs>
177 +
178 +## Multi-toolkit servers
179 +
180 +Combine multiple services in a single MCP server.
181 +
182 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
183 + <Tab value="Python">
184 +```python
185 +server = composio.mcp.create(
186 + name="productivity-suite",
187 + toolkits=[
188 + {"toolkit": "gmail", "auth_config": "ac_gmail"},
189 + {"toolkit": "slack", "auth_config": "ac_slack"},
190 + {"toolkit": "github", "auth_config": "ac_github"}
191 + ],
192 + allowed_tools=[
193 + "GMAIL_FETCH_EMAILS",
194 + "SLACK_SEND_MESSAGE",
195 + "GITHUB_CREATE_ISSUE"
196 + ]
197 +)
198 +```
199 + </Tab>
200 + <Tab value="TypeScript">
201 +```typescript
202 +const server = await composio.mcp.create(
203 + "productivity-suite",
204 + {
205 + toolkits: [
206 + {
207 + authConfigId: "ac_gmail",
208 + toolkit: "gmail"
209 + },
210 + {
211 + authConfigId: "ac_slack",
212 + toolkit: "slack"
213 + },
214 + {
215 + authConfigId: "ac_github",
216 + toolkit: "github"
217 + }
218 + ],
219 + allowedTools: [
220 + "GMAIL_FETCH_EMAILS",
221 + "SLACK_SEND_MESSAGE",
222 + "GITHUB_CREATE_ISSUE"
223 + ],
224 + manuallyManageConnections: false
225 + }
226 +);
227 +```
228 + </Tab>
229 +</Tabs>
230 +
231 +## Generate user URLs
232 +
233 +After creating a server, generate unique URLs for each user.
234 +
235 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
236 + <Tab value="Python">
237 +```python
238 +# Generate instance for user
239 +instance = server.generate("user@example.com")
240 +
241 +print(f"URL: {instance['url']}")
242 +print(f"Tools: {instance['allowed_tools']}")
243 +
244 +# Chat-based authentication is enabled by default
245 +# Set manually_manage_connections=True to disable it:
246 +instance_manual = server.generate(
247 + "user@example.com",
248 + manually_manage_connections=True
249 +)
250 +```
251 + </Tab>
252 + <Tab value="TypeScript">
253 +```typescript
254 +// Generate instance for user
255 +const instance = await server.generate("user@example.com");
256 +
257 +console.log("URL:", instance.url);
258 +console.log("Tools:", instance.allowedTools);
259 +
260 +// Chat-based authentication is enabled by default
261 +// Set manuallyManageConnections: true to disable it:
262 +const instanceManual = await composio.mcp.generate(
263 + "user@example.com",
264 + server.id,
265 + { manuallyManageConnections: true }
266 +);
267 +```
268 + </Tab>
269 +</Tabs>
270 +
271 +<Callout type="info">
272 +**Chat-based authentication:**
273 +- **TypeScript**: Enabled by default (set `manuallyManageConnections=false` or omit it)
274 +- **Python**: Enabled by default (set `manually_manage_connections=False` or omit it)
275 +
276 +When enabled, the agent can authenticate users dynamically during conversation if they're missing required connections. Set `manuallyManageConnections=true` (TypeScript) or `manually_manage_connections=True` (Python) to disable it.
277 +</Callout>
278 +
279 +## Best practices
280 +
281 +- **Use descriptive names** - Makes servers easy to find
282 +- **Limit tools appropriately** - Only include necessary tools
283 +- **Reuse servers** - Don't create duplicates for same configuration
284 +- **Store server IDs** - Keep track of created server IDs
fumadocs/content/docs/meta.json
+10 -1
@@ -17,6 +17,15 @@
17 "programmatic-auth-configs",
18 "custom-auth-params",
19 "connected-accounts",
20 - "user-management"
20 + "user-management",
21 + "---MCP---",
22 + "mcp-quickstart",
23 + "mcp-server-management",
24 + "mcp-providers",
25 + "---Resources---",
26 + "cli",
27 + "debugging-info",
28 + "migration-guide",
29 + "troubleshooting"
30 ]
31 }
fumadocs/content/docs/migration-guide/index.mdx new
+20
@@ -0,0 +1,20 @@
1 +---
2 +title: Migration guides
3 +description: Guides for migrating to newer versions of Composio
4 +---
5 +
6 +## Available migration guides
7 +
8 +<Accordions>
9 + <Accordion title="New SDK migration">
10 + Migrate from the old Composio SDK to the new SDK, including breaking changes, new features, and updated APIs.
11 +
12 + [View SDK migration guide →](/docs/migration-guide/new-sdk)
13 + </Accordion>
14 +
15 + <Accordion title="Toolkit versioning migration">
16 + Migrate to use the toolkit versioning system.
17 +
18 + [View versioning migration guide →](/docs/migration-guide/toolkit-versioning)
19 + </Accordion>
20 +</Accordions>
fumadocs/content/docs/migration-guide/meta.json new
+8
@@ -0,0 +1,8 @@
1 +{
2 + "title": "Migration Guide",
3 + "pages": [
4 + "index",
5 + "new-sdk",
6 + "toolkit-versioning"
7 + ]
8 +}
fumadocs/content/docs/migration-guide/new-sdk.mdx new
+1259
@@ -0,0 +1,1259 @@
1 +---
2 +title: Our next generation SDKs
3 +description: Learn more about Composio's next generation SDKs and how to migrate
4 +---
5 +
6 +In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
7 +
8 +A lot of these changes have happened in the background, but we are excited to finally share our new SDKs with you that complement our new infra.
9 +
10 +The new API features improved usability, enhanced stability, and better scalability. The SDKs built on top of it simplify the developer experience, making it easier than ever to build useful agents.
11 +
12 +## What's new?
13 +
14 +A lot of the changes are on the infra side, but from the SDK point of view, here is what you can expect:
15 +- Faster and more reliable tool execution
16 +- A simpler but more opinionated SDK
17 +- Much more intuitive and consistent naming conventions
18 +- A vastly improved TypeScript SDK that is meaningfully more type-safe and has full feature parity with the Python SDK
19 +
20 +There aren't too many new flashy features here (yet) mainly because we wanted to get the bones right — but we feel we have a solid foundation to ship incredible new experiences on top very quickly.
21 +
22 +## State of the new SDK and what is happening with the old SDKs?
23 +
24 +Currently, the new SDKs are in a preview release. These new SDKs come almost fully formed, we do not expect many breaking changes to them but are releasing them in a preview state to get feedback and make necessary changes before locking them in.
25 +
26 +As we lock the new SDKs in place, we will deprecate support for the old SDKs. They will continue to work for the foreseeable future but are no longer actively maintained. We will continue to push security updates and fix any critical bugs but will not support any new functionality in them.
27 +
28 +We urge you to upgrade to the new SDKs as soon as possible.
29 +
30 +## Nomenclature
31 +
32 +We have updated several key terms in the SDK and API to improve clarity and consistency. The following table summarizes these changes:
33 +
34 +| Previous Term | Current Term | Definition |
35 +|---------------|--------------------|--------------------------------------------------------------------------|
36 +| Actions | Tools | Individual operations or capabilities that can be performed by an LLM agent |
37 +| Apps | Toolkits | A collection of tools grouped under a single application |
38 +| Integration | Auth Config | Configuration containing developer credentials and application-level settings such as scopes and API endpoints. Scoped to a toolkit. |
39 +| Connection | Connected accounts | User-linked accounts associated with a toolkit |
40 +| Entity ID | User ID | The identifier of the user performing the action (UUID or email) |
41 +| Trigger | Trigger | An event that can be subscribed to |
42 +| Toolsets | Providers | LLM or agent framework that can be used with Composio to create agents |
43 +
44 +## Switch to nano IDs from UUIDs
45 +
46 +We have transitioned from UUIDs to nano IDs throughout the platform for the following reasons:
47 +
48 +- **Improved readability**: UUIDs are lengthy and difficult to read
49 +- **Better usability**: Easier to copy with a single double-click
50 +- **Better organization**: Nano IDs allow us to distinguish between different resource types through prefixes
51 +
52 +| Feature | Nano ID Prefix | Example |
53 +|-------------------|----------------|--------------------|
54 +| Connected Account | `ca_` | `ca_8x9w2l3k5m` |
55 +| Auth Config | `ac_` | `ac_1234567890` |
56 +| Trigger | `ti_` | `ti_So9EQf8XnAcy` |
57 +
58 +<Callout type="info">
59 +Nano IDs are short, unique, and prefixed to indicate the resource type.
60 +</Callout>
61 +
62 +## SDK Changes
63 +
64 +Upgrade to the latest SDK version using the appropriate package manager:
65 +
66 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
67 + <Tab value="Python">
68 +```bash
69 +pip install -U composio
70 +```
71 + </Tab>
72 + <Tab value="TypeScript">
73 +```bash
74 +npm install @composio/core
75 +```
76 + </Tab>
77 +</Tabs>
78 +
79 +Both SDKs now implement proper namespacing for each concept.
80 +
81 +### User ID scoping
82 +
83 +The concept of `entity_id` has been expanded and renamed to `user_id`.
84 +
85 +All operations are now scoped to a user ID, including:
86 +- Fetching tools
87 +- Initiating connections
88 +- Executing tools
89 +- Managing triggers
90 +
91 +This change provides explicit specification of the user for whom the action is being performed. When a user may have multiple accounts (such as work and personal Gmail connections), you can use the more specific connected account ID.
92 +
93 +### Replacing ToolSets with Providers
94 +
95 +We have deprecated "toolsets" in favor of "providers". This change allows Composio to provide deeper standardization for tool implementation across different frameworks.
96 +
97 +Previously, you needed to import and use a framework-specific `ComposioToolSet` class:
98 +
99 +<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>
100 + <Tab value="Python (previous)">
101 +```python
102 +from composio_openai import ComposioToolSet, Action, App
103 +from openai import OpenAI
104 +
105 +toolset = ComposioToolSet()
106 +```
107 + </Tab>
108 + <Tab value="TypeScript (previous)">
109 +```typescript
110 +import { OpenAIToolSet } from 'composio-core';
111 +
112 +const toolset = new OpenAIToolSet();
113 +```
114 + </Tab>
115 +</Tabs>
116 +
117 +The SDK structure is now framework-agnostic and includes the OpenAI provider out of the box:
118 +
119 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
120 + <Tab value="Python (current)">
121 +```python
122 +from composio import Composio
123 +# from composio_langchain import LangchainProvider
124 +
125 +composio = Composio()
126 +# composio = Composio(provider=LangchainProvider())
127 +
128 +tools = composio.tools.get(
129 + user_id="0001",
130 + tools=["LINEAR_CREATE_LINEAR_ISSUE", "GITHUB_CREATE_COMMIT"]
131 +)
132 +# tools returned is formatted for the provider. by default, OpenAI.
133 +```
134 + </Tab>
135 + <Tab value="TypeScript (current)">
136 +```typescript
137 +import { Composio } from '@composio/core';
138 +// import { VercelProvider } from '@composio/vercel';
139 +
140 +const composio = new Composio({
141 + // provider: new VercelProvider(),
142 +});
143 +// Can specify other providers too, like OpenAI, Anthropic, Vercel AI SDK.
144 +
145 +const tools = await composio.tools.get('user@example.com', {
146 + tools: ['LINEAR_CREATE_LINEAR_ISSUE', 'GITHUB_CREATE_COMMIT'],
147 +});
148 +// tools returned is formatted for the provider. by default, OpenAI.
149 +```
150 + </Tab>
151 +</Tabs>
152 +
153 +You can now use the same tools across any framework with our unified interface, or create custom toolsets for frameworks we don't yet support.
154 +
155 +Read more about [providers in our documentation](/docs/providers) and explore the [complete list of available providers](/providers/openai).
156 +
157 +### Fetching and filtering tools
158 +
159 +Previously, you could filter tools by:
160 +- Apps
161 +- Action names (tool names)
162 +- Tags
163 +
164 +You could also specify an `important` flag to retrieve the most important tools:
165 +
166 +<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>
167 + <Tab value="Python (previous)">
168 +```python
169 +from composio_openai import ComposioToolSet, Action, App
170 +from openai import OpenAI
171 +
172 +toolset = ComposioToolSet()
173 +client = OpenAI()
174 +
175 +tools = toolset.get_tools(
176 + actions=[Action.GITHUB_GET_THE_AUTHENTICATED_USER], check_connected_accounts=True
177 +)
178 +
179 +tools = toolset.get_tools(apps=[App.GITHUB, App.LINEAR, App.SLACK], check_connected_accounts=True)
180 +```
181 + </Tab>
182 + <Tab value="TypeScript (previous)">
183 +```typescript
184 +import { OpenAIToolSet } from 'composio-core';
185 +
186 +const toolset = new OpenAIToolSet();
187 +
188 +const tools_1 = await toolset.getTools({ apps: ['GITHUB'] });
189 +const tools_2 = await toolset.getTools({
190 + actions: ['GITHUB_GET_THE_AUTHENTICATED_USER', 'LINEAR_CREATE_LINEAR_ISSUE'],
191 +});
192 +```
193 + </Tab>
194 +</Tabs>
195 +
196 +You can now filter tools by:
197 +- Toolkits
198 +- Tool slugs
199 +- Limit parameter
200 +- Search query
201 +
202 +The `important` flag has been removed. Instead, tools are returned in order of importance by default:
203 +
204 +<Callout type="info">
205 +Since `user_id` is now explicitly required, the `check_connected_accounts` flag is no longer necessary.
206 +</Callout>
207 +
208 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
209 + <Tab value="Python (current)">
210 +```python
211 +from composio import Composio
212 +
213 +composio = Composio()
214 +
215 +user_id = "user@acme.org"
216 +
217 +tools_1 = composio.tools.get(user_id=user_id, toolkits=["GITHUB", "LINEAR"])
218 +
219 +tools_2 = composio.tools.get(user_id=user_id, toolkits=["SLACK"], limit=5) # Default limit=20
220 +
221 +tools_3 = composio.tools.get(
222 + user_id=user_id,
223 + tools=["GITHUB_CREATE_AN_ISSUE", "GITHUB_CREATE_AN_ISSUE_COMMENT", "GITHUB_CREATE_A_COMMIT"],
224 +)
225 +
226 +tools_4 = composio.tools.get(user_id="john", search="hackernews posts")
227 +```
228 + </Tab>
229 + <Tab value="TypeScript (current)">
230 +```typescript
231 +import { Composio } from '@composio/core';
232 +
233 +const userId = 'user@acme.org';
234 +
235 +const composio = new Composio();
236 +
237 +const tools_1 = await composio.tools.get(userId, {
238 + toolkits: ['GITHUB', 'LINEAR'],
239 +});
240 +
241 +const tools_2 = await composio.tools.get(userId, {
242 + toolkits: ['GITHUB'],
243 + limit: 5, // Default limit=20
244 +});
245 +
246 +const tools_3 = await composio.tools.get(userId, {
247 + tools: ['GITHUB_CREATE_AN_ISSUE', 'GITHUB_CREATE_AN_ISSUE_COMMENT', 'GITHUB_CREATE_A_COMMIT'],
248 +});
249 +
250 +const tools_4 = await composio.tools.get(userId, {
251 + search: 'hackernews posts',
252 +});
253 +```
254 + </Tab>
255 +</Tabs>
256 +
257 +### Fetching raw tool data
258 +
259 +To examine the raw schema definition of a tool for understanding input/output parameters or building custom logic around tool definitions, use the following methods:
260 +
261 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
262 + <Tab value="Python (current)">
263 +```python
264 +from composio import Composio
265 +
266 +composio = Composio()
267 +
268 +tool = composio.tools.get_raw_composio_tool_by_slug("HACKERNEWS_GET_LATEST_POSTS")
269 +
270 +print(tool.model_dump_json())
271 +```
272 + </Tab>
273 + <Tab value="TypeScript (current)">
274 +```typescript
275 +import { Composio } from '@composio/core';
276 +
277 +const composio = new Composio();
278 +
279 +const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_OCTOCAT');
280 +
281 +console.log(JSON.stringify(tool, null, 2));
282 +```
283 + </Tab>
284 +</Tabs>
285 +
286 +### Executing tools
287 +
288 +Tool execution remains largely unchanged, with `user_id` now explicitly required.
289 +
290 +For agentic frameworks, the tool object returned from `tools.get` is now the respective framework's native tool object. Tool call execution is handled by the agentic framework itself.
291 +
292 +<Callout type="info">
293 +For non-agentic frameworks, Composio provides a helper function to execute tool calls.
294 +</Callout>
295 +
296 +<Tabs groupId="language" items={['Python v3', 'TypeScript v3']} persist>
297 + <Tab value="Python v3">
298 +```python
299 +from composio import Composio
300 +from openai import OpenAI
301 +
302 +openai_client = OpenAI()
303 +composio = Composio()
304 +
305 +tools = composio.tools.get(user_id="user@acme.com", tools=["GITHUB_GET_THE_ZEN_OF_GITHUB"])
306 +response = openai_client.chat.completions.create(
307 + model="gpt-4.1",
308 + messages=[{"role": "user", "content": "gimme some zen."}],
309 + tools=tools,
310 +)
311 +
312 +result = composio.provider.handle_tool_calls(user_id="user@acme.com", response=response)
313 +print(result)
314 +```
315 + </Tab>
316 + <Tab value="TypeScript v3">
317 +```typescript
318 +import { Composio } from '@composio/core';
319 +import { AnthropicProvider } from '@composio/anthropic';
320 +import Anthropic from '@anthropic-ai/sdk';
321 +
322 +const anthropic = new Anthropic();
323 +const composio = new Composio({
324 + provider: new AnthropicProvider(),
325 +});
326 +
327 +const userId = 'user@example.com';
328 +const tools = await composio.tools.get(userId, {
329 + toolkits: ['GMAIL'],
330 +});
331 +
332 +const msg = await anthropic.messages.create({
333 + model: 'claude-3-7-sonnet-latest',
334 + tools: tools,
335 + messages: [
336 + {
337 + role: 'user',
338 + content: "Say hi to 'soham@composio.dev'",
339 + },
340 + ],
341 + max_tokens: 1024,
342 +});
343 +
344 +const result = await composio.provider.handleToolCalls(userId, msg);
345 +console.log('Tool results:', result);
346 +```
347 + </Tab>
348 +</Tabs>
349 +
350 +For more information on executing tools for different frameworks, see [Replacing ToolSets with Providers](#replacing-toolsets-with-providers).
351 +
352 +### Tool Modifiers (formerly Tool Processors)
353 +
354 +Tool processors have been renamed to *tool modifiers* and now provide an improved developer experience. The implementation is now available in TypeScript too! (previously Python-only).
355 +
356 +```python title="Python (previous)"
357 +from composio_openai import ComposioToolSet, Action
358 +
359 +toolset = ComposioToolSet()
360 +
361 +
362 +def my_schema_processor(schema: dict) -> dict: ...
363 +def my_preprocessor(inputs: dict) -> dict: ...
364 +def my_postprocessor(result: dict) -> dict: ...
365 +
366 +
367 +# Get tools with the modified schema
368 +processed_tools = toolset.get_tools(
369 + actions=[Action.GMAIL_SEND_EMAIL],
370 + processors={
371 + # Applied BEFORE the LLM sees the schema
372 + "schema": {Action.SOME_ACTION: my_schema_processor},
373 + # Applied BEFORE the tool executes
374 + "pre": {Action.SOME_ACTION: my_preprocessor},
375 + # Applied AFTER the tool executes, BEFORE the result is returned
376 + "post": {Action.SOME_ACTION: my_postprocessor},
377 + },
378 +)
379 +```
380 +
381 +| Previous | Current |
382 +|-------------------|-------------------------|
383 +| `pre` processor | `beforeExecute` modifier |
384 +| `post` processor | `afterExecute` modifier |
385 +| `schema` processor| `schema` modifier |
386 +
387 +The modifiers now leverage language-specific features to provide a more natural developer experience.
388 +
389 +While tool processors could previously be applied during SDK initialization, tool fetching, and tool execution, we have restructured them as follows:
390 +- **Chat Completion providers**: Modifiers are specified and applied during tool execution
391 +- **Agentic frameworks**: Modifiers are specified and applied during tool fetching
392 +
393 +#### Schema Modifiers
394 +
395 +The following example demonstrates schema modifier usage, applicable across all providers:
396 +
397 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
398 + <Tab value="Python (current)">
399 +```python
400 +from composio import Composio, schema_modifier
401 +from composio.types import Tool
402 +
403 +user_id = "your@email.com"
404 +
405 +@schema_modifier(tools=["HACKERNEWS_GET_LATEST_POSTS"])
406 +def modify_schema(
407 + tool: str,
408 + toolkit: str,
409 + schema: Tool,
410 +) -> Tool:
411 + _ = schema.input_parameters["properties"].pop("page", None)
412 + schema.input_parameters["required"] = ["size"]
413 + return schema
414 +
415 +tools = composio.tools.get(
416 + user_id=user_id,
417 + tools=["HACKERNEWS_GET_LATEST_POSTS", "HACKERNEWS_GET_USER"],
418 + modifiers=[
419 + modify_schema,
420 + ]
421 +)
422 +```
423 + </Tab>
424 + <Tab value="TypeScript (current)">
425 +```typescript
426 +import { Composio } from '@composio/core';
427 +import { OpenAI } from 'openai';
428 +
429 +const userId = 'your@email.com';
430 +const composio = new Composio();
431 +
432 +// Schema modifier to delete the `page` argument from the `HACKERNEWS_GET_LATEST_POSTS` tool
433 +const tools = await composio.tools.get(
434 + userId,
435 + {
436 + tools: ['HACKERNEWS_GET_LATEST_POSTS', 'HACKERNEWS_GET_USER'],
437 + },
438 + {
439 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
440 + if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
441 + const { inputParameters } = schema;
442 + if (inputParameters?.properties) {
443 + delete inputParameters.properties['page'];
444 + }
445 + inputParameters.required = ['size'];
446 + }
447 + return schema;
448 + },
449 + }
450 +);
451 +
452 +console.log(JSON.stringify(tools, null, 2));
453 +```
454 + </Tab>
455 +</Tabs>
456 +
457 +#### Before Modifiers
458 +
459 +The following example shows creating and using a before modifier for a Chat Completion provider. For agentic frameworks, view the [complete before modifier documentation](/docs/modify-tool-behavior/before-execution-modifiers):
460 +
461 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
462 + <Tab value="Python (current)">
463 +```python
464 +@before_execute(tools=["HACKERNEWS_GET_LATEST_POSTS"])
465 +def before_execute_modifier(
466 + tool: str,
467 + toolkit: str,
468 + params: ToolExecuteParams,
469 +) -> ToolExecuteParams:
470 + params["arguments"]["size"] = 1
471 + return params
472 +
473 +
474 +# Get tools
475 +tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_LATEST_POSTS")
476 +```
477 + </Tab>
478 + <Tab value="TypeScript (current)">
479 +```typescript
480 +const result_1 = await composio.tools.execute(
481 + 'HACKERNEWS_GET_LATEST_POSTS',
482 + {
483 + userId,
484 + arguments: JSON.parse(toolArgs),
485 + },
486 + {
487 + beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
488 + if (toolSlug === 'HACKERNEWS_GET_LATEST_POSTS') {
489 + params.arguments.size = 1;
490 + }
491 + console.log(params);
492 + return params;
493 + },
494 + }
495 +);
496 +```
497 + </Tab>
498 +</Tabs>
499 +
500 +#### After Modifiers
501 +
502 +The following example shows creating and using an after modifier for a Chat Completion provider. For agentic frameworks, view the [complete after modifier documentation](/docs/modify-tool-behavior/after-execution-modifiers):
503 +
504 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
505 + <Tab value="Python (current)">
506 +```python
507 +@after_execute(tools=["HACKERNEWS_GET_USER"])
508 +def after_execute_modifier(
509 + tool: str,
510 + toolkit: str,
511 + response: ToolExecutionResponse,
512 +) -> ToolExecutionResponse:
513 + return {
514 + **response,
515 + "data": {
516 + "karma": response["data"]["karma"],
517 + },
518 + }
519 +
520 +tools = composio.tools.get(user_id=user_id, slug="HACKERNEWS_GET_USER")
521 +```
522 + </Tab>
523 + <Tab value="TypeScript (current)">
524 +```typescript
525 +const result_2 = await composio.tools.execute(
526 + 'HACKERNEWS_GET_USER',
527 + {
528 + userId,
529 + arguments: JSON.parse(toolArgs),
530 + },
531 + {
532 + afterExecute: ({ toolSlug, toolkitSlug, result }) => {
533 + if (toolSlug === 'HACKERNEWS_GET_USER') {
534 + const { data } = result;
535 + const { karma } = data.response_data as { karma: number };
536 + return {
537 + ...result,
538 + data: { karma },
539 + };
540 + }
541 + return result;
542 + },
543 + }
544 +);
545 +```
546 + </Tab>
547 +</Tabs>
548 +
549 +### Custom Tools
550 +
551 +The SDK continues to support custom tools. [Creating tools from your methods](/docs/custom-tools#creating-a-custom-tool) remains possible. We recommend reviewing the [detailed custom tools documentation](/docs/custom-tools#creating-a-custom-tool) for more information.
552 +
553 +Due to changes in the SDK architecture, creating custom tools that use Composio's managed authentication has been modified. In the previous SDK, you could create a custom tool as follows:
554 +
555 +<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>
556 + <Tab value="Python (previous)">
557 +```python
558 +# Python Example using execute_request
559 +from composio import action, ComposioToolSet
560 +import typing as t
561 +
562 +toolset = ComposioToolSet()
563 +
564 +@action(toolname="github") # Associate with GitHub app for auth
565 +def get_github_repo_topics(
566 + owner: t.Annotated[str, "Repository owner username"],
567 + repo: t.Annotated[str, "Repository name"],
568 + execute_request: t.Callable # Injected by Composio
569 +) -> dict:
570 + """Gets the topics associated with a specific GitHub repository."""
571 + response_data = execute_request(
572 + endpoint=f"/repos/{owner}/{repo}/topics", # API path relative to base URL
573 + method="GET"
574 + )
575 + if isinstance(response_data, dict):
576 + return {"topics": response_data.get("names", [])}
577 +```
578 + </Tab>
579 + <Tab value="TypeScript (previous)">
580 +```typescript
581 +import { OpenAIToolSet, type ActionExecutionResDto } from "composio-core";
582 +import { z } from "zod";
583 +
584 +const toolset = new OpenAIToolSet();
585 +
586 +await toolset.createAction({
587 + actionName: "get_github_repo_topics",
588 + toolName: "github",
589 + description: "Gets the topics associated with a specific GitHub repository.",
590 + inputParams: z.object({
591 + owner: z.string().describe("Repository owner username"),
592 + repo: z.string().describe("Repository name"),
593 + }),
594 + callback: async (inputParams, _authCredentials, executeRequest): Promise<ActionExecutionResDto> => {
595 + const { owner, repo } = inputParams as { owner: string, repo: string };
596 + const response = await executeRequest({
597 + endpoint: `/repos/${owner}/${repo}/topics`,
598 + method: "GET",
599 + parameters: [],
600 + });
601 +
602 + const topics = (response as any)?.names ?? [];
603 + return { successful: true, data: { topics: topics } };
604 + }
605 +});
606 +```
607 + </Tab>
608 +</Tabs>
609 +
610 +The *execute tool request* method handles injection of the appropriate base URL and authentication credentials for the tool:
611 +
612 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
613 + <Tab value="Python (current)">
614 +```python
615 +from pydantic import BaseModel, Field
616 +from composio import Composio
617 +from composio.core.models.custom_tools import ExecuteRequestFn
618 +
619 +
620 +composio = Composio()
621 +
622 +class GetIssueInfoInput(BaseModel):
623 + issue_number: int = Field(
624 + ...,
625 + description="The number of the issue to get information about",
626 + )
627 +
628 +# function name will be used as slug
629 +@composio.tools.custom_tool(toolkit="github")
630 +def get_issue_info(
631 + request: GetIssueInfoInput,
632 + execute_request: ExecuteRequestFn,
633 + auth_credentials: dict,
634 +) -> dict:
635 + """Get information about a GitHub issue."""
636 + response = execute_request(
637 + endpoint=f"/repos/composiohq/composio/issues/{request.issue_number}",
638 + method="GET",
639 + parameters=[
640 + {
641 + "name": "Accept",
642 + "value": "application/vnd.github.v3+json",
643 + "type": "header",
644 + },
645 + {
646 + "name": "Authorization",
647 + "value": f"Bearer {auth_credentials['access_token']}",
648 + "type": "header",
649 + },
650 + ],
651 + )
652 + return {"data": response.data}
653 +```
654 + </Tab>
655 + <Tab value="TypeScript (current)">
656 +```typescript
657 +import { Composio } from "@composio/core";
658 +import z from "zod";
659 +
660 +const composio = new Composio();
661 +
662 +const tool = await composio.tools.createCustomTool({
663 + slug: 'GITHUB_STAR_COMPOSIOHQ_REPOSITORY',
664 + name: 'Github star composio repositories',
665 + toolkitSlug: 'github',
666 + description: 'Star any specificied repo of `composiohq` user',
667 + inputParams: z.object({
668 + repository: z.string().describe('The repository to star'),
669 + page: z.number().optional().describe('Pagination page number'),
670 + customHeader: z.string().optional().describe('Custom header'),
671 + }),
672 + execute: async (input, connectionConfig, executeToolRequest) => {
673 + const result = await executeToolRequest({
674 + endpoint: `/user/starred/composiohq/${input.repository}`,
675 + method: 'PUT',
676 + body: {},
677 + parameters: [
678 + {
679 + name: 'page',
680 + value: input.page?.toString() || '1',
681 + in: 'query',
682 + },
683 + {
684 + name: 'x-custom-header',
685 + value: input.customHeader || 'default-value',
686 + in: 'header',
687 + },
688 + ],
689 + });
690 + return result;
691 + },
692 + });
693 +```
694 + </Tab>
695 +</Tabs>
696 +
697 +For more information, including executing custom tools and defining custom headers and query parameters, refer to the [Custom Tools](/docs/custom-tools) documentation.
698 +
699 +### Auth configs (formerly integrations)
700 +
701 +Integrations are now called *auth configs*. While the terminology has changed, the underlying concept remains the same.
702 +
703 +Auth configs store the configuration required for authentication with a given toolkit, including OAuth developer credentials, configurable base URLs, and scopes.
704 +
705 +Auth configs now use nano IDs instead of UUIDs:
706 +
707 +| Previous (UUID) Example | Current (Nano ID) Example |
708 +| :----------------------------------- | :------------------------ |
709 +| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ac_8x9w2l3k5m` |
710 +
711 +We recommend storing auth config nano IDs in your database for connecting users to the appropriate auth configuration.
712 +
713 +For most use cases, you will create auth configs through the dashboard, and this process remains unchanged. Read more about [creating auth configs](/docs/authenticating-tools#creating-an-auth-config) and [customizing auth configs](/docs/custom-auth-configs).
714 +
715 +Creating auth configs programmatically in the previous SDK:
716 +
717 +<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>
718 + <Tab value="Python (previous)">
719 +```python
720 +from composio_openai import App, ComposioToolSet
721 +
722 +toolset = ComposioToolSet()
723 +
724 +integration = toolset.create_integration(
725 + app=App.GITHUB,
726 + auth_mode="OAUTH2",
727 + use_composio_oauth_app=True,
728 + # For use_composio_oauth_app=False, you can provide your own OAuth app credentials here
729 + # auth_config={
730 + # "client_id": "123456",
731 + # "client_secret": "123456"
732 + # }
733 +
734 +)
735 +print(integration.id)
736 +```
737 + </Tab>
738 + <Tab value="TypeScript (previous)">
739 +```typescript
740 +import { OpenAIToolSet } from "composio-core";
741 +
742 +const composioToolset = new OpenAIToolSet();
743 +
744 +const integration = await composioToolset.integrations.create({
745 + name: "gmail_integration",
746 + appUniqueKey: "gmail",
747 + forceNewIntegration: true,
748 + useComposioAuth: false,
749 + // For useComposioAuth: false, you can provide your own OAuth app credentials here
750 + // authScheme: "OAUTH2",
751 + // authConfig: {
752 + // clientId: "123456",
753 + // clientSecret: "123456"
754 + // }
755 +})
756 +
757 +console.log(integration.id)
758 +```
759 + </Tab>
760 +</Tabs>
761 +
762 +Creating auth configs programmatically in the current SDK:
763 +
764 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
765 + <Tab value="Python (current)">
766 +```python
767 +from composio import Composio
768 +
769 +composio = Composio()
770 +
771 +# Use composio managed auth
772 +auth_config = composio.auth_configs.create(
773 + toolkit="notion",
774 + options={
775 + "type": "use_composio_managed_auth",
776 + # "type": "use_custom_auth",
777 + # "auth_scheme": "OAUTH2",
778 + # "credentials": {
779 + # "client_id": "1234567890",
780 + # "client_secret": "1234567890",
781 + # "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",
782 + # },
783 + },
784 +)
785 +print(auth_config)
786 +```
787 + </Tab>
788 + <Tab value="TypeScript (current)">
789 +```typescript
790 +import { Composio } from '@composio/core';
791 +
792 +const composio = new Composio();
793 +
794 +const authConfig = await composio.authConfigs.create('LINEAR', {
795 + name: 'Linear',
796 + type: 'use_composio_managed_auth',
797 + // type: "use_custom_auth",
798 + // credentials: {
799 + // client_id: "1234567890",
800 + // client_secret: "1234567890",
801 + // oauth_redirect_uri: "https://backend.composio.dev/api/v3/toolkits/auth/callback",
802 + // },
803 +});
804 +
805 +console.log(authConfig);
806 +```
807 + </Tab>
808 +</Tabs>
809 +
810 +For using custom authentication credentials, refer to the [Programmatic Auth Configs](/docs/programmatic-auth-configs) documentation.
811 +
812 +<Callout type="info">
813 +The callback URL for creating custom OAuth configs is now `https://backend.composio.dev/api/v3/toolkits/auth/callback`. The previous URL was `https://backend.composio.dev/api/v1/auth-apps/add`.
814 +</Callout>
815 +
816 +### Connected accounts / User IDs
817 +
818 +The primary change in connected accounts and user IDs is that user IDs are now a more prominent concept compared to entities in previous versions.
819 +
820 +We have simplified the process of connecting a user to a toolkit. Instead of multiple methods and parameters for initiating a connection, both the SDK and API now require only a `user_id` and `auth_config_id` to initiate a connection.
821 +
822 +This approach is more explicit and works well with the ability for developers to have multiple auth configs for a given toolkit.
823 +
824 +Connected accounts now use nano IDs instead of UUIDs:
825 +
826 +| Previous (UUID) Example | Current (Nano ID) Example |
827 +| :----------------------------------- | :------------------------ |
828 +| `b7a9c1e2-3f4d-4a6b-8c2e-1d2f3a4b5c6d` | `ca_8x9w2l3k5m` |
829 +
830 +Previously, you might have initiated a connection like this:
831 +
832 +<Tabs groupId="language" items={['Python (previous)', 'TypeScript (previous)']} persist>
833 + <Tab value="Python (previous)">
834 +```python
835 +from composio_openai import ComposioToolSet
836 +
837 +toolset = ComposioToolSet()
838 +user_id = "your_user_unique_id"
839 +google_integration_id = "0000-0000"
840 +
841 +entity = toolset.get_entity(id=user_id)
842 +
843 +try:
844 + print(f"Initiating OAuth connection for entity {entity.id}...")
845 + connection_request = toolset.initiate_connection(
846 + integration_id=google_integration_id,
847 + entity_id=user_id,
848 + # Optionally add: redirect_url="https://yourapp.com/final-destination"
849 + # if you want user sent somewhere specific *after* Composio finishes.
850 + )
851 +
852 + # Check if a redirect URL was provided (expected for OAuth)
853 + if connection_request.redirectUrl:
854 + print(f"Received redirect URL: {connection_request.redirectUrl}")
855 + else:
856 + print("Error: Expected a redirectUrl for OAuth flow but didn't receive one.")
857 +
858 +
859 +except Exception as e:
860 + print(f"Error initiating connection: {e}")
861 +```
862 + </Tab>
863 + <Tab value="TypeScript (previous)">
864 +```typescript
865 +import { OpenAIToolSet } from "composio-core";
866 +
867 +const toolset = new OpenAIToolSet();
868 +const userId = "your_user_unique_id";
869 +const googleIntegrationId = "0000-0000";
870 +
871 +console.log(`Initiating OAuth connection for entity ${userId}...`);
872 +const connectionRequest = await toolset.connectedAccounts.initiate({
873 + integrationId: googleIntegrationId,
874 + entityId: userId,
875 + // Optionally add: redirectUri: "https://yourapp.com/final-destination"
876 + // if you want user sent somewhere specific *after* Composio finishes.
877 +});
878 +
879 +// Check if a redirect URL was provided (expected for OAuth)
880 +if (connectionRequest?.redirectUrl) {
881 + console.log(`Received redirect URL: ${connectionRequest.redirectUrl}`);
882 + // Proceed to Step 2: Redirect the user
883 + // Return or pass connectionRequest to the next stage
884 +} else {
885 + console.error("Error: Expected a redirectUrl for OAuth flow but didn't receive one.");
886 +}
887 +```
888 + </Tab>
889 +</Tabs>
890 +
891 +The current process for initiating a connection is as follows:
892 +
893 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
894 + <Tab value="Python (current)">
895 +```python
896 +from composio import Composio
897 +
898 +linear_auth_config_id = "ac_1234"
899 +user_id = "user@email.com"
900 +composio = Composio()
901 +
902 +# Create a new connected account
903 +connection_request = composio.connected_accounts.initiate(
904 + user_id=user_id,
905 + auth_config_id=linear_auth_config_id,
906 +)
907 +print(connection_request.redirect_url)
908 +
909 +# Wait for the connection to be established
910 +connected_account = connection_request.wait_for_connection()
911 +print(connected_account)
912 +```
913 + </Tab>
914 + <Tab value="TypeScript (current)">
915 +```typescript
916 +import { Composio } from "@composio/core";
917 +
918 +const composio = new Composio();
919 +const linearAuthConfigId = "ac_1234";
920 +const userId = "user@email.com";
921 +
922 +// Initiate the OAuth connection request
923 +const connRequest = await composio.connectedAccounts.initiate(userId, linearAuthConfigId);
924 +
925 +const { redirectUrl, id } = connRequest;
926 +console.log(redirectUrl);
927 +
928 +// Wait for the connection to be established
929 +await connRequest.waitForConnection();
930 +
931 +// If you only have the connection request ID, you can also wait using:
932 +await composio.connectedAccounts.waitForConnection(id);
933 +```
934 + </Tab>
935 +</Tabs>
936 +
937 +### Triggers
938 +
939 +Composio continues to support listening to application events using triggers through WebSockets and webhooks.
940 +
941 +#### Creating triggers
942 +
943 +The process for creating triggers and specifying their configuration has been redesigned for improved clarity and intuitiveness.
944 +
945 +Some triggers require configuration, such as repository names for GitHub triggers or channel names for Slack triggers. The process usually follows the pattern of fetching the trigger type and then creating the trigger with the appropriate configuration.
946 +
947 +<Tabs groupId="language" items={['Python (current)', 'TypeScript (current)']} persist>
948 + <Tab value="Python (current)">
949 +```python
950 +from composio import Composio
951 +
952 +composio = Composio()
953 +
954 +user_id = "user@example.com"
955 +trigger_config = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
956 +print(trigger_config.config)
957 +### Trigger Config
958 +# {
959 +# "properties": {
960 +# "owner": {
961 +# "description": "Owner of the repository",
962 +# "title": "Owner",
963 +# "type": "string"
964 +# },
965 +# "repo": {
966 +# "description": "Repository name",
967 +# "title": "Repo",
968 +# "type": "string"
969 +# }
970 +# },
971 +# "required": ["owner", "repo"],
972 +# "title": "WebhookConfigSchema",
973 +# "type": "object"
974 +
975 +trigger = composio.triggers.create(
976 + slug="GITHUB_COMMIT_EVENT",
977 + user_id=user_id,
978 + trigger_config={"repo": "composiohq", "owner": "composio"},
979 +)
980 +print(trigger)
981 +
982 +
983 +# Managing triggers
984 +
985 +composio.triggers.enable(id="ti_abcd123")
986 +```
987 + </Tab>
988 + <Tab value="TypeScript (current)">
989 +```typescript
990 +import { Composio } from '@composio/core';
991 +
992 +const composio = new Composio();
993 +
994 +const userId = 'user@acme.com';
995 +// Fetch the trigger details
996 +const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
997 +console.log(JSON.stringify(triggerType.config, null, 2));
998 +/*--- Trigger config ---
999 +{
1000 + "properties": {
1001 + "owner": {
1002 + "description": "Owner of the repository",
1003 + "title": "Owner",
1004 + "type": "string"
1005 + },
1006 + "repo": {
1007 + "description": "Repository name",
1008 + "title": "Repo",
1009 + "type": "string"
1010 + }
1011 + },
1012 + "required": ["owner", "repo"],
1013 + "title": "WebhookConfigSchema",
1014 + "type": "object"
1015 +}
1016 +*/
1017 +
1018 +const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {
1019 + triggerConfig: {
1020 + owner: 'composiohq',
1021 + repo: 'composio',
1022 + },
1023 +});
1024 +console.log(createResponse);
1025 +```
1026 + </Tab>
1027 +</Tabs>
1028 +
1029 +#### Enabling/Disabling triggers
1030 +
1031 +You can enable or disable triggers through either the SDK or the dashboard. The dashboard process remains unchanged.
1032 +
1033 +Managing triggers with the SDK:
1034 +
1035 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
1036 + <Tab value="Python">
1037 +```python
1038 +# Disable a trigger instance
1039 +disabled_instance = composio.triggers.disable(trigger_id="ti_abcd123")
1040 +print(disabled_instance)
1041 +```
1042 + </Tab>
1043 + <Tab value="TypeScript">
1044 +```typescript
1045 +await composio.triggers.disable("ti_abcd123");
1046 +```
1047 + </Tab>
1048 +</Tabs>
1049 +
1050 +If needed, the trigger can be enabled again.
1051 +
1052 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
1053 + <Tab value="Python">
1054 +```python
1055 +# Enable a trigger instance
1056 +enabled_instance = composio.triggers.enable(trigger_id="ti_abcd123")
1057 +print(enabled_instance)
1058 +```
1059 + </Tab>
1060 + <Tab value="TypeScript">
1061 +```typescript
1062 +await composio.triggers.enable("ti_abcd123");
1063 +```
1064 + </Tab>
1065 +</Tabs>
1066 +
1067 +#### Listening to triggers
1068 +
1069 +We recommend listening to triggers through webhooks. The following are example routes for Next.js and FastAPI.
1070 +
1071 +For development, you can also [listen to triggers through the SDK](/docs/using-triggers#subscribing-to-triggers-using-the-sdk-for-development).
1072 +
1073 +<Tabs items={['FastAPI', 'Next.js']}>
1074 + <Tab value="FastAPI">
1075 +```python title="app/route.py"
1076 +from fastapi import FastAPI, Request, HTTPException
1077 +from typing import Dict, Any
1078 +import uvicorn
1079 +import json
1080 +import hmac
1081 +import hashlib
1082 +import base64
1083 +import os
1084 +
1085 +def verify_webhook_signature(request: Request, body: bytes) -> bool:
1086 + """Verify Composio webhook signature"""
1087 + webhook_signature = request.headers.get("webhook-signature")
1088 + webhook_id = request.headers.get("webhook-id")
1089 + webhook_timestamp = request.headers.get("webhook-timestamp")
1090 + webhook_secret = os.getenv("COMPOSIO_WEBHOOK_SECRET")
1091 +
1092 + if not all([webhook_signature, webhook_id, webhook_timestamp, webhook_secret]):
1093 + raise HTTPException(status_code=400, detail="Missing required webhook headers or secret")
1094 +
1095 + if not webhook_signature.startswith("v1,"):
1096 + raise HTTPException(status_code=401, detail="Invalid signature format")
1097 +
1098 + received = webhook_signature[3:]
1099 + signing_string = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
1100 + expected = base64.b64encode(
1101 + hmac.new(webhook_secret.encode(), signing_string.encode(), hashlib.sha256).digest()
1102 + ).decode()
1103 +
1104 + if not hmac.compare_digest(received, expected):
1105 + raise HTTPException(status_code=401, detail="Invalid webhook signature")
1106 +
1107 + return True
1108 +
1109 +@app.post("/webhook")
1110 +async def webhook_handler(request: Request):
1111 + payload = await request.json()
1112 +
1113 + trigger_type = payload.get("type")
1114 + event_data = payload.get("data", {})
1115 +
1116 + if trigger_type == "github_star_added_event":
1117 + repo_name = event_data.get("repository_name")
1118 + starred_by = event_data.get("starred_by")
1119 + print(f"Repository {repo_name} starred by {starred_by}")
1120 + # Add your business logic here
1121 +
1122 + return {"status": "success", "message": "Webhook processed"}
1123 +```
1124 + </Tab>
1125 + <Tab value="Next.js">
1126 +```typescript title="app/api/webhook/route.ts"
1127 +import type { NextApiRequest, NextApiResponse } from 'next';
1128 +import { TriggerEvent } from '@composio/core';
1129 +import crypto from 'crypto';
1130 +
1131 +type GitHubStarEventData = {
1132 + repository_name: string;
1133 + repository_url: string;
1134 + starred_by: string;
1135 + starred_at: string;
1136 +};
1137 +
1138 +function verifyWebhookSignature(
1139 + req: NextApiRequest,
1140 + body: string
1141 +): boolean {
1142 + const signature = req.headers['webhook-signature'] as string | undefined;
1143 + const msgId = req.headers['webhook-id'] as string | undefined;
1144 + const timestamp = req.headers['webhook-timestamp'] as string | undefined;
1145 + const secret = process.env.COMPOSIO_WEBHOOK_SECRET;
1146 +
1147 + if (!signature || !msgId || !timestamp || !secret) {
1148 + throw new Error('Missing required webhook headers or secret');
1149 + }
1150 +
1151 + if (!signature.startsWith('v1,')) {
1152 + throw new Error('Invalid signature format');
1153 + }
1154 +
1155 + const received = signature.slice(3);
1156 + const signingString = `${msgId}.${timestamp}.${body}`;
1157 + const expected = crypto
1158 + .createHmac('sha256', secret)
1159 + .update(signingString)
1160 + .digest('base64');
1161 +
1162 + return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
1163 +}
1164 +
1165 +export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
1166 + const payload = req.body;
1167 +
1168 + if (payload.type === 'github_star_added_event') {
1169 + const event: TriggerEvent<GitHubStarEventData> = {
1170 + type: payload.type,
1171 + timestamp: payload.timestamp,
1172 + data: payload.data
1173 + };
1174 +
1175 + console.log(`Repository ${event.data.repository_name} starred by ${event.data.starred_by}`);
1176 + // Add your business logic here
1177 + }
1178 +
1179 + res.status(200).json({
1180 + status: 'success',
1181 + message: 'Webhook processed'
1182 + });
1183 +}
1184 +```
1185 + </Tab>
1186 +</Tabs>
1187 +
1188 +## Coming Soon
1189 +
1190 +### Local tools
1191 +
1192 +Previously, the Python SDK included *[local tools](https://github.com/ComposioHQ/composio/tree/master/python/composio/tools/local)*. These were tools defined within the SDK and consisted of local shell and code-related tools such as "clipboard", "sqltool", and "shelltool".
1193 +
1194 +This feature is currently in development for both Python and TypeScript SDKs, with newly created tools built for improved agent accuracy.
1195 +
1196 +This feature is currently in development for both Python and TypeScript SDKs.
1197 +
1198 +## API Endpoints
1199 +
1200 +The following table lists important API endpoints that have changed. You can use this reference to quickly find the new v3 API endpoint for migration:
1201 +
1202 +<Callout type="info">
1203 +This list is not exhaustive. Please refer to the [API Reference](/api-reference) for the complete list of endpoints.
1204 +</Callout>
1205 +
1206 +### Toolkits (formerly Apps)
1207 +
1208 +| Previous Endpoint | Current Endpoint |
1209 +| :--- | :--- |
1210 +| `GET /api/v1/apps` | `GET /api/v3/toolkits` |
1211 +| `GET /api/v1/apps/list/categories` | `GET /api/v3/toolkits/categories` |
1212 +| `GET /api/v1/apps/{appName}` | `GET /api/v3/toolkits/{slug}` |
1213 +
1214 +### Tools (formerly Actions)
1215 +
1216 +| Previous Endpoint | Current Endpoint |
1217 +| :--- | :--- |
1218 +| `GET /api/v2/actions` | `GET /api/v3/tools` |
1219 +| `GET /api/v2/actions/list/enums` | `GET /api/v3/tools/enum` |
1220 +| `GET /api/v2/actions/{actionId}` | `GET /api/v3/tools/{tool_slug}` |
1221 +| `POST /api/v2/actions/{actionId}/execute` | `POST /api/v3/tools/execute/{tool_slug}` |
1222 +| `POST /api/v2/actions/{actionId}/execute/get.inputs` | `POST /api/v3/tools/execute/{tool_slug}/input` |
1223 +| `POST /api/v2/actions/proxy` | `POST /api/v3/tools/execute/proxy` |
1224 +
1225 +### Auth Configs (formerly Integrations/Connectors)
1226 +
1227 +| Previous Endpoint | Current Endpoint |
1228 +| :--- | :--- |
1229 +| `GET /api/v1/integrations` | `GET /api/v3/auth_configs` |
1230 +| `POST /api/v1/integrations` | `POST /api/v3/auth_configs` |
1231 +| `GET /api/v1/integrations/{integrationId}` | `GET /api/v3/auth_configs/{nanoid}` |
1232 +| `PATCH /api/v1/integrations/{integrationId}` | `PATCH /api/v3/auth_configs/{nanoid}` |
1233 +| `DELETE /api/v1/integrations/{integrationId}` | `DELETE /api/v3/auth_configs/{nanoid}` |
1234 +| `POST /api/v2/integrations/create` | `POST /api/v3/auth_configs` |
1235 +
1236 +### Connected Accounts (formerly Connections)
1237 +
1238 +| Previous Endpoint | Current Endpoint |
1239 +| :--- | :--- |
1240 +| `GET /api/v1/connectedAccounts` | `GET /api/v3/connected_accounts` |
1241 +| `POST /api/v1/connectedAccounts` | `POST /api/v3/connected_accounts` |
1242 +| `POST /api/v2/connectedAccounts/initiateConnection` | `POST /api/v3/connected_accounts` |
1243 +| `GET /api/v1/connectedAccounts/{connectedAccountId}` | `GET /api/v3/connected_accounts/{nanoid}` |
1244 +| `DELETE /api/v1/connectedAccounts/{connectedAccountId}` | `DELETE /api/v3/connected_accounts/{nanoid}` |
1245 +| `POST /api/v1/connectedAccounts/{connectedAccountId}/disable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |
1246 +| `POST /api/v1/connectedAccounts/{connectedAccountId}/enable` | `PATCH /api/v3/connected_accounts/{nanoId}/status` |
1247 +| `POST /api/v1/connectedAccounts/{connectedAccountId}/reinitiate` | `POST /api/v3/connected_accounts/{nanoid}/refresh` |
1248 +
1249 +### Triggers
1250 +
1251 +| Previous Endpoint | Current Endpoint |
1252 +| :--- | :--- |
1253 +| `GET /api/v1/triggers` | `GET /api/v3/triggers_types` |
1254 +| `GET /api/v1/triggers/list/enums` | `GET /api/v3/triggers_types/list/enum` |
1255 +| `GET /api/v2/triggers/{triggerName}` | `GET /api/v3/triggers_types/{slug}` |
1256 +| `GET /api/v1/triggers/active_triggers` | `GET /api/v3/trigger_instances/active` |
1257 +| `POST /api/v1/triggers/enable/{connectedAccountId}/{triggerName}` | `POST /api/v3/trigger_instances/{slug}/upsert` |
1258 +| `DELETE /api/v1/triggers/instance/{triggerInstanceId}` | `DELETE /api/v3/trigger_instances/manage/{triggerId}` |
1259 +| `PATCH /api/v1/triggers/instance/{triggerId}/status` | `PATCH /api/v3/trigger_instances/manage/{triggerId}` |
fumadocs/content/docs/migration-guide/toolkit-versioning.mdx new
+157
@@ -0,0 +1,157 @@
1 +---
2 +title: Toolkit versioning migration
3 +description: Migrate to the new toolkit versioning system
4 +---
5 +
6 +Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.
7 +
8 +## Breaking change
9 +
10 +Manual tool execution now requires explicit version specification. The `tools.execute()` method will fail without a version.
11 +
12 +### Before (will fail)
13 +
14 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
15 + <Tab value="Python">
16 +```python
17 +# Raises ToolVersionRequiredError
18 +result = composio.tools.execute(
19 + "GITHUB_CREATE_ISSUE",
20 + {"user_id": "user-123", "arguments": {...}}
21 +)
22 +```
23 + </Tab>
24 + <Tab value="TypeScript">
25 +```typescript
26 +// Throws ComposioToolVersionRequiredError
27 +const result = await composio.tools.execute({
28 + toolSlug: "GITHUB_CREATE_ISSUE",
29 + userId: "user-123",
30 + arguments: {...}
31 +});
32 +```
33 + </Tab>
34 +</Tabs>
35 +
36 +### After (required)
37 +
38 +Choose one of three migration strategies:
39 +
40 +#### Option 1: Configure version at SDK level
41 +
42 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
43 + <Tab value="Python">
44 +```python
45 +from composio import Composio
46 +
47 +# Pin specific versions for each toolkit
48 +composio = Composio(
49 + api_key="YOUR_API_KEY",
50 + toolkit_versions={
51 + "github": "20251027_00",
52 + "slack": "20251027_00",
53 + "gmail": "20251027_00"
54 + }
55 +)
56 +```
57 + </Tab>
58 + <Tab value="TypeScript">
59 +```typescript
60 +import { Composio } from "@composio/core";
61 +
62 +// Pin specific versions for each toolkit
63 +const composio = new Composio({
64 + apiKey: "YOUR_API_KEY",
65 + toolkitVersions: {
66 + github: "20251027_00",
67 + slack: "20251027_00",
68 + gmail: "20251027_00"
69 + }
70 +});
71 +```
72 + </Tab>
73 +</Tabs>
74 +
75 +#### Option 2: Pass version with each execution
76 +
77 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
78 + <Tab value="Python">
79 +```python
80 +# Specify version directly in execute call
81 +result = composio.tools.execute(
82 + "GITHUB_LIST_STARGAZERS",
83 + arguments={
84 + "owner": "ComposioHQ",
85 + "repo": "composio"
86 + },
87 + user_id="user-k7334",
88 + version="20251027_00" # Override version for this execution
89 +)
90 +print(result)
91 +```
92 + </Tab>
93 + <Tab value="TypeScript">
94 +```typescript
95 +// Specify version directly in execute call
96 +const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
97 + userId: "user-k7334",
98 + arguments: {
99 + owner: "ComposioHQ",
100 + repo: "composio"
101 + },
102 + version: "20251027_00" // Override version for this execution
103 +});
104 +console.log(result);
105 +```
106 + </Tab>
107 +</Tabs>
108 +
109 +#### Option 3: Use environment variables
110 +
111 +```bash
112 +export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"
113 +```
114 +
115 +## Migration checklist
116 +
117 +1. **Audit your code**: Find all `tools.execute()` calls in your codebase
118 +2. **Choose a strategy**: Select one of the three options above based on your needs
119 +3. **Test thoroughly**: Verify tools work correctly with pinned versions
120 +4. **Deploy gradually**: Roll out changes incrementally to minimize risk
121 +
122 +## Temporary workaround
123 +
124 +During migration, you can temporarily skip version checks (not recommended for production):
125 +
126 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
127 + <Tab value="Python">
128 +```python
129 +result = composio.tools.execute(
130 + "GITHUB_CREATE_ISSUE",
131 + {
132 + "user_id": "user-123",
133 + "arguments": {...}
134 + },
135 + dangerously_skip_version_check=True
136 +)
137 +```
138 + </Tab>
139 + <Tab value="TypeScript">
140 +```typescript
141 +const result = await composio.tools.execute({
142 + toolSlug: "GITHUB_CREATE_ISSUE",
143 + userId: "user-123",
144 + arguments: {...},
145 + dangerouslySkipVersionCheck: true
146 +});
147 +```
148 + </Tab>
149 +</Tabs>
150 +
151 +<Callout type="warn">
152 +The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never use in production.
153 +</Callout>
154 +
155 +## Next steps
156 +
157 +For complete documentation on toolkit versioning, including best practices and advanced configuration, see [Toolkit versioning](/docs/toolkit-versioning).
fumadocs/content/docs/troubleshooting/api.mdx new
+18
@@ -0,0 +1,18 @@
1 +---
2 +title: API
3 +description: Troubleshooting API issues
4 +---
5 +
6 +## Reporting API issues
7 +
8 +When reporting API issues to support, provide the following:
9 +
10 +- **cURL command**: Include the exact cURL to reproduce the issue
11 +- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))
12 +- **Error details**: Share the complete error message
13 +- **Reproduction steps**: Include any steps needed to reproduce the issue
14 +
15 +## Getting help
16 +
17 +- **Email**: support@composio.dev
18 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/authentication.mdx new
+43
@@ -0,0 +1,43 @@
1 +---
2 +title: Authentication
3 +description: Troubleshooting authentication issues
4 +---
5 +
6 +## Using Composio's default OAuth app
7 +
8 +When using our default OAuth configuration:
9 +
10 +- **Don't add additional scopes** - They may not be approved in our OAuth app
11 +- Use only the pre-configured scopes provided
12 +
13 +## Using custom OAuth apps
14 +
15 +Ensure your OAuth app is configured correctly:
16 +
17 +- **Redirect URL**: Must match exactly what's configured in your OAuth provider
18 +- **Scopes**: Auth config scopes must match your OAuth app configuration
19 +- **Credentials**: Verify client ID and secret are correct
20 +
21 +For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)
22 +
23 +## Common authentication issues
24 +
25 +- **Invalid redirect URI**: Check the callback URL matches exactly
26 +- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app
27 +- **Expired tokens**: Try refreshing the connection
28 +- **Rate limits**: Some providers limit authentication attempts
29 +- **Credentials showing as `REDACTED`**: The "Mask Connected Account Secrets" setting is enabled on your account, which redacts all sensitive credential data. Navigate to **Settings → Project Settings → Project Configuration** and disable "Mask Connected Account Secrets" to view actual values
30 +
31 +## Reporting authentication issues
32 +
33 +When reporting to support, provide:
34 +
35 +- **Error message**: Complete error details and screenshots
36 +- **Auth config ID**: The `authConfigId` being used
37 +- **Connected account ID**: If a connection was already created
38 +- **OAuth provider**: Which service you're trying to connect
39 +
40 +## Getting help
41 +
42 +- **Email**: support@composio.dev
43 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/cli.mdx new
+91
@@ -0,0 +1,91 @@
1 +---
2 +title: CLI
3 +description: Troubleshooting CLI issues
4 +---
5 +
6 +## Command not found
7 +
8 +Verify the CLI is installed and in your PATH:
9 +
10 +```bash
11 +which composio
12 +```
13 +
14 +If not found, reinstall:
15 +
16 +```bash
17 +curl -fsSL https://composio.dev/install | bash
18 +```
19 +
20 +Or add to PATH:
21 +
22 +```bash
23 +echo 'export PATH="$HOME/.composio:$PATH"' >> ~/.bashrc && source ~/.bashrc
24 +```
25 +
26 +## Authentication errors
27 +
28 +Check current authentication:
29 +
30 +```bash
31 +composio whoami
32 +```
33 +
34 +Re-authenticate if needed:
35 +
36 +```bash
37 +composio logout
38 +composio login
39 +```
40 +
41 +For CI/CD, use environment variable:
42 +
43 +```bash
44 +export COMPOSIO_API_KEY="your-api-key"
45 +```
46 +
47 +## Type generation issues
48 +
49 +### Project type not detected
50 +
51 +Use language-specific commands:
52 +
53 +```bash
54 +composio ts generate # TypeScript
55 +composio py generate # Python
56 +```
57 +
58 +### Output directory missing
59 +
60 +Specify output directory explicitly:
61 +
62 +```bash
63 +composio generate --output-dir ./my-types
64 +```
65 +
66 +## Debug CLI issues
67 +
68 +Enable debug logging:
69 +
70 +```bash
71 +composio --log-level debug [command]
72 +```
73 +
74 +Check version compatibility:
75 +
76 +```bash
77 +composio version
78 +```
79 +
80 +## Common issues
81 +
82 +- **API key not found**: Run `composio login`
83 +- **Project type detection fails**: Use language-specific commands or ensure you're in project root
84 +- **Network timeout**: Check internet connection and proxy settings
85 +- **Permission denied**: Check directory write permissions
86 +
87 +## Getting help
88 +
89 +- **Email**: support@composio.dev
90 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
91 +- **GitHub**: [Create an issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug)
fumadocs/content/docs/troubleshooting/dashboard.mdx new
+20
@@ -0,0 +1,20 @@
1 +---
2 +title: Dashboard
3 +description: Troubleshooting dashboard issues
4 +---
5 +
6 +## Reporting dashboard issues
7 +
8 +When reporting dashboard issues to support, provide:
9 +
10 +- **Screenshot or recording**: Visual evidence of the issue
11 +- **Error details**: Complete error message shown in the UI
12 +- **Network logs**: Check browser DevTools for failing API calls and share:
13 + - Error message
14 + - Request ID (`x-request-id` header)
15 + - Failed endpoint URL
16 +
17 +## Getting help
18 +
19 +- **Email**: support@composio.dev
20 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/index.mdx new
+31
@@ -0,0 +1,31 @@
1 +---
2 +title: Troubleshooting
3 +description: Common issues and quick links
4 +---
5 +
6 +import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';
7 +
8 +This section is designed to help you quickly identify and resolve common issues encountered with Composio.
9 +
10 +Some quick links:
11 +
12 +<Cards>
13 + <Card title="Report issues" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug" icon={<Bug />}>
14 + Found a bug? Please create a Github issue!
15 + </Card>
16 + <Card title="Ask AI" href="https://deepwiki.com/ComposioHQ/composio" icon={<Brain />}>
17 + Try to use Ask AI in the docs or deepwiki to get the fastest responses on features, types, and best practices.
18 + </Card>
19 + <Card title="Feature requests" href="https://github.com/ComposioHQ/composio/issues/new?labels=enhancement" icon={<Sparkles />}>
20 + Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests
21 + </Card>
22 + <Card title="Ask the community" href="https://github.com/ComposioHQ/composio/discussions" icon={<MessageCircle />}>
23 + Join our GitHub discussions to get help from the community
24 + </Card>
25 + <Card title="Discord community" href="https://discord.com/channels/1170785031560646836/1268871288156323901" icon={<MessageSquare />}>
26 + Post support queries on our discord channel or reach out to support@composio.dev
27 + </Card>
28 + <Card title="Migration guides" href="/docs/migration-guide" icon={<BookOpen />}>
29 + Check out our migration guides to help you upgrade to the latest version.
30 + </Card>
31 +</Cards>
fumadocs/content/docs/troubleshooting/mcp.mdx new
+48
@@ -0,0 +1,48 @@
1 +---
2 +title: MCP
3 +description: Troubleshooting MCP server issues
4 +---
5 +
6 +## Connected account not found error
7 +
8 +This error occurs when MCP cannot find a valid connected account for authentication:
9 +
10 +- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration
11 +- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used
12 +- **Verification checklist**:
13 + - Account status is `ACTIVE` (not deleted)
14 + - Account belongs to the same auth config used to create the MCP server
15 +
16 +Learn more: [MCP Quickstart](/docs/mcp-quickstart)
17 +
18 +## Getting 404 errors
19 +
20 +Verify your URL format matches one of these patterns:
21 +
22 +- `https://mcp.composio.dev/composio/server/<UUID>/mcp`
23 +- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/<UUID>`
24 +- `https://apollo.composio.dev/v3/mcp/<UUID>`
25 +
26 +## Testing and debugging
27 +
28 +If experiencing issues, test your MCP server with:
29 +
30 +- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)
31 +- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
32 +
33 +This helps identify whether the issue is with your MCP client or the server.
34 +
35 +## Reporting MCP issues
36 +
37 +When reporting to support, provide:
38 +
39 +- **Error message**: Complete error details
40 +- **MCP server URL**: The exact URL you're connecting to
41 +- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client
42 +- **Connected account ID**: If facing connection issues
43 +- **Reproduction steps**: Clear steps to reproduce the issue
44 +
45 +## Getting help
46 +
47 +- **Email**: support@composio.dev
48 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/meta.json new
+14
@@ -0,0 +1,14 @@
1 +{
2 + "title": "Troubleshooting",
3 + "pages": [
4 + "index",
5 + "api",
6 + "authentication",
7 + "cli",
8 + "dashboard",
9 + "mcp",
10 + "sdks",
11 + "tools",
12 + "triggers"
13 + ]
14 +}
fumadocs/content/docs/troubleshooting/sdks.mdx new
+55
@@ -0,0 +1,55 @@
1 +---
2 +title: SDKs
3 +description: Troubleshooting SDK issues
4 +---
5 +
6 +## Debug network issues
7 +
8 +Enable debug logging to see API calls and identify if issues are SDK or API related. Look for the `x-request-id` in logs to share with support.
9 +
10 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
11 + <Tab value="Python">
12 +```bash
13 +# Set environment variable
14 +COMPOSIO_LOGGING_LEVEL=debug
15 +```
16 + </Tab>
17 + <Tab value="TypeScript">
18 +```bash
19 +// Set environment variable
20 +COMPOSIO_LOG_LEVEL=debug
21 +```
22 + </Tab>
23 +</Tabs>
24 +
25 +## Check SDK version
26 +
27 +Ensure you're using the latest version:
28 +
29 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
30 + <Tab value="Python">
31 +```bash
32 +pip install --upgrade composio
33 +```
34 + </Tab>
35 + <Tab value="TypeScript">
36 +```bash
37 +npm install @composio/core@latest
38 +```
39 + </Tab>
40 +</Tabs>
41 +
42 +Check current version:
43 +- Python: [PyPI](https://pypi.org/project/composio/)
44 +- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)
45 +
46 +## Common issues
47 +
48 +- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant
49 +- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits/introduction)
50 +- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps
51 +
52 +## Getting help
53 +
54 +- **Email**: support@composio.dev
55 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/tools.mdx new
+52
@@ -0,0 +1,52 @@
1 +---
2 +title: Tools & Toolkits
3 +description: Troubleshooting tool execution issues
4 +---
5 +
6 +## Tool execution failures (401/403 errors)
7 +
8 +Authentication and permission errors typically occur due to:
9 +
10 +### Missing scopes
11 +
12 +Check if your connection has the required scopes using this API:
13 +
14 +```bash
15 +curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \
16 +--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
17 +--header 'Content-Type: application/json' \
18 +--data '{
19 + "tools": [
20 + "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",
21 + "SLACK_CREATE_A_REMINDER"
22 + ]
23 +}'
24 +```
25 +
26 +### Insufficient permissions
27 +
28 +Verify the connected account has necessary permissions:
29 +
30 +- **Admin requirements**: Some tools require admin-level access
31 +- **Paid accounts**: Certain toolkits need paid subscriptions
32 + - Example: MS Teams requires Microsoft 365 account + Azure AD tenant
33 +
34 +## Tool not working
35 +
36 +- Check [tool-specific documentation](/toolkits/introduction) for requirements
37 +- Verify the connected account is active and properly authenticated
38 +- Test with the latest SDK version
39 +
40 +## Reporting tool issues
41 +
42 +When reporting to support, provide:
43 +
44 +- **Error message**: Complete error details
45 +- **Log ID**: From the error response
46 +- **Tool name**: Exact tool slug being executed
47 +- **Connected account ID**: Account used for execution
48 +
49 +## Getting help
50 +
51 +- **Email**: support@composio.dev
52 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/content/docs/troubleshooting/triggers.mdx new
+33
@@ -0,0 +1,33 @@
1 +---
2 +title: Triggers
3 +description: Troubleshooting trigger issues
4 +---
5 +
6 +## Unable to create trigger
7 +
8 +Check the error message - the account might not have sufficient permissions or required scopes.
9 +
10 +## Type errors with trigger payloads
11 +
12 +Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.
13 +
14 +## Not receiving trigger payloads
15 +
16 +Even if the action occurred (email received, Jira issue created, etc.), there may be delays:
17 +
18 +- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
19 +- **Other services**: May have their own polling intervals or webhook delivery delays
20 +
21 +## Reporting trigger issues
22 +
23 +When reporting to support, provide:
24 +
25 +- **Error message**: Complete error details
26 +- **Connected account**: The account ID used for creating the trigger
27 +- **cURL command**: To reproduce the issue
28 +- **Reproduction steps**: Any additional steps needed
29 +
30 +## Getting help
31 +
32 +- **Email**: support@composio.dev
33 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
fumadocs/public/images/debugging-info.png
Binary files /dev/null and b/fumadocs/public/images/debugging-info.png differ
fumadocs/public/images/project-settings.jpeg
Binary files /dev/null and b/fumadocs/public/images/project-settings.jpeg differ