Introduction
The moment you wire an AI agent into the apps you actually use — Gmail, Slack, HubSpot, Google Drive, Salesforce, Figma — it stops being a chatbot and starts being something that gets work done. The catch is that connecting a dozen tools through native integrations is painful: each one wants its own OAuth, you’re usually capped to a single account per service, and the moment you cross five or six connectors, your model starts choking on its own tool list.
This guide walks through Composio, a single connector that fronts more than a thousand applications behind one MCP endpoint. Instead of bolting on 50 integrations one at a time, you authenticate everything once on Composio’s dashboard, drop a single URL into Claude, Codex, Cursor, or OpenClaw, and let the agent search for tools on demand. We’ll cover why native connectors break at scale, how on-demand tool discovery fixes it, how to set everything up, and the pricing math that makes the free tier viable for most teams.
📚 Table of contents
- Why native connectors break at scale
- The context-bloat problem in plain English
- What Composio is and how on-demand tool discovery works
- Step-by-step setup — from sign-up to first tool call
- Wiring Composio into Claude (Chat, Code, Coworker)
- A real example: email summary → Google Doc → Drive link
- Permissions and safety: read vs write vs delete
- Pricing and free-tier limits
- Best practices for production agents
- Common mistakes
- Frequently asked questions
🔌 Why native connectors break at scale
Every major AI tool now ships a directory of officially approved connectors — Anthropic has them in Claude, OpenAI has them in ChatGPT, Google has them in Gemini. For one or two integrations they work fine. The cracks show up the moment you try to run an agent that lives across your stack.
❌ One account per service
Most native connectors only let you authenticate a single account. If you have five Gmail inboxes or three Google Drives, four of them are invisible to the agent.
❌ Per-tool re-authentication
Switching from Claude to Codex to Cursor means redoing every OAuth flow inside each tool. Auth tokens expire, sessions break, and you spend half your day signing back in.
❌ Context bloat
Every connected tool injects its full list of available functions into the system prompt. Ten connectors with 50 tools each is 500 tool definitions on every single call.
❌ Worse tool-calling accuracy
Models perform measurably worse when given hundreds of tools to choose from. The right tool gets lost in the noise and the agent picks something close-but-wrong.
🎈 The context-bloat problem in plain English
Imagine handing a contractor a wrench, a screwdriver, and a hammer. They pick the right one every time. Now hand them a 500-piece toolbox with similar-looking variants of each. They’ll still finish the job, but slower, with more mistakes, and after asking you twice which one you meant.
LLMs work the same way. Tool definitions live in the system prompt — the immutable preamble sent on every single call. With 500 tools loaded, you pay for those input tokens on every request, your latency climbs, and your tool-selection accuracy drops. This isn’t a quirk; it’s well-documented behavior across every frontier model.
📊 What you pay when context bloats
- Higher input tokens on every call — even when the agent doesn’t use any tool
- Lower accuracy as the model picks similar-sounding tools incorrectly
- More latency because larger prompts take longer to process
- Faster context-window exhaustion in long conversations
🧩 What Composio is and how on-demand tool discovery works
Composio is a managed connector that aggregates more than a thousand SaaS integrations — Gmail, Slack, HubSpot, Notion, Asana, LinkedIn, DocuSign, Reddit, Twitter, Monday, YouTube, Serp, Instagram, and on and on — behind a single MCP endpoint. You authenticate each service once on the Composio dashboard, and your agent gets one connector to rule them all.
The clever part is what Composio doesn’t do: it doesn’t hand your model the full list of available tools. Instead, it exposes a tiny set of meta-tools (search, get schema, execute) and lets the agent search semantically for the right tool when it actually needs one. The model sees roughly seven primitives instead of seven hundred.
🔁 The on-demand discovery flow
- User asks: “Send a recap email to the team about today’s standup.”
- Agent calls the one tool exposed to it:
search_tools. - Composio runs semantic search across its internal catalog and returns a short, targeted list.
- Agent picks the right tool (say,
gmail.send_email) and calls it through Composio. - Composio executes against the real service using stored auth, then trims the response before returning it.
Two side benefits fall out of this design. First, Composio handles token refresh, so you never see the expired-session errors that haunt native connectors. Second, the same configuration works across every agent you point at it — switching from Claude to Codex to Cursor doesn’t require redoing a single OAuth.
🛠️ Step-by-step setup
The whole flow takes about ten minutes the first time and a minute every time you add a new service.
1️⃣ Sign up for Composio
Head to composio.dev, create a free account, and skip past the optional onboarding into the main dashboard.
2️⃣ Connect your apps
Click Connect apps, pick a service (start with Gmail), and walk through the OAuth flow. Composio stores the session tokens and auto-refreshes them. Repeat for each app you want the agent to reach — thirty to forty connections is normal.
3️⃣ Connect multiple accounts per service
Inside each service’s page (e.g. Gmail), you can add more than one account and label each one. This is the feature native connectors can’t match — your agent can now read the founder inbox, the support inbox, and your personal mailbox in the same call.
🔗 Wiring Composio into Claude
Composio publishes a one-line MCP URL for each of the major AI tools — Claude Code, Claude Coworker, OpenClaw, ChatGPT, Codex, Cursor. The setup pattern is the same everywhere; we’ll use Claude Coworker as the example.
Add the connector inside Claude
- Open Claude (chat or Coworker), go to Settings → Connectors.
- Click Add custom connector.
- Name it
Composio. - Paste the MCP URL from Composio’s Claude Coworker setup page.
- Click Add, then Connect. A browser tab opens for Composio authorization — click Authorize.
Once connected, click into the connector and you’ll see a handful of exposed tools:
search_tools,
get_tool_schemas,
multi_execute_tool,
manage_connections,
wait_for_connections,
and a couple more. That’s the entire surface area — everything else is reached through them.
📨 A real example: email → Doc → Drive link
Here’s the kind of multi-tool task that breaks under native connectors and works smoothly through Composio. Two prompts, two tools, one cross-app workflow.
Prompt 1 — summarize the inbox
“Using Composio, go to my email, find the latest three emails, and give me a summary — high-level points and anything I need to know.”
The agent calls search_tools, finds
gmail.fetch_emails, asks for approval, and
returns the summary.
Prompt 2 — stack tools across apps
“Now write a Google Doc with that summary, save it to my Drive, and send me the link. Use Composio for all tool calls.”
If Google Docs isn’t connected yet, Composio surfaces a link inside the chat so you can authorize it on the fly, then continues the task. No restart, no separate auth tab.
📌 Tip: explicitly mention “use Composio” in your prompt the first few times. The connector name isn’t self-descriptive, and the agent occasionally tries to default to a native tool. Once it sees the pattern in the conversation, it stops needing the hint.
🛡️ Permissions: read vs write vs delete
Once Composio is connected, Claude lets you set approval rules per tool category. This is the layer most people skip and regret later.
📖 Read — always allow
Safe to auto-approve. Search inboxes, list contacts, fetch documents. The blast radius is reading data you already own.
✍️ Write — needs approval
Sending emails, creating docs, posting to Slack. Approve per task. The model occasionally composes things you didn’t expect — you want eyes on those.
🗑️ Delete — needs approval
Removing files, deleting messages, dropping records. Always confirm. There’s no undo button on a misfired delete in production data.
💰 Pricing and free-tier limits
Composio bills on tool calls, not connected services. Most solo developers and small teams never leave the free tier.
| Plan | Tool calls / month | Price |
|---|---|---|
| Free | 20,000 | $0 |
| Starter | 200,000 | $29 |
| Pro | 2,000,000 | Custom |
20,000 tool calls a month is a lot. A heavy daily user running a dozen agent workflows rarely cracks half that. If you do need more, the $29 tier covers 200,000 calls — small money compared to the LLM bill you’re already paying.
✅ Best practices for production agents
- Separate orgs by purpose. Composio supports multiple organizations — keep personal connections separate from production agent connections.
- Name your accounts clearly. “founder@”, “support@”, “personal” — future-you reviewing logs will thank present-you.
- Keep write/delete gated. Always-allow on read, approval on write and delete. The agent will still fly, just with a brief pause before destructive actions.
- Watch the call log. Composio shows you a running log of every tool invocation. Review it weekly — you’ll spot agents that loop, retry, or pick wrong tools.
- Be selective about connected apps. More connections = more attack surface. Only authenticate apps the agent actually needs.
- Re-use the same Composio account across tools. Adding Claude, Codex, and Cursor on top of the same account means one place to revoke or rotate access.
❌ Common mistakes
- Connecting Composio and the native connectors for the same service — you reintroduce the bloat you came here to escape
- Skipping the per-tool approval rules and waking up to discover the agent emailed half the company
- Stuffing 50 apps into Composio before you know which the agent will actually use — start with five and add as needed
- Forgetting that the agent needs a hint to prefer Composio early on (“use Composio”)
- Treating tool-call counts as free — cheap, yes, free, no. Watch the meter on long-running agent loops
- Connecting only one Gmail account when multi-account is the whole point
Conclusion
Native connectors are fine when you’re running one or two integrations. The moment your agent needs to live across a real stack, they fall apart on three fronts: single-account limits, context bloat, and per-tool auth churn. Composio fixes all three with one design decision — expose a small set of meta-tools, let the agent search for the right one at the moment it needs it, and keep the actual integrations behind a managed dashboard.
Spend ten minutes wiring it into whichever agent you use most. Connect five apps. Run a single cross-tool workflow end-to-end. Once you’ve seen on-demand discovery work, going back to bolting on connectors one at a time feels like a downgrade.
Related reading: MCP explained: build your own server — Claude ecosystem guide (Chat, Code & Desktop) — Claude AI review
Explore More on DevShelf
-
MCP Explained: Build Your Own Server
Understand the Model Context Protocol that Composio exposes — and how to build a custom MCP server beyond the 1,000+ pre-built connectors.
-
Learn Agentic AI in 7 Steps
The broader path — where Composio-style tool connectors sit in the production agentic AI stack from Step 2 onwards.