composio-mcp

Composio — CLI（主要）＋ MCP（フォールバック）

Composio を通じて、AI エージェントを 1000 以上の外部アプリに接続します。このスキルでは、2 つの実行経路と、ツール機能の全体を扱います。

経路	トランスポート	認証	使用する場面
A. CLI（主要）	PATH 上の composio バイナリ	ak_* プロジェクト API キー	ヘッドレスサーバー、スクリプト、シェルアクセスを持つあらゆるエージェントで使用します。composio login が成功すれば動作します。
B. MCP（フォールバック）	HTTP https://connect.composio.dev/mcp	x-consumer-api-key の ck_* コンシューマーキー	シェルよりもツール呼び出しを優先する、MCP ネイティブのエージェントで使用します。ダッシュボードからコンシューマーキーを取得する必要があります。

どちらの経路も同じ Composio バックエンドと通信し、同じツールキットを公開します。CLI は独自の認証（composio login）を備えているため、ヘッドレス環境で最も手軽に使える経路です。

選択フロー

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 のフォールバックパターン： MCP サーバーが停止中または未設定の場合、CLI で MCP と同じすべての操作を実行できます。composio execute は MCP ツール呼び出しの代わりに、composio search は MCP の検索の代わりに、composio link は MCP の認証フローの代わりに使用できます。

使用する場面

• devin mcp list / claude mcp list で、composio のツール一覧の取得に失敗している（認証エラー）。

• ユーザーが「Composio を設定して」「Composio MCP が動かない」「composio の認証に失敗した」と言っている。

• composio execute <slug> の呼び出しで、ツールキットが接続されていないと報告された → composio link <toolkit> を実行します。

• 適切なツールのスラッグを探す必要がある → composio search "<task>" を実行します。

• MCP のフォールバック経路で使うコンシューマーキー（ck_*）が必要である。

• ユーザーが英語でこのスキルの使用を依頼する、または言及している（例：「use /composio-mcp」「run composio-mcp」）。

• ユーザーがポルトガル語でこのスキルの使用を依頼する、または言及している（例：「use /composio-mcp」「execute composio-mcp」）。

使用しない場面

• ユーザーが一般的な composio-cli のチートシート（スラッグ、execute、search、link）だけを求めている場合 — それは上流の composio-cli スキルです。このスキルでは、セットアップ、認証、MCP の接続設定を扱います。
• ユーザーが Composio SDK を使ったプロジェクト（TypeScript/Python）を構築している場合 → Composio の SDK ドキュメントを直接使用します。

ガードレール

• インストール前にバージョンを固定すること：composio-core と @composio/cli は、必ず明示的なバージョンタグを指定してインストールしてください。バージョンを指定せずに npm install -g を実行しないでください。
• composio setup --yes の前に確認すること：ホストへの CLI の自動インストール前にユーザーに確認してください。まず --dry-run を使用してください。
• 実行前に確認すること：データを変更したりメッセージを送信したりするツールを実行する前に、composio execute <slug> --get-schema と --dry-run を使用してください。
• キーを保護すること：ak_* または ck_* キーをログに記録、コミット、出力しないでください。環境変数またはエージェントのシークレットストアを使用してください。
• ツールのスラッグは composio search または公式インベントリからのみ取得すること：スラッグを捏造したり、検証せずにユーザー提供のスラッグを信用したりしないでください。

---

PATH A — CLI（主要）

A.1 インストール

インストール前にパッケージのバージョンを固定してください。<VERSION> を npm view @composio/cli version で確認できる最新の安定版、またはプロジェクトで指定されたバージョンに置き換えてください。

# 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

確認します：

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

A.2 CLI の認証

CLI では、ak_* をプレフィックスとするプロジェクト API キーを使用します。ログイン方法は 2 つあります：

# 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>

キーは ~/.composio/user_data.json に保存され、シェルプロファイルで COMPOSIO_API_KEY としてエクスポートされます。確認します：

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

whoami が失敗する場合は、composio login を再実行してください。

A.3 CLI の使用

CLI には、日常的な使用向けのコアコマンドと、高度なプロジェクトワークフロー向けの composio dev という 2 つのレイヤーがあります。

コアコマンド一覧

コマンド	目的	例
composio search	セマンティックなツールの検索	composio search "send an email"
composio execute	ツールを実行	composio execute GMAIL_SEND_EMAIL -d '{...}'
composio link	アプリのアカウントを接続	composio link github
composio listen	トリガーイベントを購読	composio listen --toolkit github --trigger GITHUB_COMMIT_EVENT
composio run	ヘルパーを使ったインライン TS/JS	composio run 'await execute("...")'
composio proxy	API に直接アクセス	composio proxy https://api.github.com/user --toolkit github
composio login	認証	composio login --user-api-key ak_...
composio whoami	認証状態を確認	composio whoami
composio setup	プラグインをインストール	composio setup --target auto
composio orgs	組織を管理	composio orgs list
composio config	CLI 設定	composio config

デフォルトのワークフロー（execute → search → link）

1. スラッグが分かっている場合は、まず composio execute <slug> を実行します。
2. 並列呼び出し → composio execute -p/--parallel に、<slug> -d <json> の組を繰り返し指定します。
3. ツールキットが未接続の場合 → composio link <toolkit> を実行してから、再試行します。
4. 引数が不明な場合 → 推測する前に composio execute <slug> --get-schema または --dry-run を実行します。
5. スラッグが不明な場合 → composio search "<task>" を実行します（関連するクエリは1回の呼び出しにまとめます）。

# 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: "[email protected]", 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 '{...}'

主なフラグ：

フラグ	目的
--get-schema	実行せずに必須の引数を確認
--dry-run	アクションを実行せずにリクエストの形式をプレビュー
--file <path>	アップロード可能なファイル入力が1つだけのツールに、ローカルファイルを渡す
--account <alias>	同じツールキットに複数のアカウントがある場合、接続済みアカウントを選択
--parallel / -p	1回の実行で複数の独立したツール呼び出しを実行
--skip-connection-check	接続済みアカウントの確認を省略
--skip-tool-params-check	キャッシュされたスキーマに対する入力の検証を省略
--skip-checks	上記の両方の確認を省略

composio run — SDK を使わないスクリプト実行

composio run は、認証済みの execute()、search()、proxy() と、実験的なヘルパー experimental_subAgent() があらかじめ注入された、インラインの ESM JavaScript/TypeScript スニペットを実行します。SDK のセットアップは不要です。

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);
'

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);
'

注入されるヘルパー： execute()、search()、proxy()、experimental_subAgent()、result.prompt()、z（zod）。

composio listen — トリガーイベントを購読

composio listen --toolkit github --trigger GITHUB_COMMIT_EVENT

ツールキットのトリガーイベントを購読し、標準出力にストリーミングします。リアクティブなワークフローや自動化に役立ちます。

composio dev — 高度なワークフロー

開発者スコープの管理機能：スキャフォールディング、プレイグラウンドでの実行、ログ、接続済みアカウント、トリガー、プロジェクト。

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 — 型スタブ

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

コマンド一覧の全容については、references/cli-reference.md を参照してください。

---

PATH B — MCP フォールバック

B.1 コンシューマーキー（ck_*）を取得

MCP エンドポイント https://connect.composio.dev/mcp は、ak_* プロジェクト API キーを受け付けません。別の認証情報である、ck_* がプレフィックスのコンシューマーキーが必要です。

ck_* と ak_* の違い — コンシューマーキー（ck_*）は、Connect エンドポイントに接続する MCP クライアントの認証に使用します。プロジェクト API キー（ak_*）は、バックエンド API 呼び出し（backend.composio.dev/api/v3/...）と CLI の認証に使用します。これらは別個のキーであり、互いに代用できません。

コンシューマーキーの取得方法：

1. ダッシュボードを開きます：https://dashboard.composio.dev/
2. For You → Connect Settings → Sessions & API Key に移動します
3. コンシューマーキーをコピーします（ck_ で始まります）
4. （任意）Regenerate でキーをローテーションします。これにより、すべての MCP クライアントで旧キーが直ちに無効になります。

B.2 MCP サーバーを設定

MCP サーバーは、https://connect.composio.dev/mcp にあるストリーミング可能な HTTP サーバーです。x-consumer-api-key ヘッダーが必要です。

汎用設定（すべての stdio/http MCP クライアント向け）

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

環境変数による置換（推奨 — キーをコミットせずに済みます）

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

次に、シェルのプロファイル（~/.bashrc / ~/.zshrc）でエクスポートします。

export COMPOSIO_CONSUMER_KEY="ck_your_consumer_key_here"

プラットフォーム別の設定 — 重要な注意点

各 MCP クライアントプラットフォームでは、設定形式が異なります。フィールド名を間違えると、サーバーはエラーなしで無視されます（エラーは表示されず、ツールも表示されません）。一覧については、**references/platform-quirks.md**をご覧ください。

プラットフォーム	設定ファイル	ルートキー	URL フィールド	注意点
Claude Code	~/.claude.json	mcpServers	url	type: "http"
Claude Desktop	claude_desktop_config.json	mcpServers	url	—
Cursor	~/.cursor/mcp.json	mcpServers	url	—
Devin CLI	~/.config/devin/mcp_config.json	mcpServers	url	devin mcp add CLI
Devin Desktop	~/.devin/mcp_config.json	mcpServers	serverUrl	urlではありません！
OpenCode	~/.config/opencode/opencode.json	mcp	url	type: "remote"、envではなくenvironment
Antigravity IDE/CLI	~/.gemini/config/mcp_config.json	mcpServers	serverUrl	urlではありません！アンインストール時にキャッシュを消去
OpenClaw	OpenClaw の設定	mcp.servers	url	transport: "streamable-http"、openclaw mcp add CLI

特に注意すべき、設定が無視される原因トップ3：

1. Devin Desktop / AntigravityではurlではなくserverUrlを使います。urlを使うと、設定はエラーなしで無視されます。
2. OpenCodeではmcpServersではなくmcp、envではなくenvironmentを使い、commandは単一の配列にします。
3. OpenCodeの環境変数置換では${VAR}ではなく{env:VAR}を使います。

プラットフォームごとの正確な JSON ブロックについては、**references/mcp-config.md**をご覧ください。

自動セットアップヘルパー

同梱のヘルパーを実行すると、インストール済みのすべてのプラットフォームを検出し、それぞれに正しい形式で設定を適用します（serverUrlとurl、mcpとmcpServers、environmentとenvの違い、および 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 MCP サーバーを確認する

設定後、エージェントを再起動して、次を確認します。

# 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)

{"error":"Authorization required"}が表示される場合は、コンシューマーキーが未設定、誤っている、または失効しています。ダッシュボードを再確認し、必要に応じてキーをローテーションしてください。

B.4 MCP ツールの構成

MCP エンドポイントは、CLI と同じツールキットを公開します。mcp_list_toolsが成功すると、ツールはmcp__composio__<SLUG>（例：mcp__composio__GMAIL_SEND_EMAIL）として表示されます。基盤となるスラッグは CLI と同じです。composio searchとcomposio executeでは、同じ名前を使用します。

B.5 オプション：MCP サーバーで API キーを必須にする（組織レベル）

組織では、コンシューマーキーに加えて、有効なプロジェクト API キー（ak_*）をすべての MCP リクエストに必須にできます。

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}'

有効にすると、MCP リクエストにはx-consumer-api-key（ck_）とx-api-key（ak_）の両方が必要です。デフォルトでは無効です。

---

認証リファレンス

認証情報	プレフィックス	保存場所	認証対象
プロジェクト API キー	ak_*	~/.composio/user_data.json、$COMPOSIO_API_KEY	CLI コマンド、backend.composio.dev API
コンシューマーキー	ck_*	ダッシュボードのみ。MCP 設定に貼り付けます	MCP Connect エンドポイント（connect.composio.dev/mcp）
接続済みアカウント（ツールキットごと）	—	composio link <toolkit>によるブラウザー OAuth	個別アプリへのアクセス（Gmail、GitHub、Slack…）
AuthKit JWT	—	OAuth フロー	代替の MCP ベアラー認証（まれ。OAuth ベースのデプロイ向け）

認証フロー図

┌─────────────────────────────────────────────────────────────┐
│  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  │
└─────────────────────────────────────────────────────────────┘

---

ツールの検索と参照

適切なツールを見つける方法

1. セマンティック検索 — composio search "<describe the task>"は、すべてのツールキットを対象にセマンティック検索を行います。これが主な検索方法です。
2. ツールキットで絞り込む — アプリが分かっている場合は、--toolkits <slug>で絞り込みます。
3. スキーマを確認する — composio execute <slug> --get-schemaを実行すると、実行前に必須入力が表示されます。
4. ドライラン — composio execute <slug> --dry-run -d '{...}'を実行すると、副作用を起こさずに検証できます。

ツール一覧

最新のカタログには、30 個のツールキット／約 3,300 個のツール／約 170 個のトリガーがあります。ツールキットの全内訳と一般的なツールのパターンについては、references/tools-inventory.md を参照してください。

ツールキット	スラッグ	ツール	トリガー
Gmail	gmail	61	2
GitHub	github	871	46
Slack	slack	158	9
Google Calendar	googlecalendar	45	7
Notion	notion	53	8
Jira	jira	97	17
HubSpot	hubspot	244	2
…	…	…	…

タグ

ツールはフィルタリング用のタグが付けられています。一般的なタグは次のとおりです。

タグ	意味
important	中核となる／価値の高いツール
destructiveHint	元に戻せない操作、またはデータを破壊する操作
idempotentHint	安全に再試行できる
createHint	リソースを作成する
updateHint	リソースを変更する
deleteHint	リソースを削除する
readOnlyHint	副作用なし
openWorldHint	結果が外部の状態に依存する
batch	一括操作

---

MCP のフォールバックとしての CLI

MCP エンドポイントに接続できない場合や、設定されていない場合でも、CLI を使って MCP で実行できるすべての操作を行えます。

MCP 操作	CLI での同等操作
mcp__composio__GMAIL_SEND_EMAIL	composio execute GMAIL_SEND_EMAIL -d '{...}'
ツールの検出	composio search "<task>"
アカウントのリンク	composio link <toolkit>
トリガーのサブスクリプション	composio listen --toolkit <toolkit> --trigger <slug>
生の API 呼び出し	composio proxy <url> --toolkit <toolkit>
複数ステップのワークフロー	composio run '<code>'

CLI の方法は、認証をローカルで処理し（~/.composio/user_data.json の ak_* キーを使用）、MCP エンドポイントやコンシューマーキーに依存しないため、ヘッドレスサーバーではより確実です。

---

トラブルシューティング

症状	原因	解決方法
composio whoami が失敗する／空の結果を返す	ログインしていない	composio login（または --user-api-key ak_...）
composio execute が「toolkit not connected」と表示する	アプリのアカウントがリンクされていない	composio link <toolkit> を実行してから再試行
MCP Failed to list tools for composio	x-consumer-api-key ヘッダーがない／誤っている	ダッシュボードから ck_* を取得し、設定を修正（B.2）して、エージェントを再起動
MCP Authorization required: Bearer token rejected	ck_* が必要な箇所に ak_* を送信した	プロジェクト API キーではなく、コンシューマーキー（ck_*）を使用
MCP Authorization required: No Authorization header	ヘッダーがない	MCP 設定に x-consumer-api-key ヘッダーを追加
ヘッドレス環境で composio login が停止する	ブラウザーのフローにディスプレイが必要	--no-browser --no-wait を使用してから、--key <session> または --user-api-key ak_... を指定
ツールは表示されるが、実行すると 401 が返る	require_mcp_api_key が有効で、x-api-key がない	x-consumer-api-key とともに x-api-key: ak_* ヘッダーを追加
composio search が結果を返さない	キャッシュが古い、または組織が設定されていない	rm -rf ~/.composio/toolkits.json を実行してから再試行

---

参考資料

• references/cli-reference.md — composio CLI コマンドの完全なリファレンス（core + dev + generate + setup）。
• references/tools-inventory.md — ライブツールキットのインベントリ（30 のツールキットに約 3300 個のツール）と一般的なツールのパターン。
• references/mcp-config.md — プラットフォームごとの完全な JSON 設定ブロック（Claude Code/Desktop、Cursor、Devin CLI/Desktop、OpenCode、Antigravity IDE/CLI、OpenClaw）。
• references/platform-quirks.md — クロスプラットフォーム MCP 設定の差異一覧（serverUrl と url、mcp と mcpServers、environment と env、env の置換構文、OpenClaw の CDP ポート）。
• references/troubleshooting.md — 詳細なトラブルシューティング（CLI キャッシュ、pending-login、組織ピッカー、composio dev プロジェクト）。
• scripts/setup_composio_mcp.sh — インストール済みのすべてのプラットフォームを検出し、それぞれに適切な形式でパッチを適用します（serverUrl/url、mcp/mcpServers、environment/env、OpenClaw CLI に対応）。
• scripts/verify_composio.sh — whoami と curl の initialize プローブを実行し、いくつかのツールを一覧表示して、エンドツーエンドで動作することを確認します。
• Composio Connect のドキュメント
• コンシューマーキーとプロジェクトキーの境界
• Devin CLI MCP の設定
• Antigravity MCP のドキュメント
• OpenCode MCP サーバー
• OpenClaw MCP ツール
• Cursor MCP のドキュメント
• コマンドのチートシート全体については、上流の composio-cli スキルを参照してください。