Skip to content

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

docs(composio-connect): add overview, available MCP tools, and troubleshooting

Shawn Esquiveld2a1b5fbe051
diff --git a/docs/content/docs/composio-connect.mdx b/docs/content/docs/composio-connect.mdx
index 3457b3f48..07472e71d 100644
--- a/docs/content/docs/composio-connect.mdx
+++ b/docs/content/docs/composio-connect.mdx
@@ -6,6 +6,14 @@ keywords: [composio connect, mcp, claude code, cursor, vscode, windsurf, cline,
Give any AI agent the ability to act across 1000+ apps. Bring your agent to where you work.
+## How Composio Connect works
+
+Composio Connect is an MCP server at `https://connect.composio.dev/mcp` that gives your AI agent access to 1000+ apps — Gmail, Notion, Slack, GitHub, Linear, HubSpot, Strava, and more — through a single connection.
+
+Rather than exposing every app tool directly, Composio exposes **7 meta-tools** that let the agent discover what's available, authorize apps on demand, and execute tools across apps in parallel. The first time your agent needs an app, Composio generates an OAuth link you approve in your browser; after that the connection persists across sessions. See [Available MCP tools](#available-mcp-tools) for the full list.
+
+To get started, pick your client below.
+
<ConnectFlow>
<ConnectClientOption id="claude-code" name="Claude Code" description="Terminal-based AI with MCP tools" icon="/images/clients/claude.svg" category="popular">
@@ -467,6 +475,46 @@ Use this config with any MCP-compatible client:
</ConnectFlow>
-### Connect your apps
+## Connect your apps
Your agent will prompt you to connect apps when needed. If you want to connect apps ahead of time, open the [Composio dashboard](https://dashboard.composio.dev) and click **Connect Apps** in the sidebar.
+
+## Available MCP tools
+
+Composio Connect exposes 7 meta-tools that orchestrate access to all supported apps. Your agent uses these to discover, connect, and execute upstream tools — you don't need to call them directly.
+
+- **`COMPOSIO_SEARCH_TOOLS`** — Search the Composio catalog and return relevant tools for a user request, along with a suggested execution plan.
+- **`COMPOSIO_GET_TOOL_SCHEMAS`** — Fetch full input schemas for tool slugs returned by search.
+- **`COMPOSIO_MULTI_EXECUTE_TOOL`** — Execute one or more discovered tools in parallel across connected apps (up to 50 per call).
+- **`COMPOSIO_MANAGE_CONNECTIONS`** — Create, list, rename, or remove OAuth connections to upstream apps.
+- **`COMPOSIO_WAIT_FOR_CONNECTIONS`** — Wait for a user to complete an OAuth flow before the agent continues.
+- **`COMPOSIO_REMOTE_WORKBENCH`** — Run Python in a remote sandbox for bulk operations or processing large tool responses.
+- **`COMPOSIO_REMOTE_BASH_TOOL`** — Run bash in a remote sandbox for file processing and large data handling.
+
+## Troubleshooting
+
+### Tools aren't appearing in my agent
+
+1. Confirm the MCP server is connected. In Claude Desktop, go to **Settings > Connectors** and check that Composio shows a `CUSTOM` badge. In Claude Code, run `/mcp` and confirm Composio is enabled.
+2. Clear the connector cache. In Claude Desktop: click the **⋮** next to Composio and select **Clear cache**.
+3. If the issue persists, disconnect and re-add the connector:
+ - **Claude Desktop** — click **⋮ > Disconnect**, then **Remove**. Re-add via **Add custom connector**.
+ - **Claude Code** — re-run the setup command from the Claude Code section above.
+
+### The OAuth link expired or didn't open
+
+OAuth links are short-lived. If the browser window doesn't open or the link has expired, ask your agent to retry the action — Composio will generate a fresh link. You can also open the [Composio dashboard](https://dashboard.composio.dev), click **Connect Apps**, and start the flow manually.
+
+### An app action is failing with an auth error
+
+1. Open the [Composio dashboard](https://dashboard.composio.dev) and click **Connect Apps**.
+2. Find the app in question. If the connection is unhealthy, click **Disconnect** and reconnect.
+3. Retry the action in your agent.
+
+### I want to remove or reconnect an app
+
+Open [dashboard.composio.dev](https://dashboard.composio.dev) and click **Connect Apps**. From there you can disconnect, delete, or re-authorize any app.
+
+### I still need help
+
+Reach out at [[email protected]](mailto:[email protected]) or join the [Composio Discord](https://discord.com/invite/cNruWaAhQk).