Composio — CLI (primary) + MCP (fallback)

Connect AI agents to 1000+ external apps through Composio. This skill covers two execution paths and the full tool surface.

Both paths talk to the same Composio backend and expose the same toolkits. The CLI is the path of least resistance on headless boxes because it ships its own auth (composio login).

Decision flow

Need to use Composio?
├─ Agent has shell access? → Use CLI (Path A) → composio search/execute/link/run/proxy
└─ Agent is MCP-native only? → Use MCP (Path B) → mcp__composio__* tool calls

CLI fallback pattern: When the MCP server is down or unconfigured, the CLI can perform every operation the MCP would do — composio execute replaces MCP tool calls, composio search replaces MCP search, composio link replaces MCP auth flows.

When to use

• devin mcp list / claude mcp list shows composio failing to list tools (auth error).

• The user says "configure Composio", "Composio MCP not working", "composio auth failed".

• A composio execute <slug> call reports a toolkit is not connected → run composio link <toolkit>.

• You need to find the right tool slug → composio search "<task>".

• You need the consumer key (ck_*) for the MCP fallback path.

• User asks or mentions this skill in English (e.g., "use /composio-mcp", "run composio-mcp").

• O usuário pede ou menciona esta skill em português (ex.: "use /composio-mcp", "execute composio-mcp").

When NOT to use

• The user only wants the generic composio-cli cheat-sheet (slugs, execute, search, link) — that is the upstream composio-cli skill. This skill focuses on setup, auth, and MCP wiring.
• The user is building a Composio SDK project (TypeScript/Python) → use Composio's SDK docs directly.

Guardrails

• Pin before install: always install composio-core and @composio/cli with an explicit version tag; do not run bare npm install -g without a version.
• Confirm before composio setup --yes: ask the user before auto-installing the CLI on their host; prefer --dry-run first.
• Inspect before execute: use composio execute <slug> --get-schema and --dry-run before running any tool that mutates data or sends messages.
• Protect keys: never log, commit, or echo ak_* or ck_* keys. Use environment variables or the agent's secret store.
• Tool slugs only from composio search or official inventory: do not fabricate slugs or trust user-provided slugs without verification.

PATH A — CLI (primary)

A.1 Install

Pin the package versions before installing. Replace <VERSION> with the latest stable from npm view @composio/cli version or the version required by the project.

# Option 1: npm (recommended) — pinned versions
npm install -g composio-core@<VERSION> @composio/cli@<VERSION>

# Option 2: let Composio auto-install for your agent host
# Ask the user before auto-installing; prefer --dry-run first if available.
composio setup --target auto --yes --dry-run || composio setup --target auto --yes

Verify:

composio --version
composio whoami    # should print JSON with email + org

A.2 Authenticate the CLI

The CLI uses a project API key prefixed ak_*. Two ways to log in:

# Interactive (opens browser, polls for completion)
composio login

# Headless / CI: pass the key directly
composio login --user-api-key ak_your_key_here --yes

# No-browser flow: prints a URL + session key, you complete in any browser
composio login --no-browser --no-wait
# then later:
composio login --key <session-key>

The key is stored in ~/.composio/user_data.json and exported as COMPOSIO_API_KEY in the shell profile. Verify:

composio whoami
# {"account_type":"human","email":"...","current_org_name":"..."}

If whoami fails, re-run composio login.

A.3 Use the CLI

The CLI has two layers: core commands for everyday use and composio dev for advanced project workflows.

Core command surface

Default workflow (execute → search → link)

1. Start with composio execute <slug> whenever the slug is known.
2. Parallel calls → composio execute -p/--parallel with repeated <slug> -d <json> groups.
3. Toolkit not connected? → composio link <toolkit> and retry.
4. Arguments unclear? → composio execute <slug> --get-schema or --dry-run before guessing.
5. Slug unknown? → composio search "<task>" (batch related queries into one call).

# Known slug — just execute
composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'

# Unknown slug — search first
composio search "create a github issue"
composio search "send an email" --toolkits gmail

# Inspect before executing
composio execute GITHUB_CREATE_ISSUE --get-schema
composio execute GITHUB_CREATE_ISSUE --dry-run -d '{ owner: "acme", repo: "app", title: "Bug" }'

# Pass data from file or stdin
composio execute GITHUB_CREATE_ISSUE -d @issue.json
cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -

# Upload a local file
composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \
  --file ./image.png \
  -d '{ channels: "C123" }'

# Parallel independent calls
composio execute --parallel \
  GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi" }' \
  GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'

# Skip connection check (when you know the account is linked)
composio execute GITHUB_CREATE_ISSUE --skip-connection-check -d '{...}'

Key flags:

composio run — scripting without SDK

composio run executes an inline ESM JavaScript/TypeScript snippet with authenticated execute(), search(), proxy(), and the experimental experimental_subAgent() helper pre-injected. No SDK setup required.

composio run '
  const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");
  console.log(me.data.login);
'

composio run '
  const [emails, issues] = await Promise.all([
    execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
    execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "acme", repo: "app", state: "open" }),
  ]);
  const brief = await experimental_subAgent(`Summarize:\n${emails.prompt()}\n${issues.prompt()}`);
  console.log(brief);
'

Structured output with zod:

composio run --logs-off '
  const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 5 });
  const brief = await experimental_subAgent(
    `Summarize these emails and count them.\n\n${emails.prompt()}`,
    { schema: z.object({ summary: z.string(), count: z.number() }) }
  );
  console.log(brief.structuredOutput);
'

Injected helpers: execute(), search(), proxy(), experimental_subAgent(), result.prompt(), z (zod).

composio listen — subscribe to trigger events

composio listen --toolkit github --trigger GITHUB_COMMIT_EVENT

Subscribe to toolkit trigger events and stream them to stdout. Useful for reactive workflows and automation.

composio dev — advanced workflows

Developer-scoped management: scaffolding, playground execution, logs, connected accounts, triggers, projects.

composio dev init                          # scaffold a project
composio dev toolkits list                 # browse all toolkits
composio dev toolkits info github          # inspect a toolkit
composio dev auth-configs list             # auth configs
composio dev connected-accounts list       # connected accounts
composio dev triggers list                 # trigger types
composio dev playground-execute            # playground execution
composio dev logs tools                    # browse tool logs

composio generate — type stubs

composio generate --toolkits github gmail --output-dir ./src/types

See references/cli-reference.md for the full command surface.

PATH B — MCP fallback

B.1 Get the consumer key (ck_*)

The MCP endpoint https://connect.composio.dev/mcp does not accept the ak_* project API key. It requires a consumer key prefixed ck_*, which is a separate credential.

ck_* vs ak_* — Consumer keys (ck_*) authenticate MCP clients connecting to the Connect endpoint. Project API keys (ak_*) authenticate backend API calls (backend.composio.dev/api/v3/...) and the CLI. They are distinct; one cannot substitute for the other.

How to get the consumer key:

1. Open the dashboard: https://dashboard.composio.dev/
2. Go to For You → Connect Settings → Sessions & API Key
3. Copy the consumer key (starts with ck_)
4. (Optional) Rotate it with Regenerate — this immediately invalidates the old key across all MCP clients.

B.2 Configure the MCP server

The MCP server is a streamable HTTP server at https://connect.composio.dev/mcp. It needs the x-consumer-api-key header.

Universal config (any stdio/http MCP client)

{
  "mcpServers": {
    "composio": {
      "type": "http",
      "url": "https://connect.composio.dev/mcp",
      "headers": {
        "x-consumer-api-key": "ck_your_consumer_key_here"
      }
    }
  }
}

Env-substituted (recommended — avoids committing the key)

{
  "mcpServers": {
    "composio": {
      "type": "http",
      "url": "https://connect.composio.dev/mcp",
      "headers": {
        "x-consumer-api-key": "${COMPOSIO_CONSUMER_KEY}"
      }
    }
  }
}

Then export in your shell profile (~/.bashrc / ~/.zshrc):

export COMPOSIO_CONSUMER_KEY="ck_your_consumer_key_here"

Per-platform config — critical gotchas

Each MCP client platform has its own config format. Getting field names wrong causes the server to be silently ignored (no error, just no tools). See references/platform-quirks.md for the full matrix.

Top 3 silent-failure traps:

1. Devin Desktop / Antigravity use serverUrl (not url) — using url = silently ignored.
2. OpenCode uses mcp (not mcpServers), environment (not env), command as single array.
3. OpenCode env substitution uses {env:VAR} not ${VAR}.

See references/mcp-config.md for the exact JSON block per platform.

Automated setup helper

Run the bundled helper to detect all installed platforms and patch each one with the correct format (handles serverUrl vs url, mcp vs mcpServers, environment vs env, and OpenClaw CLI):

bash skills/composio-mcp/scripts/setup_composio_mcp.sh
# or with the key inline:
COMPOSIO_CONSUMER_KEY=ck_xxx bash skills/composio-mcp/scripts/setup_composio_mcp.sh
# dry-run (show what would change):
COMPOSIO_CONSUMER_KEY=ck_xxx bash skills/composio-mcp/scripts/setup_composio_mcp.sh --dry-run
# target one platform:
bash skills/composio-mcp/scripts/setup_composio_mcp.sh --platform cursor
# remove:
bash skills/composio-mcp/scripts/setup_composio_mcp.sh --remove

B.3 Verify the MCP server

After configuring, restart the agent and check:

# From the agent (Claude Code / Devin):
#   mcp_list_tools for composio should return tools

# From the shell, test the endpoint directly:
curl -sS -X POST "https://connect.composio.dev/mcp" \
  -H "Content-Type: application/json" \
  -H "x-consumer-api-key: $COMPOSIO_CONSUMER_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Expect: a JSON-RPC InitializeResult (not an "Authorization required" error)

If you see {"error":"Authorization required"}, the consumer key is missing, wrong, or revoked. Re-check the dashboard and rotate if needed.

B.4 MCP tool surface

The MCP endpoint exposes the same toolkits as the CLI. When mcp_list_tools succeeds, tools appear as mcp__composio__<SLUG> (e.g. mcp__composio__GMAIL_SEND_EMAIL). The underlying slugs are identical to the CLI — composio search and composio execute use the same names.

B.5 Optional: enforce API key on the MCP server (org-level)

Orgs can require that every MCP request carry a valid project API key (ak_*) in addition to the consumer key:

curl -X PATCH "https://backend.composio.dev/api/v3/org/project/config" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $COMPOSIO_API_KEY" \
  -d '{"require_mcp_api_key": true}'

When enabled, MCP requests must include both x-consumer-api-key (ck_) and x-api-key (ak_). Default is disabled.

Authentication reference

Auth flow diagram

┌─────────────────────────────────────────────────────────────┐
│  CLI path (ak_*)                                            │
│  composio login ──► ~/.composio/user_data.json              │
│  composio whoami ──► verify                                 │
│  composio link <toolkit> ──► browser OAuth per app          │
│  composio execute <slug> ──► uses ak_* + connected account  │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│  MCP path (ck_*)                                            │
│  dashboard → Connect Settings → copy ck_*                   │
│  patch mcp config: headers.x-consumer-api-key = ck_*        │
│  restart agent → mcp_list_tools(composio) → tools            │
│  (optional) require_mcp_api_key=true → also send x-api-key  │
└─────────────────────────────────────────────────────────────┘

Tool discovery & consultation

How to find the right tool

1. Semantic search — composio search "<describe the task>" uses semantic search across all toolkits. This is the primary discovery mechanism.
2. Narrow by toolkit — when you know the app, filter: --toolkits <slug>.
3. Inspect the schema — composio execute <slug> --get-schema shows required inputs before running.
4. Dry-run — composio execute <slug> --dry-run -d '{...}' validates without side effects.

Tool inventory

The live catalog is 30 toolkits / ~3300 tools / ~170 triggers. See references/tools-inventory.md for the full toolkit breakdown and common tool patterns.

Tags

Tools are tagged for filtering. Common tags:

CLI as MCP fallback

When the MCP endpoint is unreachable or unconfigured, the CLI can perform every operation the MCP would do:

The CLI path is more reliable on headless servers because it handles auth locally (ak_* key in ~/.composio/user_data.json) and does not depend on the MCP endpoint or consumer key.

Troubleshooting

References

• references/cli-reference.md — Full composio CLI command reference (core + dev + generate + setup).
• references/tools-inventory.md — Live toolkit inventory (~3300 tools across 30 toolkits) and common tool patterns.
• references/mcp-config.md — Full per-platform JSON config blocks (Claude Code/Desktop, Cursor, Devin CLI/Desktop, OpenCode, Antigravity IDE/CLI, OpenClaw).
• references/platform-quirks.md — Cross-platform MCP config quirks matrix (serverUrl vs url, mcp vs mcpServers, environment vs env, env substitution syntax, OpenClaw CDP ports).
• references/troubleshooting.md — Extended troubleshooting (CLI cache, pending-login, org picker, composio dev projects).
• scripts/setup_composio_mcp.sh — Detects all installed platforms and patches each with the correct format (handles serverUrl/url, mcp/mcpServers, environment/env, OpenClaw CLI).
• scripts/verify_composio.sh — Runs whoami + curl initialize probe + lists a few tools to confirm end-to-end.
• Composio Connect docs
• Consumer vs project key boundaries
• Devin CLI MCP configuration
• Antigravity MCP docs
• OpenCode MCP servers
• OpenClaw MCP tools
• Cursor MCP docs
• Upstream composio-cli skill for the full command cheat-sheet.