@devries-cameron20 / composio Mirror · read-only / commits / dd380782e
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

docs: add Apps and toolkits section for Composio Built vs Provider MCP

The catalog now contains toolkits backed by a product's own hosted MCP server (slug `<slug>_mcp`) alongside toolkits Composio builds on the product's public API, and the dashboard groups sibling toolkits under one App. Nothing in the docs explained this. Adds a nested `apps-and-toolkits` section with three pages: * Apps vs toolkits: what a toolkit is, how an App groups siblings, and why siblings never share a connection. * What are Provider MCPs: how they work, slug and tool naming, auth, no triggers, and how they differ from Composio's own MCP transports. * Composio Built vs Provider MCPs: the comparison and the decision, with the Composio and MCP marks inlined from the dashboard as currentColor SVG so they theme in both modes. The section keeps the `/docs/apps-and-toolkits` path via `index.mdx`, so no existing inbound link changes. Also updates the glossary, the LLM guardrails, the docs agent knowledge and context, and the `composio` skill so the agent-facing surfaces use the shipped labels, and adds a decision record. Verified against the live API on 2026-09-02: tool and trigger counts, the auth spread across all 73 Provider MCP toolkits, and that `session.authorize("notion_mcp")` returns a Connect Link with no pre-created auth config. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0122zeybQcKRxGNzdjdRhZBr

Jeevesh Jain committed Sep 2, 2026 at 16:12 UTC dd380782ea6be8b34f36bb0e4696094c12f12359
28 files changed +386 -25
docs/agent/instructions/context.ts
+2
@@ -15,6 +15,8 @@ This is your always-on map of Composio's concepts and the canonical page for eac
15
16 ## Tools and toolkits
17
18 +- **Apps and toolkits**: an App groups catalog toolkits for comparison. Composio Built toolkits use a product API; Provider MCP toolkits use its hosted MCP server. Each keeps separate tools and connections. Use exact toolkit slugs in session configuration. See [Apps and toolkits](/docs/apps-and-toolkits).
19 +
20 - **Toolkit** — a collection of related tools for a service (e.g. \`github\`, \`gmail\`). A **tool** is one action, named \`{TOOLKIT}_{ACTION}\` (e.g. \`GITHUB_CREATE_ISSUE\`). Every toolkit is discoverable by default; restrict with the \`toolkits\` config. → [Configuring sessions](/docs/configuring-sessions)
21 - **Meta tools** — the fixed set every session exposes (\`COMPOSIO_SEARCH_TOOLS\`, \`COMPOSIO_GET_TOOL_SCHEMAS\`, \`COMPOSIO_MANAGE_CONNECTIONS\`, \`COMPOSIO_MULTI_EXECUTE_TOOL\`, \`COMPOSIO_REMOTE_WORKBENCH\`, \`COMPOSIO_REMOTE_BASH_TOOL\`). → [Meta tools reference](/toolkits/meta-tools)
22 - **Providers** — adapter packages that format Composio tools for a framework (OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, Pi, …). → [Providers](/docs/providers)
docs/agent/knowledge.md
+10 -2
@@ -16,9 +16,17 @@ A provider adapts Composio tools into the shape your AI framework expects. Compo
16
17 The userID scopes connected accounts and tool executions and isolates users from each other. Use a stable identifier such as your database UUID or primary key. Avoid email addresses (they change) and never use `default` in production, since that exposes one user's connections to others.
18
19 -## Native tools vs MCP (/docs/sessions-via-mcp)
19 +## Direct tools (provider package) vs MCP transport (/docs/sessions-via-mcp)
20
21 -By default a session gives your agent tools it calls directly through a provider package; this integrates with your framework and supports modifiers and custom tools. Creating a session with `{ mcp: true }` also exposes `session.mcp.url` and `session.mcp.headers` for any MCP-compatible client. MCP is more portable across clients, but modifiers and custom tools do not apply over the MCP surface.
21 +By default a session gives your agent direct tools, called through a provider package (previously called native tools); this integrates with your framework and supports modifiers and custom tools. Creating a session with `{ mcp: true }` also exposes `session.mcp.url` and `session.mcp.headers` for any MCP-compatible client. MCP transport is more portable across clients, but modifiers and custom tools do not apply over the MCP surface.
22 +
23 +## Apps: Composio Built vs Provider MCP toolkits (/docs/apps-and-toolkits)
24 +
25 +An App groups the sibling toolkits for one product in the catalog; for example, the Notion app contains the `notion` and `notion_mcp` toolkits. A Composio Built toolkit is built and maintained by Composio on the product's public API and can have triggers. A Provider MCP toolkit (slug ending `_mcp`) connects to the product's own hosted MCP server, commonly uses DCR OAuth, and has no triggers today. Siblings are separate toolkits with separate auth configs and connected accounts; sessions, search, and execution take exact toolkit slugs, and an App has no slug. To choose, compare auth schemes, tool lists, and triggers, and prefer the toolkit your users can authenticate.
26 +
27 +## Custom MCP vs Provider MCP toolkits (/docs/extending-sessions/custom-mcp)
28 +
29 +A Custom MCP toolkit is your own remote MCP server registered into your project (slug `CUSTOM_*`); it is project-private and never grouped into an App. A Provider MCP toolkit is a catalog toolkit that connects to a product's own hosted MCP server (slug ending `_mcp`) and is available to every project. Use Custom MCP for an MCP server that isn't in the catalog; when the product already ships a Provider MCP toolkit, use that instead.
30
31 ## Sandbox files and the /mnt/files mount (/docs/sandbox)
32
docs/content/docs/apps-and-toolkits/composio-built-vs-provider-mcp.mdx new
+64
@@ -0,0 +1,64 @@
1 +---
2 +title: Composio Built vs Provider MCPs
3 +description: Which toolkit to use when a product ships more than one, such as notion or notion_mcp, decided from auth, triggers, and tool coverage
4 +keywords: [composio built vs provider mcp, which toolkit, notion vs notion_mcp, choose a toolkit, provider mcp, sibling toolkits, dcr oauth, triggers]
5 +isNew: true
6 +---
7 +
8 +export const ComposioBuiltIcon = (<svg width="14" height="14" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg" style={{display:'inline-block',verticalAlign:'-2px',marginRight:'6px'}} aria-hidden="true"><path d="M58.2101 18.0354L22.1511 10.6607C19.7868 10.1753 17.5635 11.9916 17.5635 14.4028V31.4851V32.3933V49.4754C17.5635 51.8867 19.7868 53.7032 22.1511 53.2177L58.2101 45.843" stroke="currentColor" strokeWidth="1.82758" strokeMiterlimit="10" strokeLinecap="round" strokeLinejoin="round"/><path d="M30.3675 4.7266C30.3676 1.33903 33.8302 -0.926498 36.9309 0.370393L37.0785 0.434773L37.0817 0.436653L56.3717 9.34549C58.0646 10.1086 59.1257 11.7994 59.1261 13.6354V21.1824C59.1261 23.9356 56.7812 26.1101 54.0417 25.8981L32.195 24.2675V39.6105L54.0384 37.9799L54.2944 37.9667C56.9179 37.9028 59.1252 40.0214 59.1098 42.6801V50.227C59.1098 52.0772 58.0208 53.7432 56.3587 54.516L56.3559 54.5169L37.0822 63.4096L37.0827 63.41C33.9397 64.8647 30.3675 62.5737 30.3675 59.1206V51.9285C30.2259 51.9844 30.0742 52.0214 29.9149 52.033L19.2542 52.8005C18.3634 52.8645 17.6054 52.1586 17.6052 51.2654V43.3507C17.6053 43.0438 17.6969 42.756 17.8543 42.5137L9.0841 43.1688H9.08083C6.34886 43.3625 4.00001 41.1949 4 38.4526V25.4254C4.0002 22.6713 6.34695 20.4959 9.08742 20.7097H9.08694L17.6631 21.3497C17.6259 21.2173 17.6053 21.0781 17.6052 20.9343V12.5969C17.6052 11.3796 18.6942 10.4511 19.8962 10.6434L30.0475 12.2675C30.1591 12.2854 30.2658 12.3159 30.3675 12.3558V4.7266ZM54.1808 39.8023H54.1774L32.195 41.4432V50.9825L57.2826 45.7388V42.6735L57.2798 42.5184C57.2047 40.9241 55.8073 39.6754 54.1808 39.8023ZM17.2528 23.1519C17.4061 23.3917 17.4952 23.6759 17.4953 23.9794V40.1801C17.4953 40.3679 17.4601 40.5478 17.398 40.7148L30.3675 39.7468V24.1307L17.2528 23.1519ZM32.195 22.4348L54.1774 24.0757L54.1808 24.0762L54.3367 24.0842C55.9444 24.1234 57.2985 22.8221 57.2985 21.1824V18.0099L32.195 12.7623V22.4348Z" fill="currentColor"/></svg>);
9 +
10 +export const ProviderMcpIcon = (<svg width="14" height="14" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" style={{display:'inline-block',verticalAlign:'-2px',marginRight:'6px'}} aria-hidden="true"><path fill="currentColor" d="M5.52 1.12a3.578 3.578 0 0 1 6.078 2.98a3.578 3.578 0 0 1 2.982 6.08l-3.292 3.293a.25.25 0 0 0 0 .354l.843.843a.749.749 0 1 1-1.06 1.06l-.844-.843a1.75 1.75 0 0 1 0-2.474L13.52 9.12a2.08 2.08 0 0 0 0-2.94a2.08 2.08 0 0 0-2.94 0L7.731 9.03A.75.75 0 0 1 6.67 7.97l2.85-2.85a2.08 2.08 0 0 0 0-2.94a2.08 2.08 0 0 0-2.94 0l-4.799 4.8A.75.75 0 0 1 .72 5.92Z"/><path fill="currentColor" d="M7.52 3.12a.749.749 0 1 1 1.06 1.06L5.731 7.03A2.079 2.079 0 0 0 8.67 9.97l2.85-2.85a.749.749 0 1 1 1.06 1.06l-2.849 2.85A3.578 3.578 0 0 1 4.67 5.97Z"/></svg>);
11 +
12 +When a product ships more than one toolkit, you pick one slug and pass it. This page is how to pick.
13 +
14 +A **Composio Built** toolkit is one Composio builds and maintains against the product's public API. A [**Provider MCP**](/docs/apps-and-toolkits/provider-mcps) toolkit connects to the product's own hosted MCP server. Both are catalog toolkits, available to every project, and both behave the same way inside a session. The catalog's Type filter carries these two labels, plus Custom for servers your own project registered. They differ in who maintains the tools, and that has consequences.
15 +
16 +## How they compare
17 +
18 +| | {ComposioBuiltIcon} Composio Built | {ProviderMcpIcon} Provider MCP |
19 +| --- | --- | --- |
20 +| Who maintains the tools | Composio | The product's team |
21 +| What it connects to | The product's public API | The product's own hosted MCP server |
22 +| Slug | Anything that doesn't end in `_mcp`, like `notion` | Ends in `_mcp`, like `notion_mcp` |
23 +| Tool naming | `NOTION_CREATE_PAGE` | `NOTION_MCP_NOTION_CREATE_PAGES` |
24 +| Auth | OAuth2, API Key, Bearer Token, or Basic, often with [Composio managed auth](/docs/authentication/custom-app-vs-managed-app) | Whatever the product's server declares: usually DCR OAuth, often none at all |
25 +| [Triggers](/docs/triggers) | Available on many toolkits | None |
26 +| Staying current | Composio regenerates and versions the toolkit | A sync produces a new dated version |
27 +
28 +Neither is a subset of the other. Tool lists differ in both directions, and there's no general rule that one supersedes the other.
29 +
30 +## Decide in this order
31 +
32 +Open the app drawer, or the comparison strip on either toolkit's detail page, and read these facts.
33 +
34 +<Figure width={1456} height={839} src="/images/docs/toolkit-apps/toolkit-detail-notion-mcp.jpg" alt="The notion_mcp toolkit page with a DCR OAuth pill, the Notion toolkits comparison strip, and a tools table of NOTION_MCP_ slugs" caption="The Notion toolkits strip on either sibling's detail page compares tools, authentication, and ownership side by side." />
35 +
36 +1. **Auth your users can complete.** The usual decider, read per toolkit rather than per label. A Composio Built toolkit often offers [Composio managed](/docs/authentication/custom-app-vs-managed-app) OAuth2 or an API key. A Provider MCP toolkit most often uses DCR OAuth, and a good number need no auth at all, which can make it the shortest path rather than the longest.
37 +2. **Triggers.** [Triggers](/docs/triggers) exist only on Composio Built toolkits. If your agent has to react to events, that settles it.
38 +3. **Tool coverage, checked in both directions.** A Provider MCP toolkit can expose capabilities only the product's own server offers, and it can also cover less of the product's API. Compare both tool lists before assuming the `_mcp` one is bigger or newer.
39 +4. **Which account your users already have.** [Siblings never share a connection](/docs/apps-and-toolkits#sibling-toolkits-never-share-a-connection), so prefer the toolkit your user is already connected to.
40 +
41 +Then pick one sibling per session or task, so your users authenticate once. [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) has the enable and disable recipes.
42 +
43 +<Callout type="info" title="Sometimes the labels tell you nothing">
44 +Not every App splits one of each kind. The Slack app holds `slack` and `slackbot`, both Composio Built, differing by the identity the tools act as. When both siblings carry the same label, decide from the tool list and the auth instead.
45 +</Callout>
46 +
47 +## If neither fits
48 +
49 +The catalog is what Composio already runs. If no toolkit covers the product, or you need tools only your team can provide, register your own remote MCP server as a [Custom MCP](/docs/extending-sessions/custom-mcp) and you get a project-private `CUSTOM_*` toolkit that works like a catalog toolkit inside your project.
50 +
51 +## If an agent picks at runtime
52 +
53 +- **Use the slug you were given.** If the request or the session config names `notion` or `notion_mcp`, use exactly that toolkit.
54 +- **Decide from facts you can already read.** Auth schemes, whether the user already has a connected account, each tool list, and trigger counts are all observable. Prefer the toolkit the user is already connected to, then the one whose auth they can complete.
55 +- **Don't read `_mcp` as newer, bigger, or already connected.** It only means the tools come from the product's own server.
56 +- **State which slug you chose** when the toolkit was ambiguous, so the user can redirect you.
57 +
58 +## Related guides
59 +
60 +<Cards>
61 + <Card icon={<Blocks />} title="Apps vs toolkits" href="/docs/apps-and-toolkits" description="How an App groups the toolkits that exist for one product" />
62 + <Card icon={<Plug />} title="What are Provider MCPs" href="/docs/apps-and-toolkits/provider-mcps" description="Toolkits backed by a product's own hosted MCP server" />
63 + <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Enable, disable, and pin toolkits for a session" />
64 +</Cards>
docs/content/docs/apps-and-toolkits/index.mdx new
+69
@@ -0,0 +1,69 @@
1 +---
2 +title: Apps vs toolkits
3 +description: What a toolkit is, how an App groups the toolkits that exist for one product, and why sibling toolkits never share a connection
4 +keywords: [app, toolkit, apps vs toolkits, toolkit slug, sibling toolkits, notion_mcp, catalog]
5 +isNew: true
6 +---
7 +
8 +A **toolkit** is the unit you name everywhere in Composio: one slug, one auth setup, one set of tools. An **App** groups the toolkits that exist for the same product, so you can compare them.
9 +
10 +Most products have exactly one toolkit, so the two words describe the same thing and you never notice the App layer. The difference matters when a product has more than one. The Notion app holds `notion`, which Composio builds on Notion's public API, and `notion_mcp`, which connects to [Notion's own hosted MCP server](/docs/apps-and-toolkits/provider-mcps).
11 +
12 +## An App is a grouping, not an address
13 +
14 +An App is a way of browsing. It has no slug, and nothing operational accepts an App name. Sessions, tool search, auth configs, connected accounts, and execution all take exact toolkit slugs:
15 +
16 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
17 +<Tab value="Python">
18 +```python
19 +session = composio.sessions.create(
20 + user_id="user_123",
21 + toolkits=["notion"] # a toolkit slug, never an App name
22 +)
23 +```
24 +</Tab>
25 +<Tab value="TypeScript">
26 +```typescript
27 +import { Composio } from '@composio/core';
28 +const composio = new Composio({ apiKey: 'your_api_key' });
29 +// ---cut---
30 +const session = await composio.create("user_123", {
31 + toolkits: ["notion"], // a toolkit slug, never an App name
32 +});
33 +```
34 +</Tab>
35 +</Tabs>
36 +
37 +## An App holds any number of toolkits
38 +
39 +They aren't always one of each kind:
40 +
41 +- **Canva** pairs `canva` with `canva_mcp`, the plainest shape.
42 +- **Supabase** holds `supabase`, `supabase_mcp`, and `supabase_read_mcp`, two of them Provider MCP.
43 +- **Slack** holds `slack` and `slackbot`, both built by Composio, differing by the identity the tools act as.
44 +
45 +## Sibling toolkits never share a connection
46 +
47 +Each toolkit has its own auth configs and its own connected accounts. Connecting `notion` does _not_ connect `notion_mcp`, even for the same user, and the managed-auth badge is per toolkit. The same separation applies to session scoping: `toolkits: ["notion"]` exposes only `notion` tools, so the agent can't discover or call `notion_mcp` tools.
48 +
49 +<Callout type="warn" title="Enabling both siblings means authenticating twice">
50 +Each toolkit your session uses needs its own connection. Enable both only when you're comparing them or migrating from one to the other. See [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) for the enable and disable recipes.
51 +</Callout>
52 +
53 +## Finding apps and toolkits in the dashboard
54 +
55 +The Toolkits page in the [dashboard](https://dashboard.composio.dev/~/project/toolkits?utm_source=docs&utm_medium=content&utm_campaign=docs-apps-and-toolkits) opens on two sections: **Custom Toolkits**, holding the servers your project registered, and the **Composio Catalog** below it. An app with more than one toolkit shows a stacked icon with a count and lists every member slug.
56 +
57 +<Figure width={1456} height={839} src="/images/docs/toolkit-apps/catalog-list.jpg" alt="The Toolkits catalog in list layout, with the Notion row showing a two-toolkit count and both slugs" caption="One row per app. Notion shows a stacked icon with a count and both member slugs, while apps with a single toolkit show one slug." />
58 +
59 +Clicking an app with more than one toolkit opens a drawer listing each sibling with its own badge, slug, auth methods, and tool and trigger counts:
60 +
61 +<Figure width={1456} height={839} src="/images/docs/toolkit-apps/app-drawer-notion.jpg" alt="The Notion app drawer listing two toolkits with their badges, slugs, auth methods, and tool and trigger counts" caption="The Notion app drawer. Each sibling carries its own badge, auth, and counts, which is what you compare when picking one." />
62 +
63 +## Related guides
64 +
65 +<Cards>
66 + <Card icon={<Plug />} title="What are Provider MCPs" href="/docs/apps-and-toolkits/provider-mcps" description="Toolkits backed by a product's own hosted MCP server" />
67 + <Card icon={<RouteIcon />} title="Composio Built vs Provider MCPs" href="/docs/apps-and-toolkits/composio-built-vs-provider-mcp" description="Which sibling to use when a product ships more than one" />
68 + <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Enable, disable, and pin toolkits for a session" />
69 +</Cards>
docs/content/docs/apps-and-toolkits/meta.json new
+9
@@ -0,0 +1,9 @@
1 +{
2 + "title": "Apps and toolkits",
3 + "defaultOpen": false,
4 + "pages": [
5 + "index",
6 + "provider-mcps",
7 + "composio-built-vs-provider-mcp"
8 + ]
9 +}
docs/content/docs/apps-and-toolkits/provider-mcps.mdx new
+61
@@ -0,0 +1,61 @@
1 +---
2 +title: What are Provider MCPs
3 +description: Toolkits backed by a product's own hosted MCP server, how their slugs and tool names work, what auth they use, and where they differ from Composio's own MCP transports
4 +keywords: [provider mcp, provider mcps, notion_mcp, mcp toolkit, dcr oauth, mcp server, toolkit versions latest, custom mcp]
5 +isNew: true
6 +---
7 +
8 +A **Provider MCP** toolkit connects to an MCP server that the product's own team hosts and maintains. Composio acts as the MCP client, syncs the tools that server publishes, and wraps them as an ordinary toolkit.
9 +
10 +That means you use one the same way you use any other toolkit. It appears in the same catalog and tool search, authenticates through the same Connect Link flow, and executes and logs the same way. `session.authorize("notion_mcp")` behaves exactly like `session.authorize("notion")`.
11 +
12 +<Figure width={1456} height={839} src="/images/docs/toolkit-apps/preview-notion-mcp.jpg" alt="The notion_mcp preview panel showing Type Provider MCP, 37 tools, 0 triggers, DCR OAuth, and a dated latest version, beside a catalog filtered to Provider MCP toolkits" caption="The notion_mcp preview. Type reads Provider MCP, with 37 tools, no triggers, DCR OAuth, and a dated version. In the list behind it, Aiwyn Tax MCP and AllTrails MCP show No Auth, so DCR OAuth isn't universal." />
13 +
14 +## How to spot one
15 +
16 +The slug ends in `_mcp`, like `notion_mcp`. The display name usually ends in " MCP", but match on the slug, not the name.
17 +
18 +Its tools carry the toolkit prefix plus the tool name the product publishes, so they look different from a Composio-built toolkit's tools:
19 +
20 +| | Composio Built | Provider MCP |
21 +| --- | --- | --- |
22 +| Slug | `notion` | `notion_mcp` |
23 +| A tool | `NOTION_CREATE_PAGE` | `NOTION_MCP_NOTION_CREATE_PAGES` |
24 +
25 +## What to expect
26 +
27 +- **Auth varies per toolkit.** Most use [DCR OAuth](/reference/glossary#dcr-oauth) against the product's own server. A good number need no auth at all, and a few use an API key or OAuth2. Read what the toolkit declares rather than assuming from the label.
28 +- **No [triggers](/docs/triggers).** Triggers exist only on toolkits Composio builds. If your agent has to react to events, use the Composio-built sibling.
29 +- **The tool surface follows the product.** Tool names, descriptions, and schemas are limited to what the upstream server publishes, so a sparse schema is the product's, not a stale catalog. The surface changes when a sync produces a new dated version.
30 +
31 +<Callout type="info" title="You don't need to create an auth config">
32 +`session.authorize("notion_mcp")` returns a Connect Link with nothing set up in advance. DCR OAuth registers the client with the product's server for you, so a Provider MCP toolkit having no Composio managed auth does _not_ mean you have to bring credentials. Create an auth config only to pin scopes or use your own OAuth app.
33 +</Callout>
34 +
35 +<Callout type="warn" title="Listing the tools on v3 returns nothing">
36 +A Provider MCP toolkit keeps its tools only in the latest dated version, so `GET /api/v3/tools?toolkit_slug=notion_mcp` comes back empty even though the toolkit is healthy. Add `toolkit_versions=latest`, or use v3.1, which always resolves the latest version. Sessions and tool search are unaffected either way. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
37 +</Callout>
38 +
39 +## Provider MCP vs MCP as a transport
40 +
41 +MCP shows up on both sides of Composio, and the two are independent. A Provider MCP toolkit is about where tools come from, with Composio acting as the MCP client. The MCP transports are about how your agent reaches Composio's tools.
42 +
43 +| You want to | Use | Read more |
44 +| --- | --- | --- |
45 +| Expose one user's session to an MCP-compatible client | The session MCP endpoint (`mcp: true`) | [Using sessions via MCP](/docs/sessions-via-mcp) |
46 +| Connect an existing MCP client to Composio without the SDK | Composio Connect | [Composio Connect](/docs/composio-connect) |
47 +| Use tools from a product's own hosted MCP server | A Provider MCP toolkit, like `notion_mcp` | This page |
48 +
49 +The two stack without interacting, so you can enable `notion_mcp` in a session and serve it over the session MCP endpoint.
50 +
51 +## Your own server is Custom MCP, not Provider MCP
52 +
53 +A Provider MCP toolkit is a catalog toolkit backed by the product's server, available to every project. If you want to bring _your own_ remote MCP server, that's [Custom MCP](/docs/extending-sessions/custom-mcp): you register the server into your project and get a project-private `CUSTOM_*` toolkit that's never grouped into an App. The two behave alike at runtime, since Composio is the MCP client in both.
54 +
55 +## Related guides
56 +
57 +<Cards>
58 + <Card icon={<RouteIcon />} title="Composio Built vs Provider MCPs" href="/docs/apps-and-toolkits/composio-built-vs-provider-mcp" description="Which sibling to use when a product ships more than one" />
59 + <Card icon={<Blocks />} title="Apps vs toolkits" href="/docs/apps-and-toolkits" description="How an App groups the toolkits that exist for one product" />
60 + <Card icon={<Terminal />} title="Custom MCP" href="/docs/extending-sessions/custom-mcp" description="Register your own remote MCP server into a project" />
61 +</Cards>
docs/content/docs/authentication/custom-app-vs-managed-app.mdx
+1 -1
@@ -9,7 +9,7 @@ Composio supports two ways to authenticate users with toolkits.
9 - **[Composio managed apps](/toolkits/managed-auth)**: Composio registers and maintains OAuth apps for popular toolkits such as GitHub, Gmail, and Slack. You do not need to register your own OAuth app.
10 - **Custom auth configs**: You provide your own OAuth app, API key, bearer token, or other credentials and tell Composio to use them for a toolkit.
11
12 -This page covers when to use each, how to create a custom auth config, and how to wire it into a session.
12 +This page covers when to use each, how to create a custom auth config, and how to wire it into a session. Throughout this page, "app" means the OAuth app you or Composio register with the provider, *not* an [App in the toolkit catalog](/docs/apps-and-toolkits).
13
14 Both options use Composio to store and refresh connected-account credentials. Choosing your own OAuth app changes app ownership, branding, scopes, and provider quota, not [token custody](/docs/security/token-custody#oauth-app-ownership-and-token-custody).
15
docs/content/docs/composio-connect.mdx
+13 -11
@@ -16,6 +16,8 @@ Composio Connect is an MCP server at `https://connect.composio.dev/mcp` that giv
16
17 Rather than exposing every app tool directly, Composio exposes **7 meta-tools** that let the agent discover what's available, authorize apps on demand, and execute tools across apps in parallel. The first time your agent needs an app, Composio generates an OAuth link you approve in your browser; after that the connection persists across sessions. See [Available MCP tools](#available-mcp-tools) for the full list.
18
19 +MCP here is the transport between your client and Composio; Provider MCP toolkits in the catalog, such as `notion_mcp`, are ordinary toolkits your agent can discover over this same connection. See [Apps and toolkits](/docs/apps-and-toolkits).
20 +
21 To get started, pick your client below.
22
23 <ConnectFlow>
@@ -455,15 +457,15 @@ Your agent will prompt you to connect apps when needed. If you want to connect a
457
458 ## Available MCP tools
459
458 -Composio Connect exposes 7 meta-tools that orchestrate access to all supported apps. Your agent uses these to discover, connect, and execute upstream tools — you don't need to call them directly.
460 +Composio Connect exposes 7 meta-tools that orchestrate access to all supported apps. Your agent uses these to discover, connect, and execute upstream tools. You don't need to call them directly.
461
460 -- **`COMPOSIO_SEARCH_TOOLS`** — Search the Composio catalog and return relevant tools for a user request, along with a suggested execution plan.
461 -- **`COMPOSIO_GET_TOOL_SCHEMAS`** — Fetch full input schemas for tool slugs returned by search.
462 -- **`COMPOSIO_MULTI_EXECUTE_TOOL`** — Execute one or more discovered tools in parallel across connected apps (up to 50 per call).
463 -- **`COMPOSIO_MANAGE_CONNECTIONS`** — Create, list, rename, or remove OAuth connections to upstream apps.
464 -- **`COMPOSIO_WAIT_FOR_CONNECTIONS`** — Wait for a user to complete an OAuth flow before the agent continues.
465 -- **`COMPOSIO_REMOTE_WORKBENCH`** — Run Python in a remote sandbox for bulk operations or processing large tool responses.
466 -- **`COMPOSIO_REMOTE_BASH_TOOL`** — Run bash in a remote sandbox for file processing and large data handling.
462 +- **`COMPOSIO_SEARCH_TOOLS`**: Search the Composio catalog and return relevant tools for a user request, along with a suggested execution plan.
463 +- **`COMPOSIO_GET_TOOL_SCHEMAS`**: Fetch full input schemas for tool slugs returned by search.
464 +- **`COMPOSIO_MULTI_EXECUTE_TOOL`**: Execute one or more discovered tools in parallel across connected apps (up to 50 per call).
465 +- **`COMPOSIO_MANAGE_CONNECTIONS`**: Create, list, rename, or remove OAuth connections to upstream apps.
466 +- **`COMPOSIO_WAIT_FOR_CONNECTIONS`**: Wait for a user to complete an OAuth flow before the agent continues.
467 +- **`COMPOSIO_REMOTE_WORKBENCH`**: Run Python in a remote sandbox for bulk operations or processing large tool responses.
468 +- **`COMPOSIO_REMOTE_BASH_TOOL`**: Run bash in a remote sandbox for file processing and large data handling.
469
470 ## Troubleshooting
471
@@ -472,12 +474,12 @@ Composio Connect exposes 7 meta-tools that orchestrate access to all supported a
474 1. Confirm the MCP server is connected. In Claude Desktop, go to **Settings > Connectors** and check that Composio shows a `CUSTOM` badge. In Claude Code, run `/mcp` and confirm Composio is enabled.
475 2. Clear the connector cache. In Claude Desktop: click the **⋮** next to Composio and select **Clear cache**.
476 3. If the issue persists, disconnect and re-add the connector:
475 - - **Claude Desktop** — click **⋮ > Disconnect**, then **Remove**. Re-add via **Add custom connector**.
476 - - **Claude Code** — re-run the setup command from the Claude Code section above.
477 + - **Claude Desktop**: click **⋮ > Disconnect**, then **Remove**. Re-add via **Add custom connector**.
478 + - **Claude Code**: re-run the setup command from the Claude Code section above.
479
480 ### The OAuth link expired or didn't open
481
480 -OAuth links are short-lived. If the browser window doesn't open or the link has expired, ask your agent to retry the action — Composio will generate a fresh link.
482 +OAuth links are short-lived. If the browser window doesn't open or the link has expired, ask your agent to retry the action. Composio will generate a fresh link.
483
484 ### An app action is failing with an auth error
485
docs/content/docs/configuring-sessions.mdx
+38
@@ -207,6 +207,44 @@ Requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (
207
208 The session API rejects unknown root keys with a `400` before it creates anything. A typo such as a singular `toolkit` fails the request instead of silently creating an unrestricted session.
209
210 +## Sibling toolkits
211 +
212 +When a product has more than one toolkit, each has its own slug, and enabling one never enables the other. Enable `["notion_mcp"]` to use only Notion's Provider MCP toolkit, or disable one sibling to exclude it while keeping other toolkits discoverable. You can't pass an App: the `toolkits` lists take exact toolkit slugs only. See [Apps vs toolkits](/docs/apps-and-toolkits) for what the siblings are, and [Composio Built vs Provider MCPs](/docs/apps-and-toolkits/composio-built-vs-provider-mcp) for picking one.
213 +
214 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
215 +<Tab value="Python">
216 +```python
217 +# Only the Provider MCP toolkit
218 +session = composio.sessions.create(
219 + user_id="user_123",
220 + toolkits=["notion_mcp"]
221 +)
222 +
223 +# Keep other toolkits discoverable, but exclude notion_mcp
224 +session = composio.sessions.create(
225 + user_id="user_123",
226 + toolkits={"disable": ["notion_mcp"]}
227 +)
228 +```
229 +</Tab>
230 +<Tab value="TypeScript">
231 +```typescript
232 +import { Composio } from '@composio/core';
233 +const composio = new Composio({ apiKey: 'your_api_key' });
234 +// ---cut---
235 +// Only the Provider MCP toolkit
236 +const session = await composio.create("user_123", {
237 + toolkits: ["notion_mcp"],
238 +});
239 +
240 +// Keep other toolkits discoverable, but exclude notion_mcp
241 +const session2 = await composio.create("user_123", {
242 + toolkits: { disable: ["notion_mcp"] },
243 +});
244 +```
245 +</Tab>
246 +</Tabs>
247 +
248 ## Direct tools preset
249
250 The direct tools preset preloads every tool allowed by session filters into the session's tool list and disables session meta tools by default. Use it for specialized agents with a narrow tool set that don't need dynamic tool discovery, in-chat auth, or workbench helpers.
docs/content/docs/extending-sessions/custom-mcp.mdx
+4
@@ -13,6 +13,10 @@ Custom MCP is experimental. The APIs may change.
13
14 This is different from [Local Tools and Toolkits](/docs/extending-sessions/local-tools-and-toolkits), which run inside your app. A Custom MCP server runs on its own public HTTPS URL.
15
16 +<Callout type="info" title="Custom MCP vs Provider MCP">
17 +A Custom MCP toolkit registers a remote server for your project or one user and has a `CUSTOM_*` slug. A Provider MCP toolkit, such as `notion_mcp`, connects to a product's hosted MCP server and is part of the catalog. See [Apps and toolkits](/docs/apps-and-toolkits).
18 +</Callout>
19 +
20 ## How it works
21
22 1. **Get** a remote MCP server at a public HTTPS URL: your own, or an existing one.
docs/content/docs/how-composio-works.mdx
+2
@@ -73,6 +73,8 @@ architecture-beta
73
74 Below we're going to explain each of the concepts that come with a session.
75
76 +Some products have multiple toolkits. The catalog can group them into an **App** for comparison, such as `notion` and `notion_mcp`. Each toolkit keeps its own tools and connections. Configure sessions with exact toolkit slugs. See [Apps vs toolkits](/docs/apps-and-toolkits).
77 +
78 ## Users
79
80 A user is an identifier from your app. Composio stores connections under that ID, so tools run with the right account and stay isolated from other users. Use a stable identifier like your database ID, never one that can change.
docs/content/docs/meta.json
+1
@@ -11,6 +11,7 @@
11 "agent-setup",
12 "---Core concepts---",
13 "how-composio-works",
14 + "apps-and-toolkits",
15 "configuring-sessions",
16 "session-configs",
17 "instant-tools",
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+3 -3
@@ -241,12 +241,12 @@ span many toolkits without bloating context.
241
242 ## Beyond the MCP URL
243
244 -A session isn't only an MCP endpoint — it's also a normal SDK object, which is handy for non-agent
244 +A session isn't only an MCP endpoint: it's also a normal SDK object, which is handy for non-agent
245 code paths.
246
247 -### Native tools for your framework
247 +### Direct tools for your framework
248
249 -`session.tools()` returns provider-wrapped native tools for OpenAI, Anthropic, LangChain, the Vercel
249 +`session.tools()` returns provider-wrapped direct tools for OpenAI, Anthropic, LangChain, the Vercel
250 AI SDK, and others, so you skip manual schema wiring. With the direct-tools preset it returns your
251 exact fixed tool set; by default it returns the meta-tools that drive runtime discovery.
252
docs/content/docs/sessions-via-mcp.mdx
+4
@@ -16,6 +16,10 @@ If you use Codex or Claude Code and did not explicitly choose MCP, install the n
16 Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](/docs/extending-sessions/custom-mcp).
17 </Callout>
18
19 +<Callout type="info">
20 +MCP on this page is the transport that exposes a session to a client. It is independent of Provider MCP toolkits such as `notion_mcp`, which are catalog toolkits you can use over any transport. See [Apps and toolkits](/docs/apps-and-toolkits).
21 +</Callout>
22 +
23 ## The MCP endpoint
24
25 If you use a scoped project API key, enable **Session management** to create and configure sessions and **Session tool execution** for session-linked MCP access. See [API key permissions](/reference/authenticating-to-composio/project-api-key-permissions) for access levels and routes.
docs/content/reference/glossary.mdx
+24 -4
@@ -7,6 +7,30 @@ keywords: [glossary, definitions, terminology]
7
8 <Glossary>
9
10 +<GlossaryTerm name="Provider MCP">
11 +A toolkit that connects to the product's own hosted MCP server, maintained by that product. Its slug ends in `_mcp` (for example, `notion_mcp`). Auth varies per toolkit: usually DCR OAuth, often none at all. Not to be confused with a provider, which is an AI-framework adapter. See [Apps and toolkits](/docs/apps-and-toolkits).
12 +</GlossaryTerm>
13 +
14 +<GlossaryTerm name="Direct tools (provider package)">
15 +Tools you access through provider packages with `session.tools()` and call directly, rather than over MCP. Both paths give the agent the same capabilities, but tools called directly integrate with your AI framework and support modifiers and custom tools. Previously called native tools.
16 +</GlossaryTerm>
17 +
18 +<GlossaryTerm name="DCR OAuth">
19 +OAuth Dynamic Client Registration, the auth scheme many Provider MCP toolkits use. The client registers itself with the product's MCP server automatically, so your user just approves access and there is no OAuth app to register.
20 +</GlossaryTerm>
21 +
22 +<GlossaryTerm name="Custom MCP">
23 +Your own remote MCP server registered into your project as a toolkit with a `CUSTOM_*` slug, usable in sessions alongside catalog toolkits. Custom MCP toolkits can be shared within your project or private to one user. See [Custom MCP](/docs/extending-sessions/custom-mcp).
24 +</GlossaryTerm>
25 +
26 +<GlossaryTerm name="Composio Built">
27 +A toolkit that Composio builds and maintains on the product's public API, like the `notion` toolkit. Composio Built toolkits can have triggers and commonly authenticate with `OAUTH2` or `API_KEY`, often through Composio Managed Auth. See [Apps and toolkits](/docs/apps-and-toolkits).
28 +</GlossaryTerm>
29 +
30 +<GlossaryTerm name="App">
31 +A grouping of sibling toolkits for one product in the catalog. The Notion app, for example, contains the `notion` and `notion_mcp` toolkits. An App is a way of browsing: it has no slug, and sessions, search, and auth configs always take exact toolkit slugs. See [Apps and toolkits](/docs/apps-and-toolkits).
32 +</GlossaryTerm>
33 +
34 <GlossaryTerm name="Auth Config">
35 A blueprint that defines how authentication works for a toolkit: the auth method (`OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`), scopes, and credentials. A [session](/docs/how-composio-works) creates one automatically when it needs one. To use your own OAuth credentials or non-default scopes, [create a custom one](/docs/auth-configuration/custom-auth-configs).
36 </GlossaryTerm>
@@ -63,10 +87,6 @@ A set of tools included in every session: `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET
87 Middleware that transforms tool behavior. [Schema modifiers](/docs/tools-direct/modify-tool-behavior/schema-modifiers) change a tool's schema before the agent sees it, [before-execution modifiers](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers) change arguments before a tool runs, and [after-execution modifiers](/docs/tools-direct/modify-tool-behavior/after-execution-modifiers) transform the result. In Python, [`@before_file_upload`](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers#before-file-upload-python) intercepts local paths for `file_uploadable` parameters before read and upload.
88 </GlossaryTerm>
89
66 -<GlossaryTerm name="Native Tools">
67 -Tools you access through provider packages with `session.tools()` and call directly, rather than over MCP. Both paths give the agent the same capabilities, but tools called directly integrate with your AI framework and support modifiers and local tools.
68 -</GlossaryTerm>
69 -
90 <GlossaryTerm name="Organization">
91 The top-level Composio account entity. It contains team members and projects.
92 </GlossaryTerm>
docs/decisions/README.md
+1
@@ -13,3 +13,4 @@ Read these when a docs change touches an existing architecture, generated-data p
13 and snapshot-miss toolkit page fallback.
14 - `toolkits.md` - toolkit page data, rendering, and live Instant eligibility filter decisions.
15 - `cookbooks-revamp-plan.md` - historical cookbook revamp tracker.
16 +- `apps-and-toolkits.md` - Apps, Composio Built toolkits, and Provider MCP toolkits: vocabulary, sibling rendering, and search-contract wording.
docs/decisions/apps-and-toolkits.md new
+62
@@ -0,0 +1,62 @@
1 +# Apps, Composio Built toolkits, and Provider MCP toolkits
2 +
3 +## Decision
4 +
5 +When one product ships more than one toolkit, the docs group those toolkits under an **App** and label each member by who maintains it: **Composio Built** for a toolkit Composio builds on the product's public API (descriptors `REST API`, `GraphQL API`, `Graph API`), and **Provider MCP** for a toolkit that connects to the product's own hosted MCP server (descriptor `MCP server`, slug `<slug>_mcp`, name `X MCP`). An App is presentation and decisioning context, not a merge: every member keeps its own slug, auth config, connected account, tool slugs, and readiness, and nothing in the product (sessions, search, execution, auth configs, connected accounts) accepts an App name. You always name an exact toolkit slug.
6 +
7 +The docs stop using "native" as a toolkit label anywhere, rename the glossary entry "Native Tools" to "Direct tools (provider package)", and always write "Provider MCP" as the capitalised two-word label so that "provider" on its own keeps meaning an LLM-framework adapter. **Custom MCP** (`CUSTOM_*`, your own remote MCP server registered into your project) stays a separate concept with no App, and Composio's own MCP transports (the session MCP endpoint and Composio Connect) are described as transports, never as toolkits. Decided by JJ on 2026-08-21 after the team's 2026-08-20 `app` grouping decision.
8 +
9 +## Context
10 +
11 +Provider MCP toolkits are already first-class catalog toolkits (73 `*_mcp` slugs live in the catalog as of 2026-09-01, 30 of them with a Composio Built sibling, including `canva`, `linear`, `notion`, `clickup`, and `supabase`), and the set is still growing. Until now no docs page, glossary term, skill, or toolkit page explained what `tavily_mcp` is or how it relates to `tavily`; the only prose was a changelog line calling them "external MCPs now available as native toolkits". The dashboard ships a grouped catalog and the backend adds an `app` field on the toolkit (PLEN-3109) plus related-toolkit facts in session search (`is_provider_mcp`, auth scheme, triggers, tool count, a reviewed default per ambiguity group, at most one alternative; an explicitly named slug always wins).
12 +
13 +The naming choice is constrained by collisions that already live in agent-facing text:
14 +
15 +- **native** means three things today: the glossary "Native Tools" (tools called directly through a provider package rather than over MCP), the "native agent plugin" (CLI-backed Codex and Claude Code plugin), and the public API field `type: "native" | "custom"` (catalog vs project-registered, so `tavily_mcp` is itself `type: native`). The dashboard rejected "Native" for the REST sibling for the same reason.
16 +- **provider** means an LLM-framework adapter (`/docs/providers`, "provider package").
17 +- **app** appears in the LLM-guardrail terminology table as a legacy v1/v2 word that agents are told to translate to "toolkit", and "OAuth app" / "managed app" appear throughout the authentication pages.
18 +- **custom** already covers custom auth configs, SDK custom tools (`LOCAL_`), Custom MCP (`CUSTOM_`), custom providers, and the legacy custom MCP server API.
19 +- Internally the same concept has been called family, toolkit group, ambiguity group, app family, implementation, and interface; internal `group` means tenancy.
20 +
21 +Alternatives considered: "API toolkit" vs "MCP toolkit" (symmetric, but hides who maintains the toolkit, which is the fact developers ask about first); "Composio Native" vs "Provider MCP" (the 2026-08-18 pill vocabulary, rejected because of the three live meanings of "native"); a blind "prefer MCP" rule in search (rejected on 2026-08-19: Provider MCP toolkits have no triggers and often a narrower surface, and auth scheme is the usual decider).
22 +
23 +Facts the docs must not contradict: Provider MCP toolkits have no triggers; tool annotations are dropped on MCP sync today, so tag filters do not apply to their tools; Custom MCP accepts `NO_AUTH`, `API_KEY`, and `DCR_OAUTH` only (classic OAuth2 and CIMD are unsupported as of 2026-08-21, PLEN-3094); `CIMD_OAUTH` exists for Provider MCP toolkits only once the platform change lands; the search-response facts and the `app` field have no shipped engineering artifact as of 2026-08-21.
24 +
25 +## Consequences
26 +
27 +Vocabulary, to be used identically in docs, dashboard copy, and the agent skills:
28 +
29 +| Concept | User-facing | Agent-facing facts | Internal shorthand (never published) |
30 +| --- | --- | --- | --- |
31 +| Group of sibling toolkits for one product | App (field `app`) | `app` on the toolkit; related toolkits under the same app in search | toolkit group, family, ambiguity group |
32 +| Toolkit Composio builds on the product's public API | Composio Built (`REST API` / `GraphQL API` / `Graph API`) | `is_provider_mcp: false`, `auth_schemes`, `triggers_count`, `tools_count` | native toolkit, `toolkit_type: api` |
33 +| Toolkit that connects to the product's own MCP server | Provider MCP (`MCP server`), slug `<slug>_mcp` | `is_provider_mcp: true`; `type: native` | provider MCP, admin MCP, `toolkit_type: mcp` |
34 +| Your own remote MCP server in your project | Custom MCP, slug `CUSTOM_*` | `type: custom`; project-private | custom toolkit (dashboard) |
35 +| In-process SDK tools | Custom tools (`LOCAL_`) | n/a | local tools |
36 +| Composio's MCP transports | Session MCP endpoint (`session.mcp.url`), Composio Connect | n/a | Composio MCP |
37 +| Tools called directly through a provider package | Direct tools (provider package) | n/a | native tools (old glossary name) |
38 +
39 +Operational rules for docs and agent surfaces:
40 +
41 +- Tavily is the canonical example pair (`tavily`, API key, 5 tools; `tavily_mcp`, DCR OAuth, 5 tools, different tool set).
42 +- A Provider MCP toolkit page states in its first line that it connects to the product's own MCP server. Toolkit pages with siblings render a "Part of the App" strip; derive siblings from the `_mcp`, `_graphql`, `_graph` slug suffix until the `app` field is available, then switch.
43 +- The guide describes the search contract (facts, reviewed default, explicit slug wins) as rolling out until the platform ships it, and never calls a sibling "recommended" until the API returns a reviewed default.
44 +- The LLM-guardrail terminology row for "apps / appType" states that the legacy v1/v2 word meant toolkit and that the current App is a grouping of sibling toolkits; agents must not translate the current term.
45 +- "App" is never used for an OAuth app; the authentication pages say "OAuth app" or "managed app".
46 +- The `composio` skill carries one stable rule: siblings are separate toolkits with separate connections; use the slug the user or code names; when unspecified, read the facts (auth scheme, connected state, triggers, tool count), prefer the toolkit the user can authenticate, and say which one you chose; do not assume `_mcp` is newer, larger, or shares a connection. The `composio-cli` and `composio-runtime` skills get the same rule as follow-ups.
47 +- Pages that carry the vocabulary: `content/docs/apps-and-toolkits.mdx` (guide, Core concepts), `how-composio-works.mdx`, `configuring-sessions.mdx`, `reference/glossary.mdx`, `extending-sessions/custom-mcp.mdx`, `sessions-via-mcp.mdx`, `composio-connect.mdx`, `authentication/custom-app-vs-managed-app.mdx`, `toolkits/managed-auth.mdx`, `agent/knowledge.md`, `agent/instructions/context.md`, `lib/llm-guardrails/session.ts` and `terminology.ts`, `components/toolkits/toolkit-detail.tsx` with `scripts/generate-toolkits.ts` and the toolkit `.md` renderer, and `skills/composio/*`. Generated pages (`toolkits/meta-tools/*`, API reference) change only through their generators.
48 +
49 +Follow-up work, each gated on engineering: mirror the exact `app` JSON shape (PLEN-3109); mirror the search fields and the reviewed-default list; add `DCR OAuth` and `CIMD` to the glossary auth schemes when `CIMD_OAUTH` is public; update the Custom MCP page if plain OAuth2 lands (PLEN-3094); write the changelog entry on GA; flip "rolling out" callouts; realign the 2026-09-02 changelog entry, which still calls these "native toolkits"; render the App strip and sibling slug on toolkit pages (`components/toolkits/toolkit-detail.tsx` plus `scripts/generate-toolkits.ts`); regenerate the toolkit snapshot so `/toolkits/notion_mcp.md` resolves.
50 +
51 +## Verification
52 +
53 +- `bun run build`, `bun run lint:links`, and `bun run test` pass from `docs/`.
54 +- `git grep -n "Native Tools" docs/content docs/lib docs/agent` returns only the alias sentence in the glossary. `git grep -n -i "native toolkit" docs/content skills` still returns `docs/content/changelog/02-09-26.mdx` lines 3 and 7, which keep their original wording as a dated historical record; realigning that entry is tracked as follow-up work below.
55 +- `reference/glossary.mdx` defines App, Composio Built, Provider MCP, Custom MCP, and Direct tools (provider package).
56 +- Not yet true, tracked as follow-up: toolkit pages do not render the App strip or the sibling slug. `/toolkits/tavily_mcp.md` mentions its App context, `/toolkits/tavily.md` does not, and no toolkit renderer or generator changed in this pass.
57 +- The agent eval (12 questions, kept in the docs PR description) passes against the preview `.md` endpoints and the updated `composio` skill: siblings do not share a connection, `toolkits: ["tavily"]` does not expose `tavily_mcp`, App names are not valid in `toolkits`, `CUSTOM_ACME` is unrelated to `acme_mcp`, `session.mcp.url` does not mean Provider MCP toolkits, triggers imply Composio Built, and "native tool" means direct tools through a provider package.
58 +- The shipped dashboard tooltip and switcher heading use the same three labels as the guide.
59 +
60 +## Update 2026-09-01
61 +
62 +The dashboard grouping shipped with the labels "Composio Built", "Provider MCP", and "Custom" (Type filter, badges, app drawer, and the toolkit-detail comparison strip). A live probe of the public API on 2026-09-01 (`GET /api/v3.1/toolkits/{slug}`) shows no `app` field and no `toolkit_type` field, and session search returns no related-toolkit facts. The customer docs therefore describe the dashboard experience and exact toolkit slugs only, and document no grouping or search API fields until they ship. The shipped docs and skills use Notion (`notion` / `notion_mcp`, both verified live) as the canonical example pair instead of Tavily, because Notion is the pair shown in the dashboard screenshots and it is the only candidate pair whose tool and trigger counts (53 tools / 8 triggers against 37 / 0) illustrate the triggers difference. Tavily does still have both toolkits; the earlier note that it did not was wrong. The markdown exporter's fallback tab label in `docs/lib/source.ts` was also updated from "Native Tools" to "Direct tools" in this pass, so the Verification grep for "Native Tools" now returns only the glossary alias sentence.
docs/lib/llm-guardrails/session.ts
+4 -2
@@ -28,11 +28,11 @@ export const SESSION_GUARDRAILS = `
28
29 ## 1. Recommended Integration: Sessions
30
31 -For agent tool delivery, Composio supports **Native Tools** (with a provider package) and **MCP** (no provider package needed).
31 +For agent tool delivery, Composio supports **direct tools through a provider package** (with a provider package) and **MCP** (no provider package needed).
32
33 For application-owned tools or deterministic backend code, use [managed authentication with Proxy Execute](/docs/authentication/managed-auth-for-custom-tools). A session can provide a user-scoped runtime context without an LLM or MCP. Composio authenticates provider requests server-side; connected-account reads redact credentials and aren't a supported token-export workflow.
34
35 -### Native Tools
35 +### Direct tools (provider package)
36
37 #### Python
38
@@ -91,6 +91,8 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
91
92 ## 2. Integration Notes
93
94 +- App grouping does not combine toolkit connections or tools. Configure exact toolkit slugs, such as \`notion\` or \`notion_mcp\`, and use the one the request names.
95 +
96 - \`composio.create(user_id)\` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; \`user_id\` goes to \`composio.create()\` — individual tool calls in session mode don't take one.
97 - Execute session tool calls through the session, never through a user ID: either \`session.execute(tool_slug, arguments=...)\` / \`session.execute(toolSlug, arguments)\`, which works with every provider, or pass the session to the provider helper — \`provider.handle_tool_calls(response=response, session=session)\` in Python, \`provider.handleToolCalls(session, response)\` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: \`executeToolCall(session, call)\` in TypeScript, \`session=session\` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with \`"can only be called inside a tool-router session"\`.
98 - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
docs/lib/llm-guardrails/terminology.ts
+1 -1
@@ -15,7 +15,7 @@ If you encounter these terms in error messages, old documentation, or user promp
15 |---|---|---|
16 | entity ID | user ID | \`user_id\` parameter |
17 | actions | tools | e.g., \`GITHUB_CREATE_ISSUE\` is a *tool* |
18 -| apps / appType | toolkits | e.g., \`github\` is a *toolkit* |
18 +| apps / appType (legacy v1/v2 API field) | toolkits | e.g., \`github\` is a *toolkit*. The current word **App** is *not* legacy: it names a catalog grouping of sibling toolkits (the Notion app groups \`notion\` and \`notion_mcp\`); do not translate it |
19 | integration / integration ID | auth config / auth config ID | \`auth_config_id\` parameter |
20 | connection | connected account | \`connected_accounts\` namespace |
21 | ComposioToolSet / OpenAIToolSet | \`Composio\` class with a provider | \`Composio(provider=...)\` |
docs/lib/source.ts
+1 -1
@@ -442,7 +442,7 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
442 result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
443 result = result.replace(/<\/FrameworkOption>/g, '');
444
445 - const tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };
445 + const tabLabelMap: Record<string, string> = { native: 'Direct tools', mcp: 'MCP' };
446 result = result.replace(
447 /<IntegrationTabs[\s\S]*?tabs=\{\[([\s\S]*?)\]\}[\s\S]*?>/g,
448 (_, tabsContent: string) => {
docs/public/images/docs/toolkit-apps/app-drawer-notion.jpg
Binary files /dev/null and b/docs/public/images/docs/toolkit-apps/app-drawer-notion.jpg differ
docs/public/images/docs/toolkit-apps/catalog-list.jpg
Binary files /dev/null and b/docs/public/images/docs/toolkit-apps/catalog-list.jpg differ
docs/public/images/docs/toolkit-apps/preview-notion-mcp.jpg
Binary files /dev/null and b/docs/public/images/docs/toolkit-apps/preview-notion-mcp.jpg differ
docs/public/images/docs/toolkit-apps/toolkit-detail-notion-mcp.jpg
Binary files /dev/null and b/docs/public/images/docs/toolkit-apps/toolkit-detail-notion-mcp.jpg differ
skills/composio/SKILL.md
+2
@@ -64,6 +64,8 @@ Do not turn an explanation, documentation lookup, or narrow bug fix into onboard
64 11. Do not invent repository facts. Never claim that a file, framework, environment loader, identity field, agent path, or dependency exists until it was provided or inspected. If codebase context is unavailable, state the unknown and ask for access or one necessary detail.
65 12. In SDK or API examples, use exact identifiers and call shapes from a current public page or schema. Copy the documented shape for the requested language instead of translating names between TypeScript and Python; if a required detail is not documented, explain the behavior without inventing code.
66
67 +13. A product may ship both a Composio Built toolkit (`notion`) and a Provider MCP toolkit (`notion_mcp`) grouped as one App in the catalog. They are separate toolkits with separate connections. Use the slug the user or the code names; when the slug is unspecified, compare auth schemes, connected state, tool lists, and triggers, prefer the toolkit the user can authenticate, and state which one you chose. Never assume the `_mcp` toolkit is newer, larger, or shares a connection with its sibling.
68 +
69 ## Canonical information
70
71 Use bundled references for stable decisions. A user-facing source list contains only public `https://docs.composio.dev/...` pages actually consulted; bundled reference names, local paths, and `file://` URLs are omitted. For versions, provider adapters, client-specific setup, toolkit behavior, or APIs that may have changed, use the current canonical documentation and current CLI or tool schemas as the primary sources before answering or editing code:
skills/composio/references/errors.md
+4
@@ -47,6 +47,10 @@ This appears on a real tool execution after the project and session reached the
47
48 Keep the same project key and application user ID. Generate a fresh Connect Link for that integration, reconnect the provider account, and retry the safe call. If a link expired, request a new one.
49
50 +### No active connection on a sibling toolkit
51 +
52 +A `NoActiveConnection` error can appear when the user connected one toolkit of a product's App but the execution targets its sibling: the connection is on `notion` while the tool belongs to `notion_mcp`, or the reverse. Sibling toolkits never share a connection. Link the exact slug the execution uses, or switch the execution to the slug that is already connected.
53 +
54 ### For You client authentication
55
56 If the MCP client itself cannot authenticate, verify the consumer endpoint, OAuth session, or `ck_...` header path from the For You guide. Do not substitute a Platform project key.
skills/composio/references/for-you.md
+2
@@ -60,6 +60,8 @@ composio link <toolkit>
60 composio execute <TOOL_SLUG> -d '{...}'
61 ```
62
63 +`composio search` can return two toolkits for one product, such as `notion` and `notion_mcp`, and they are separate toolkits with separate connections. `composio link` links exactly the slug you give it, so link the same slug you plan to execute.
64 +
65 Use `composio login --no-wait | jq` when the agent cannot open a browser. Give the returned login URL to the user and complete authentication with the returned key. Once installed, prefer the bundled `composio-cli` skill for current command and flag details.
66
67 ## Connect apps when the task needs them
skills/composio/references/platform.md
+4
@@ -136,6 +136,10 @@ Use the direct-tools preset only for a narrow, deterministic agent with a fixed
136
137 If the application has its own connect UI, use session authorization and connection-state methods and suppress in-chat connection prompts. Use managed auth initially. Create a custom auth config only for the application's OAuth branding, additional scopes, dedicated provider quotas, or self-hosted or regional requirements.
138
139 +### Composio Built or Provider MCP
140 +
141 +Some products ship more than one toolkit grouped as one App in the catalog, for example a Composio Built toolkit (`notion`) and a Provider MCP toolkit backed by the product's own MCP server (`notion_mcp`). An App can hold more than two, and they are not always one of each kind: `supabase` groups with `supabase_mcp` and `supabase_read_mcp`, and `slack` groups with `slackbot`, which are both Composio Built. They are separate toolkits with separate auth configs and connected accounts. Session config takes exact slugs, never an App: enable one sibling (`toolkits: ["notion"]`), enable both (`toolkits: ["notion", "notion_mcp"]`), or use the disable list to remove the sibling the agent should not see (syntax in `configuring-sessions.md`). Enabling `notion` does not expose `notion_mcp`, and the siblings never share a connection. When the request or code names a slug, use it. Otherwise compare auth schemes, connected state, tool lists, and triggers (triggers exist only on Composio Built toolkits today), prefer the toolkit the user can authenticate, and state which one you chose. Do not assume Provider MCP means DCR OAuth: some need no auth at all, and a few use API Key or OAuth2. Read what the toolkit declares. Details: `https://docs.composio.dev/docs/apps-and-toolkits.md`. A Custom MCP server registered into the project (slug `CUSTOM_*`) is separate from both; see the `extending-sessions` guides.
142 +
143 ## Handle advanced product work
144
145 Do not force advanced requests through first-time setup. Route them to current documentation: