# Claude Code Plugin (/docs/claude-code-plugin)

The **Composio plugin for Claude Code** bundles the Composio Connect MCP server with a set of opinionated skills, so Claude Code can search, connect, and act across 1000+ apps right after install. Authentication is fully managed — no API key handling, no manual MCP config.

> Looking for the API-key based MCP setup (or other clients like Cursor, Codex, Claude Desktop)? See [Composio Connect](/docs/composio-connect).

# What you get

The plugin ships two things together:

* **Composio Connect MCP server** — the same gateway documented in [Composio Connect](/docs/composio-connect), pre-configured. Auth is handled via in-flow OAuth, so you don't paste API keys into your config.
* **Bundled skills** — pre-written prompts that show Claude how to use the MCP server effectively:
  * **`composio-mcp`** — reference for the 7 meta-tools (`COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, etc.) and the recommended search → connect → execute flow.
  * **`onboarding`** — interactive setup that asks what you want to automate, recommends 2–4 apps, and walks you through connecting them.
  * **`company-activity-summary`** — cross-app activity summary across Slack, GitHub, Notion, Linear, Gmail, and more.
  * **`prefer-composio`** — routing skill that tells Claude to reach for Composio first whenever you paste an app URL or mention an external service, so you don't end up using less reliable native connectors.

# Install

#### Add the Composio marketplace

In Claude Code, run:

```bash
/plugin marketplace add ComposioHQ/composio-plugin-cc
```

This registers the catalog. No plugins are installed yet.

#### Install the Composio plugin

```bash
/plugin install composio-mcp@composio
```

Restart Claude Code (or run `/reload-plugins`) when prompted.

#### Connect your first app

Ask Claude something that needs an external service — for example: *"Star `composiohq/composio` on GitHub"* — and Claude will run the `onboarding` skill, walk you through connecting GitHub, and execute the action. Subsequent runs reuse the same connection.

# Team setup

To pre-install the plugin for everyone on your team, add this to your project's `.claude/settings.json`:

```json title=".claude/settings.json"
{
  "extraKnownMarketplaces": {
    "composio": {
      "source": {
        "source": "github",
        "repo": "ComposioHQ/composio-plugin-cc"
      }
    }
  },
  "enabledPlugins": {
    "composio-mcp@composio": true
  }
}
```
Anyone who clones the repo and opens it in Claude Code will be prompted to enable the plugin. See the Claude Code [plugin scopes](https://docs.claude.com/en/docs/claude-code/plugins-reference#plugin-installation-scopes) reference for `user` vs `project` vs `local` scope behavior.

# Updating

The plugin is versioned via the `version` field in its `plugin.json`. To pull the latest release:

```bash
/plugin marketplace update composio
/reload-plugins
```

# How it differs from the API-key MCP setup

Both paths give Claude Code access to the same Composio Connect MCP server and the same 1000+ apps. The differences:

|                                         | Plugin install                        | `claude mcp add`                                  |
| --------------------------------------- | ------------------------------------- | ------------------------------------------------- |
| Setup steps                             | Two slash commands                    | One terminal command, requires copying an API key |
| Auth                                    | OAuth, no API key in your config      | API key in `--header "x-consumer-api-key: ..."`   |
| Bundled skills                          | Yes (onboarding, routing, summaries)  | No                                                |
| Discoverable in Claude Code marketplace | Yes                                   | No                                                |
| Updates                                 | `/plugin marketplace update composio` | Manual re-run of `claude mcp add`                 |

Pick the plugin path if you want the fastest install and the bundled skills. Pick the `claude mcp add` path if you already have an API key and want a single-command setup script you can replicate across machines.

# Source code

The plugin is open source: [ComposioHQ/composio-plugin-cc](https://github.com/ComposioHQ/composio-plugin-cc). Issues and PRs welcome.

# Troubleshooting

For tools-not-appearing, OAuth, and connection issues, see the [Composio Connect troubleshooting section](/docs/composio-connect#troubleshooting). The same checks apply to the plugin install (the underlying MCP server is identical).

For plugin-specific issues — install errors, marketplace not updating, skills not appearing — see the [Claude Code plugin troubleshooting docs](https://docs.claude.com/en/docs/claude-code/plugins-reference#common-issues).

---

📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference)

---

# Composio SDK — Instructions for AI Code Generators

**Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents.
**Scope:** All AI-generated code using Composio must follow these guardrails.

---

## 1. Correct Composio Integration

Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).

### Native Tools

```python
# ✅ CORRECT — Python (defaults to OpenAI)
from composio import Composio

composio = Composio()
session = composio.create(user_id="user_123")
tools = session.tools()
# Pass tools to your agent/LLM framework
```

```typescript
// ✅ CORRECT — TypeScript (defaults to OpenAI)
import { Composio } from "@composio/core";

const composio = new Composio();
const session = await composio.create("user_123");
const tools = await session.tools();
// Pass tools to your agent/LLM framework
```

For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_<provider>` for Python, `@composio/<provider>` for TypeScript.

### MCP

Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.

---

## 2. CRITICAL INSTRUCTIONS FOR AI MODELS

### 2.1 — ALWAYS DO THE FOLLOWING

1. **Use `composio.create(user_id)`** to create a session — this is the entry point for all Composio integrations.
2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration.
3. **Import** from the correct provider package (`composio_<provider>` for Python, `@composio/<provider>` for TypeScript).
4. **Pass `user_id` to `composio.create()`**, not to individual tool calls.

### 2.2 — NEVER DO THE FOLLOWING

1. **Do not** instruct users to manually create auth configs or connected accounts before running.
2. **Do not** import from `composio_openai` / `@composio/openai` when using OpenAI Agents SDK — use `composio_openai_agents` / `@composio/openai-agents` instead.

### 2.3 — DISCOURAGED (do not use unless user explicitly asks)

Do **not** generate `composio.tools.get()`, `composio.tools.execute()`, or `composio.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface.


---

## Terminology Migration (old → current)

If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.**

| Old term (v1/v2) | Current term (v3) | In code |
|---|---|---|
| entity ID | user ID | `user_id` parameter |
| actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* |
| apps / appType | toolkits | e.g., `github` is a *toolkit* |
| integration / integration ID | auth config / auth config ID | `auth_config_id` parameter |
| connection | connected account | `connected_accounts` namespace |
| ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` |
| toolset | provider | e.g., `OpenAIProvider` |

If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.