@devries-cameron20 / composio-1 / commits / c062d234e
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.

docs: align toolkit grouping guidance with current contracts

Jeevesh Jain committed Nov 16, 2026 at 16:04 UTC c062d234ed734e09db45667ff9ea0245cf31f3aa
14 files changed +134 -152
docs/agent/knowledge.md
+2 -2
@@ -22,11 +22,11 @@ By default a session gives your agent direct tools, called through a provider pa
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.
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 (for example, `notion_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 display name is not a toolkit identifier. 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.
29 +A Custom MCP toolkit is your own remote MCP server registered into your project (slug `CUSTOM_*`); it can be shared within the project or private to one user and never grouped into an App. A Provider MCP toolkit is a catalog toolkit that connects to a product's own hosted MCP server (for example, `notion_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
+15 -19
@@ -5,21 +5,19 @@ keywords: [composio built vs provider mcp, which toolkit, notion vs notion_mcp,
5 isNew: true
6 ---
7
8 -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>);
8 +Choose the toolkit whose tools and authentication fit your task. Use its exact slug when configuring a session.
9
10 -When a product ships more than one toolkit, you pick one slug and pass it. This page is how to pick.
11 -
12 -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.
10 +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 use session discovery and execution. The catalog's Type filter carries these two labels, plus Custom for servers your own project registered. Their tool coverage and authentication can differ.
11
12 ## How they compare
13
16 -| | Composio Built | {ProviderMcpIcon} Provider MCP |
14 +| | Composio Built | Provider MCP |
15 | --- | --- | --- |
16 | Who maintains the tools | Composio | The product's team |
17 | What it connects to | The product's public API | The product's own hosted MCP server |
20 -| Slug | Anything that doesn't end in `_mcp`, like `notion` | Ends in `_mcp`, like `notion_mcp` |
18 +| Example slug | `notion` | `notion_mcp` |
19 | Tool naming | `NOTION_CREATE_PAGE` | `NOTION_MCP_NOTION_CREATE_PAGES` |
22 -| 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, most often DCR OAuth |
20 +| 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, such as DCR OAuth |
21 | [Triggers](/docs/triggers) | Available on many toolkits | None |
22 | Staying current | Composio regenerates and versions the toolkit | A sync produces a new dated version |
23
@@ -27,30 +25,28 @@ Neither is a subset of the other. Tool lists differ in both directions, and ther
25
26 ## Decide in this order
27
30 -Open the app drawer, or the comparison strip on either toolkit's detail page, and read these facts.
31 -
32 -<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." />
28 +Compare each toolkit's details in the catalog.
29
34 -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 against the product's own server, and some need no auth, so read the auth pills rather than assuming from the label.
35 -2. **Triggers.** [Triggers](/docs/triggers) exist only on Composio Built toolkits. If your agent has to react to events, that settles it.
30 +1. **Auth your users can complete.** Check this per toolkit rather than assuming it from the type. A Composio Built toolkit may offer [Composio managed](/docs/authentication/custom-app-vs-managed-app) OAuth2 or an API key. A Provider MCP toolkit may use DCR OAuth against the product's own server or another declared scheme, including no auth, so read the auth pills rather than assuming from the label.
31 +2. **Triggers.** [Triggers](/docs/triggers) exist only on Composio Built toolkits. If your agent needs an event, check that a toolkit exposes that specific trigger.
32 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.
37 -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.
33 +4. **Which account your users already have.** [Siblings never share a connection](/docs/apps-and-toolkits#sibling-toolkits-never-share-a-connection), so reuse an existing connection when that toolkit covers the task.
34
39 -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.
35 +Enable the toolkit your task needs. Enable both only when you need tools from both. [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) has the enable and disable recipes.
36
41 -<Callout type="info" title="Sometimes the labels tell you nothing">
42 -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.
37 +<Callout type="info" title="Compare the task, not just the type">
38 +Two toolkits can have the same type and serve different jobs or acting identities. Compare the tools and authentication even when both say Composio Built.
39 </Callout>
40
41 ## If neither fits
42
47 -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.
43 +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 `CUSTOM_*` toolkit. It can be shared within your project or private to one user.
44
45 ## If an agent picks at runtime
46
47 - **Use the slug you were given.** If the request or the session config names `notion` or `notion_mcp`, use exactly that toolkit.
52 -- **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.
53 -- **Don't read `_mcp` as newer, bigger, or already connected.** It only means the tools come from the product's own server.
48 +- **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. First check that the toolkit covers the task. Then prefer an existing connection or authentication the user can complete.
49 +- **Don't read `_mcp` as newer, bigger, or already connected.** Use the toolkit's catalog type to identify where its tools come from.
50 - **State which slug you chose** when the toolkit was ambiguous, so the user can redirect you.
51
52 ## Related guides
docs/content/docs/apps-and-toolkits/index.mdx
+29 -22
@@ -5,17 +5,20 @@ keywords: [app, toolkit, apps vs toolkits, toolkit slug, sibling toolkits, notio
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.
8 +A **toolkit** is the unit you name everywhere in Composio: one slug and a set of tools with its supported authentication methods. 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).
10 +An App can contain one toolkit or several. 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:
14 +Use an App to compare related toolkits. When an SDK or API parameter asks for a toolkit, pass its exact toolkit slug, not the App display name:
15
16 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
16 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
17 <Tab value="Python">
18 ```python
19 +from composio import Composio
20 +
21 +composio = Composio()
22 session = composio.sessions.create(
23 user_id="user_123",
24 toolkits=["notion"] # a toolkit slug, never an App name
@@ -32,38 +35,42 @@ const session = await composio.create("user_123", {
35 });
36 ```
37 </Tab>
38 +<Tab value="API">
39 +```bash
40 +curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
41 + -H "x-api-key: $COMPOSIO_API_KEY" \
42 + -H "Content-Type: application/json" \
43 + -d '{"user_id": "user_123", "toolkits": {"enable": ["notion"]}}'
44 +```
45 +</Tab>
46 </Tabs>
47
37 -## An App holds any number of toolkits
48 +## Grouping keeps toolkit choices separate
49
39 -They aren't always one of each kind:
50 +An App groups related toolkits for comparison. Grouping does not combine their tools or credentials, and the first toolkit in a group is not a recommendation.
51
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.
52 +Use the group shown in the catalog. A shared provider name or a suffix such as `_mcp` does not establish that two toolkits belong together. Products for different jobs or acting identities can remain separate, such as Slack and Slackbot or a core product and its advertising API.
53
54 ## Sibling toolkits never share a connection
55
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.
56 +Connecting `notion` does _not_ connect `notion_mcp`, even for the same user. Each toolkit has its own auth configs and connected accounts. Composio managed auth availability also belongs to the individual toolkit.
57
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
58 +The same separation applies to session filters. `toolkits: ["notion"]` makes `notion` available without making `notion_mcp` available.
59
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.
60 +<Callout type="info" title="Check authentication for each toolkit">
61 +If both toolkits require authentication, each needs its own connection. A toolkit that declares no authentication does not require a sign-in. Enable the toolkits your task needs. See [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) for the enable and disable examples.
62 +</Callout>
63
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." />
64 +## Find apps and toolkits in the dashboard
65
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:
66 +Open [Toolkits in the dashboard](https://dashboard.composio.dev/~/project/toolkits?utm_source=docs&utm_medium=content&utm_campaign=apps-and-toolkits). For an App with multiple toolkits, compare each toolkit's slug, type, authentication methods, tools, and triggers before connecting it.
67
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." />
68 +**Composio Built** and **Provider MCP** describe where tools come from. **Composio managed auth** describes who supplies the OAuth app. These are separate properties.
69
70 ## Related guides
71
72 <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" />
73 + <Card icon={<Plug />} title="What are Provider MCPs" href="/docs/apps-and-toolkits/provider-mcps" description="Toolkits backed by a product's hosted MCP server" />
74 + <Card icon={<RouteIcon />} title="Composio Built vs Provider MCPs" href="/docs/apps-and-toolkits/composio-built-vs-provider-mcp" description="Choose a toolkit for your task" />
75 + <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Choose which toolkits a session can use" />
76 </Cards>
docs/content/docs/apps-and-toolkits/provider-mcps.mdx
+14 -20
@@ -5,41 +5,35 @@ keywords: [provider mcp, provider mcps, notion_mcp, mcp toolkit, dcr oauth, mcp
5 isNew: true
6 ---
7
8 -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>);
9 -
10 -export const ProviderMcpIconLg = (<svg width="18" height="18" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" style={{display:'inline-block',verticalAlign:'-4px',marginRight:'8px'}} 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 -
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
14 -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")`.
15 -
16 -<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." />
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. Use the same session APIs with the exact toolkit slug, but check its supported authentication methods.
11
12 ## How to spot one
13
20 -In the catalog, the {ProviderMcpIconLg} mark on an app means it includes a Provider MCP toolkit. Hovering it reads "Provider MCP available".
14 +Look for the **Provider MCP** type in the catalog.
15
22 -In code, the slug ends in `_mcp`, like `notion_mcp`. The display name usually ends in " MCP", but match on the slug, not the name.
16 +Many Provider MCP slugs end in `_mcp`, such as `notion_mcp`. Use the catalog type to identify Provider MCP toolkits, and copy exact toolkit and tool slugs from discovery. Do not classify or group toolkits by their suffix.
17
24 -Its tools carry the toolkit prefix plus the tool name the product publishes, so they look different from a Composio-built toolkit's tools:
18 +Its tools carry the toolkit prefix plus the tool name the product publishes, as in this example:
19
26 -| | Composio Built | {ProviderMcpIcon} Provider MCP |
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
33 -- **Auth varies per toolkit.** Most use [DCR OAuth](/reference/glossary#dcr-oauth) against the product's own server, some need no auth, and a few use an API key or OAuth2. Read what the toolkit declares rather than assuming from the label.
34 -- **No [triggers](/docs/triggers).** Triggers exist only on toolkits Composio builds. If your agent has to react to events, use the Composio-built sibling.
35 -- **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.
27 +- **Auth varies per toolkit.** A toolkit may use [DCR OAuth](/reference/glossary#dcr-oauth), an API key, OAuth2, or no authentication. 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 needs an event, check the Composio Built toolkit for that specific trigger.
29 +- **Tools come from the product.** Tool names, descriptions, and schemas are limited to what the upstream server publishes, and Composio imports them during synchronization. A sync imports updated tool definitions into a dated toolkit version.
30
37 -<Callout type="info" title="You don't need to create an auth config">
38 -`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.
31 +<Callout type="info" title="DCR OAuth and managed auth are different">
32 +DCR OAuth registers a client with the server during the connection flow. It does not require a Composio-managed OAuth app. Follow the toolkit's connection instructions; other authentication schemes can require credentials or a custom auth config.
33 </Callout>
34
41 -<Callout type="warn" title="Listing the tools on v3 returns nothing">
42 -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).
35 +<Callout type="warn" title="If a v3 tool listing is empty">
36 +A v3 tool listing can select a pinned version that predates the imported MCP tools. If `GET /api/v3/tools?toolkit_slug=notion_mcp` is empty, check the version before treating it as a sync failure. Add `toolkit_versions=latest`, or use v3.1, which defaults to the latest version. Session discovery does not use that v3 listing request. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
37 </Callout>
38
39 ## Provider MCP vs MCP as a transport
@@ -52,11 +46,11 @@ MCP shows up on both sides of Composio, and the two are independent. A Provider
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
55 -The two stack without interacting, so you can enable `notion_mcp` in a session and serve it over the session MCP endpoint.
49 +You can combine them, 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
59 -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.
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 `CUSTOM_*` toolkit shared within the project or private to one user. Custom toolkits remain separate from catalog App groups. The two behave alike at runtime, since Composio is the MCP client in both.
54
55 ## Related guides
56
docs/content/docs/configuring-sessions.mdx
+19 -1
@@ -211,9 +211,12 @@ The session API rejects unknown root keys with a `400` before it creates anythin
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>
214 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
215 <Tab value="Python">
216 ```python
217 +from composio import Composio
218 +
219 +composio = Composio()
220 # Only the Provider MCP toolkit
221 session = composio.sessions.create(
222 user_id="user_123",
@@ -243,6 +246,21 @@ const session2 = await composio.create("user_123", {
246 });
247 ```
248 </Tab>
249 +<Tab value="API">
250 +```bash
251 +# Only the Provider MCP toolkit
252 +curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
253 + -H "x-api-key: $COMPOSIO_API_KEY" \
254 + -H "Content-Type: application/json" \
255 + -d '{"user_id": "user_123", "toolkits": {"enable": ["notion_mcp"]}}'
256 +
257 +# Keep other toolkits discoverable, but exclude notion_mcp
258 +curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
259 + -H "x-api-key: $COMPOSIO_API_KEY" \
260 + -H "Content-Type: application/json" \
261 + -d '{"user_id": "user_123", "toolkits": {"disable": ["notion_mcp"]}}'
262 +```
263 +</Tab>
264 </Tabs>
265
266 ## Direct tools preset
docs/content/reference/glossary.mdx
+36 -36
@@ -7,28 +7,8 @@ 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 -
10 <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).
11 +A grouping of sibling toolkits for one product in the catalog. The Notion app, for example, contains the `notion` and `notion_mcp` toolkits. Use an App to compare toolkits. SDK and API toolkit parameters take exact toolkit slugs, not App display names. See [Apps and toolkits](/docs/apps-and-toolkits).
12 </GlossaryTerm>
13
14 <GlossaryTerm name="Auth Config">
@@ -47,6 +27,10 @@ The URL a user returns to after completing an OAuth flow through a Connect Link.
27 A project-scoped secret that authenticates your SDK and API requests. Every resource you create with it is scoped to that project.
28 </GlossaryTerm>
29
30 +<GlossaryTerm name="Composio Built">
31 +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).
32 +</GlossaryTerm>
33 +
34 <GlossaryTerm name="Composio Managed Auth">
35 The default mode in which Composio supplies its own OAuth app credentials for each toolkit. It requires no setup.
36 </GlossaryTerm>
@@ -63,6 +47,18 @@ A stored set of credentials (OAuth tokens or API keys) linked to a userID, creat
47 The object returned when you initiate authentication. It contains the Connect Link URL and a `waitForConnection()` method that resolves once the user completes the flow.
48 </GlossaryTerm>
49
50 +<GlossaryTerm name="Custom MCP">
51 +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).
52 +</GlossaryTerm>
53 +
54 +<GlossaryTerm name="DCR OAuth">
55 +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.
56 +</GlossaryTerm>
57 +
58 +<GlossaryTerm name="Direct tools (provider package)">
59 +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. Previously called native tools.
60 +</GlossaryTerm>
61 +
62 <GlossaryTerm name="In-Chat Authentication">
63 A flow in which the agent handles authentication itself by calling `COMPOSIO_MANAGE_CONNECTIONS` to generate a Connect Link and send it to the user in the conversation. See [In-chat authentication](/docs/authentication#in-chat-authentication).
64 </GlossaryTerm>
@@ -71,14 +67,14 @@ A flow in which the agent handles authentication itself by calling `COMPOSIO_MAN
67 A tool you define yourself that runs in your application process alongside Composio's built-in tools. Previously called a custom tool. Add experimental local tools and local toolkits through [Local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits).
68 </GlossaryTerm>
69
74 -<GlossaryTerm name="MCP (Model Context Protocol)">
75 -An open protocol for connecting AI models to external tools. Create a session with `mcp: true` to expose `session.mcp.url` and `session.mcp.headers`, an MCP-compatible endpoint any MCP client can connect to. See [Using sessions via MCP](/docs/sessions-via-mcp).
76 -</GlossaryTerm>
77 -
70 <GlossaryTerm name="Manual Authentication">
71 Authenticating users from your own code with `session.authorize()` or `connectedAccounts.link()`, rather than letting the agent handle it through in-chat authentication. See [Manual authentication](/docs/authentication/manually-authenticating).
72 </GlossaryTerm>
73
74 +<GlossaryTerm name="MCP (Model Context Protocol)">
75 +An open protocol for connecting AI models to external tools. Create a session with `mcp: true` to expose `session.mcp.url` and `session.mcp.headers`, an MCP-compatible endpoint any MCP client can connect to. See [Using sessions via MCP](/docs/sessions-via-mcp).
76 +</GlossaryTerm>
77 +
78 <GlossaryTerm name="Meta Tools">
79 A set of tools included in every session: `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET_TOOL_SCHEMAS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront. See [Meta Tools Reference](/toolkits/meta-tools).
80 </GlossaryTerm>
@@ -99,16 +95,24 @@ A key (`x-org-api-key`) for organization-level operations such as creating and m
95 An isolated environment within an organization that scopes API keys, connected accounts, auth configs, and webhooks. Resources in one project are inaccessible from another. IDs are prefixed `proj_`. See [Projects](/reference/api-reference/projects).
96 </GlossaryTerm>
97
98 +<GlossaryTerm name="Provider">
99 +An adapter package that transforms Composio tools into the format an AI framework expects (OpenAI, Anthropic, LangChain, Vercel AI SDK, and others). See [Providers](/docs/providers).
100 +</GlossaryTerm>
101 +
102 +<GlossaryTerm name="Provider MCP">
103 +A toolkit that connects to the product's own hosted MCP server, maintained by that product. Many slugs end in `_mcp`, such as `notion_mcp`. Check the catalog type and the toolkit's authentication methods. Not to be confused with a provider, which is an AI-framework adapter. See [Apps and toolkits](/docs/apps-and-toolkits).
104 +</GlossaryTerm>
105 +
106 <GlossaryTerm name="Proxy Execute">
107 Making authenticated HTTP requests through a toolkit's connected account without a predefined tool. Use it for API endpoints Composio has no built-in tool for.
108 </GlossaryTerm>
109
106 -<GlossaryTerm name="Provider">
107 -An adapter package that transforms Composio tools into the format an AI framework expects (OpenAI, Anthropic, LangChain, Vercel AI SDK, and others). See [Providers](/docs/providers).
110 +<GlossaryTerm name="Sandbox">
111 +A persistent Python environment (previously called the workbench) exposed through the `COMPOSIO_REMOTE_WORKBENCH` meta tool. Its state persists across calls within a session, which makes it useful for bulk operations, data transformations, and processing large tool responses. Configure it with the `sandbox` session key; `workbench` still works as an alias. See [Sandbox](/docs/sandbox/remote).
112 </GlossaryTerm>
113
114 <GlossaryTerm name="Session">
111 -An ephemeral, immutable configuration object returned by `composio.create(userId)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
115 +The runtime context returned by `composio.create(userId)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
116 </GlossaryTerm>
117
118 <GlossaryTerm name="Session ID">
@@ -143,6 +147,10 @@ A source that sends structured payloads to your application when something happe
147 A specific, active trigger scoped to a user's connected account.
148 </GlossaryTerm>
149
150 +<GlossaryTerm name="userID">
151 +An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between userIDs. See [What is a session?](/docs/how-composio-works).
152 +</GlossaryTerm>
153 +
154 <GlossaryTerm name="Webhook Endpoint">
155 The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint_setup` flag is `true`, you configure it yourself once per OAuth app through the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints). See [Custom OAuth webhooks](/docs/setting-up-triggers/custom-oauth-webhooks).
156 </GlossaryTerm>
@@ -151,16 +159,8 @@ The ingress URL Composio issues per OAuth app for webhook triggers, plus the sig
159 The URL Composio delivers signed events to in your application. There is one per project, configured through the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhook-subscriptions). See [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events).
160 </GlossaryTerm>
161
154 -<GlossaryTerm name="userID">
155 -An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between userIDs. See [What is a session?](/docs/how-composio-works).
156 -</GlossaryTerm>
157 -
162 <GlossaryTerm name="White-Labeling">
163 Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding. See [White-labeling authentication](/docs/authentication/white-labeling-authentication).
164 </GlossaryTerm>
165
162 -<GlossaryTerm name="Sandbox">
163 -A persistent Python environment (previously called the workbench) exposed through the `COMPOSIO_REMOTE_WORKBENCH` meta tool. Its state persists across calls within a session, which makes it useful for bulk operations, data transformations, and processing large tool responses. Configure it with the `sandbox` session key; `workbench` still works as an alias. See [Sandbox](/docs/sandbox/remote).
164 -</GlossaryTerm>
165 -
166 </Glossary>
docs/decisions/apps-and-toolkits.md
+15 -50
@@ -1,62 +1,27 @@
1 -# Apps, Composio Built toolkits, and Provider MCP toolkits
1 +# Apps and 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.
5 +Use **Composio Built** for toolkits Composio maintains against product APIs, **Provider MCP** for catalog toolkits backed by a product's hosted MCP server, and **Custom MCP** for remote servers registered for a project or one user.
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.
7 +An **App** groups related catalog toolkits for comparison. Each toolkit retains its own slug, tools, authentication methods, auth configs, and connected accounts. App grouping does not enable sibling toolkits in a session or transfer a connection between them.
8
9 -## Context
9 +## Grouping and selection
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).
11 +- The dashboard groups by the backend-owned `app` value. Missing values and Custom MCP toolkits remain singletons.
12 +- Use `toolkit_type` to distinguish Composio Built from Provider MCP in dashboard code. Do not infer type or grouping from `_mcp`, `_graph`, or `_graphql` suffixes.
13 +- A shared provider does not establish that toolkits serve the same job. Different products, acting identities, or deployment targets can remain separate.
14 +- Do not recommend the first toolkit in a group. Honor an explicitly named slug; otherwise compare required tools, triggers, authentication, and existing connections.
15 +- Composio managed auth availability is independent of toolkit type.
16
13 -The naming choice is constrained by collisions that already live in agent-facing text:
17 +## Documentation scope
18
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.
19 +The three guides cover App grouping, Provider MCP behavior, and choosing a toolkit. Session configuration, the glossary, agent instructions, LLM guardrails, and the Composio skill use the same terminology. Session MCP transport remains separate from Provider MCP toolkits.
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).
21 +The replacement for PR #4336 carries the content onto the current `next` branch. It preserves the newer Custom MCP scope and session configuration docs and moves the agent guidance into `docs/agent/instructions/context.ts`.
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.
23 +The September staging screenshots are omitted because they contain personal workspace details, old counts, and grouping examples that no longer match the backend-owned contract. Fresh demo-workspace screenshots can be added separately.
24
25 -## Consequences
25 +## Verification boundary
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.
27 +Review against the current docs and SDK contracts and the dashboard grouping implementation. Build, link, snippet, lint, and test results belong in the PR description. A local check does not establish production rollout or provider availability, and old test results from PR #4336 do not validate this replacement.
docs/lib/home-navigation.ts
+2
@@ -128,6 +128,7 @@ export const DOCS_PRODUCTS = {
128 '/docs/production-readiness',
129 '/docs/providers',
130 '/docs/how-composio-works',
131 + '/docs/apps-and-toolkits',
132 '/docs/configuring-sessions',
133 '/docs/session-configs',
134 '/docs/governance/approvals',
@@ -176,6 +177,7 @@ export const DOCS_PRODUCTS = {
177 type: 'group',
178 label: 'Toolkits & Tools',
179 links: [
180 + { type: 'folder', path: 'apps-and-toolkits' },
181 { url: '/docs/toolkits' },
182 { url: '/docs/instant-tools' },
183 { url: '/docs/extending-sessions/local-tools-and-toolkits' },
docs/public/images/docs/toolkit-apps/app-drawer-notion.jpg
Binary files a/docs/public/images/docs/toolkit-apps/app-drawer-notion.jpg and /dev/null differ
docs/public/images/docs/toolkit-apps/catalog-list.jpg
Binary files a/docs/public/images/docs/toolkit-apps/catalog-list.jpg and /dev/null differ
docs/public/images/docs/toolkit-apps/preview-notion-mcp.jpg
Binary files a/docs/public/images/docs/toolkit-apps/preview-notion-mcp.jpg and /dev/null differ
docs/public/images/docs/toolkit-apps/toolkit-detail-notion-mcp.jpg
Binary files a/docs/public/images/docs/toolkit-apps/toolkit-detail-notion-mcp.jpg and /dev/null differ
skills/composio/references/errors.md
+1 -1
@@ -49,7 +49,7 @@ Keep the same project key and application user ID. Generate a fresh Connect Link
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.
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 toolkit the tool belongs to. If you choose an already-connected sibling instead, rediscover its tools and inspect their schemas before calling them; sibling tool slugs and inputs are not interchangeable.
53
54 ### For You client authentication
55
skills/composio/references/platform.md
+1 -1
@@ -138,7 +138,7 @@ If the application has its own connect UI, use session authorization and connect
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.
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`). Use the catalog grouping; do not derive membership from names or suffixes. Different jobs or acting identities can remain separate. 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