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, 03:37 UTC
docs: make auth for existing tools discoverable (DEVREL-329) (#5455)
## Summary Agents keep treating Composio's catalog as redundant when developers already own their tools. The November 17 Gauge recheck stayed at 0/4 Composio picks for the plain own-MCP-tool auth prompt, and none of those sessions fetched the existing managed-auth guide. This makes that existing path visible at the docs entry points and in the published agent skill. Addresses [DEVREL-329](https://linear.app/composio/issue/DEVREL-329/agents-dont-see-composio-as-an-auth-layer-for-tools-developers-already) and the docs discovery portion of PRO-3749. Designated reviewer: @jkomyno. ## Changes | Entry point | Before | After | | --- | --- | --- | | Docs landing, quickstart, session overview | No direct route to auth for existing tools | Link to the existing Python, TypeScript, and REST guide | | `llms.txt` | Auth guide nested under application building; summary focused on agents | Auth-only capability in the summary; Connect Link + Proxy Execute before the SDK quickstart | | Published Composio skill | General integration flow fetched session tools and required a tool log ID | Own-tool path verifies a successful proxy response without catalog discovery or a tool log ID | | Quickstart notes | Auth callout at the top; identity callout and session note midway through | Three consistent Markdown bullets under Plan your application → Considerations | | Managed-auth guide | Ambiguous refresh language and unexplained permission label | Provider-dependent refresh, outbound-auth boundary, and explanation of the exact `Proxy execute (Legacy)` permission label | No runtime changes or token-export capability. Existing custody, owner checks, account pinning, and three-language examples are preserved. ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? On follow-up commit `5bbe07010`: - Quickstart MDX compilation passes. Its actual `mdxToCleanMarkdown()` output contains each of the three notes exactly once under `Plan your application` → `Considerations`. - `bun test --timeout 30000 tests/static/home-navigation.test.ts tests/static/llms-routing.test.ts tests/static/dashboard-links.test.ts tests/static/source.test.ts`: **13 passed, 0 failed**. - `bun run lint:links`, `bun run validate:agent-skills`, `bun run validate:skill-routing`, and `git diff --check` pass. - The direct proxy's committed v3.1 response schema returns provider status, body, and headers without a tool log ID. Verification now branches by integration type and retains the real, safe provider-request requirement. - `gh pr checks 5455` passed on `5bbe0701039ad78e948fdf62eaf975923a6ac28a`, including docs build/integration, TypeScript, Python snippets, links, and agent guidance. The optional agent eval was skipped. The PR is ready for review. No local full build was repeated for the prose relocation and skill wording. The initial commit `a2dc6d7e0` passed GitHub CI, including docs build/integration, TypeScript, Python snippets, links, and agent guidance. Local lint, type checking, example checks, production build, and agent Markdown checks also passed. The optional agent eval was skipped. Build output was removed afterward. No new tests were added for prose and links; existing checks cover the changed content. The connection flow is implemented by [TypeScript `authorize()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/ToolRouterSession.ts#L475) and [Python `authorize()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/python/composio/core/models/tool_router_session.py#L862). The outbound call is implemented by [TypeScript `tools.proxyExecute()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/Tools.ts#L1599) and [Python `tools.proxy()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/python/composio/core/models/tools.py#L998). The committed v3.1 schema does not mark the proxy operation deprecated. Refresh and credential-redaction boundaries were checked against the existing authentication and token-custody docs; SDK models alone do not establish server-side custody or refresh guarantees. ## Screenshots (if applicable) The quickstart moves existing notes into ordinary Markdown bullets at the bottom. No component or style code changed. The before/after table records the content and placement changes; MDX compilation and agent Markdown output were checked directly. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages <!-- sdk-release-note-exempt: Documentation discovery, quickstart note placement, and agent guidance only; no TypeScript or Python SDK runtime behavior changes. --> Docs and skill prose only; no changeset needed. Please review the full diff before merging. ## Additional context NEEDS BRENDAN: - Product and SDK owners: confirm official auth-only positioning and support commitments. Should the dashboard's `Proxy execute (Legacy)` permission be renamed? This PR preserves the real label and explains its current routes. - Auth/backend and security owners: confirm which provider/auth-scheme combinations and refresh behavior are guaranteed for this path, including revoked or expired credentials. This PR makes no universal scheme or refresh promise. - Product/billing: confirm pricing and metering for connections and Proxy Execute without catalog tools. No auth-only price is inferred here. - Landing/content owner: the Nango comparison and marketing homepage are outside this repo. Continue comparison work through [PRO-3751](https://linear.app/composio/issue/PRO-3751); no other repo was changed. Gauge preference improvement is unmeasured. The issue's matched retest belongs after publication, with evidence that the changed pages reached the sessions. No live provider or customer-account requests were made. In plain language: keep the tools you wrote. Composio can connect each user's account and authenticate the API requests those tools make, returning the response rather than an OAuth token.