Connecting External Tools with Composio MCP
You'll never copy-paste between Gmail, Notion, and Slack again. MCP gives Claude Code hands — this guide shows you how to attach them in one command.
What is MCP, in plain English
MCP — the common language AI agents use to talk to your tools
MCP stands for Model Context Protocol — an open standard published by Anthropic in 2024. Think of it as USB for digital tools: any tool that speaks MCP can connect to any AI agent that speaks MCP, without custom wiring for every pair.
Before MCP: Claude could write a draft email but couldn't send it. It could plan a meeting but couldn't open a calendar event. Every interaction ended with you copying text into another tab.
With MCP: Claude Code connects directly to Gmail, Google Calendar, Slack, Notion — and can perform actions inside them. Not just compose, but send, create, update, and search.
Each connection is called an MCP Server — an external service that extends what Claude Code can do. Composio provides dozens of pre-built MCP Servers so you don't have to build anything yourself.
The same approach works with Codex (OpenAI's AI coding agent). If your team runs both, one Composio setup covers you.
The flow at a glance
Authorize tools in Composio
Sign in to composio.dev, pick the tools you want (Gmail, Slack, etc.), and approve access via OAuth — the same "Sign in with Google" flow you already know. No passwords stored.
Composio generates your MCP URL + API key
After authorization, Composio gives you a unique MCP URL and an API key. These are the two credentials you need for the next step.
Connect with one command
Run claude mcp add with the URL and key. Claude Code immediately recognizes all your connected tools.
Before you start
- Claude Code installed on your machine — see Setup Guide (Part 2)
- Composio account (free tier available): composio.dev — create one before continuing
- Active internet connection for the OAuth flow in Step 1
The agent-onboarding-wizard skill inside Claude Code reviews any unfamiliar MCP server before you install it: it explains what the server does, recommends the right scope (project vs. global), and warns you against bulk-installing dozens of tools you'll never use. Invoke it before connecting any new MCP server — it's your safety net for staying in control of what Claude Code can reach.
Step 1 — Create a Composio account and authorize your tools
Sign up and connect your first integrations
Go to composio.dev and create a free account (Google sign-in available).
Once inside the dashboard, navigate to Integrations and search for the tools you want to connect. Good starting points: Gmail, Google Calendar, Notion, Slack, GitHub, Linear.
For each tool, Composio opens a standard OAuth authorization window — you select your account and approve access. Important: Composio never receives your password. OAuth issues a scoped access token directly from the service. You can revoke it at any time from Google Account Security, Slack settings, or whichever service you connected.
Start with two or three tools. It's easy to add more later, and there's no benefit to authorizing integrations you won't use.
Step 2 — Get your MCP URL and API key
Two credentials to copy
In the Composio dashboard, navigate to MCP Servers and click Create MCP Server (the exact label may vary across versions). Select which authorized tools to include in this server.
Composio generates an MCP URL in the form:
https://mcp.composio.dev/your-unique-token
You also need your Composio API key. Find it under Settings → API Keys (or it may be shown inline on the MCP Server page). Generate a new key if you don't have one yet.
Your MCP URL and API key together grant access to every tool you've authorized through Composio. Do not commit them to a public repository or paste them in a shared Slack channel. Store them the same way you'd store any API credential.
Step 3 — Connect with one command
claude mcp add
Open a terminal and run:
claude mcp add --transport http composio-composio "https://YOUR_MCP_URL" \ --headers "X-API-Key:YOUR_COMPOSIO_API_KEY"
Replace https://YOUR_MCP_URL with the URL from Composio, and YOUR_COMPOSIO_API_KEY with your API key.
After the command completes, restart Claude Code fully — quit the application and reopen it.
Choose the right scope
The default scope is local (stored in ~/.claude.json, active in the current project only). Use a flag to change it:
| Scope | When to use | Where it's stored |
|---|---|---|
default |
Initial testing, single project | ~/.claude.json |
--scope project |
Share with the team via Git | .mcp.json in project root |
--scope user |
All your projects, just you | Global user settings |
To share the server with your team, add --scope project. The resulting .mcp.json file can be committed to Git:
claude mcp add --transport http composio-composio "https://YOUR_MCP_URL" \ --headers "X-API-Key:YOUR_COMPOSIO_API_KEY" --scope project
Note: Manual editing of .claude.json is possible but considered an advanced/legacy path. Always prefer the CLI command above.
Step 4 — Verify and authenticate
Two verification steps
Confirm the server is registered:
claude mcp list
You should see composio-composio in the list with a connected status.
Complete any pending OAuth flows:
Inside Claude Code, type:
/mcp
This opens the MCP management interface and lets you complete OAuth flows that remain open. Some tools (Gmail in particular) may require an additional authorization step specific to Claude Code.
After finishing the /mcp flow, restart Claude Code once more.
Success indicator: Claude Code answers questions like "How many unread emails do I have from today?" with real data from Gmail.
What you can now ask Claude
Five things that just became possible
- Summarize my unread emails from today and post the digest to #team in Slack.
- Reply to the last email from Alex — professional tone, say we'll follow up within two business days.
- Create a calendar event for June 15th, 2–4 PM, and send invites to Dana and Ron.
- Update the "Design review" task in Linear to "In Review" and add a comment: "Awaiting feedback."
- Open a GitHub issue in the landing-ai repo with the title "Fix mobile layout" and label it as a bug.
Supported integrations
150+ integrations by category
Categories include email, project management, CRM, developer tools, and databases. Full catalog at composio.dev.
Yes. Composio never stores your passwords — not once. Every connection uses OAuth, which issues a scoped access token directly from the service (Google, Slack, etc.). You can revoke access at any time from the service's own security settings. Claude Code itself stores no credentials; it only communicates with the MCP server. The MCP server in turn only holds the OAuth tokens Composio manages on your behalf.
Troubleshooting
Most frequent problems and fixes
Server doesn't appear in claude mcp list
Verify that claude mcp add completed without errors. On macOS/Linux, check for permission issues on the config file. On Windows, try running the terminal as Administrator. Fully restart Claude Code after adding the server.
OAuth window closed before completing
Run /mcp inside Claude Code to reopen the authorization flow. If it still fails, go to the Composio dashboard, disconnect the tool, and re-authorize it from scratch.
Added to the wrong scope
Remove the entry with claude mcp remove composio-composio and re-add it with the correct scope flag.
API key expired or invalid
Generate a new key in Composio under Settings → API Keys. Remove the existing server entry with claude mcp remove composio-composio, then re-add with the new key.
Claude Code says "I don't have access to that tool"
The specific tool is probably not included in your MCP Server configuration on Composio. Go to the dashboard, edit the server, and add the missing tool.
Where to next
Guide 5 — AI Agent Repo Advisor
Now that Claude Code is wired to your tools, Guide 5 covers how to choose which repositories to install and how an AI code advisor adds value beyond MCP connections.
Revisiting Guide 3? That's where MCP servers fit in the workspace architecture — the .claude directory and CLAUDE.md you set up there are the command layer that directs all of these tool connections.