Missing Composio Toolkit — Runbook

Missing Composio Toolkit — Runbook

Updated 2026-05-20 to lead with Path D (Pipedream Connect) per ADR-061. The CF Worker path (formerly the default) is demoted to a last resort.

What is a “missing toolkit”?

A “missing toolkit” means a SaaS provider we need to call is not in Composio’s catalog — there’s no toolkit slug, no tools to discover, no OAuth flow to initiate through Composio.

Symptoms:

• GET backend.composio.dev/api/v3/tools?search={provider} returns empty results
• No toolkit slug appears at composio.dev/toolkits
• Tool call errors with 404 on toolkit name, not 403 on scope

What it is NOT:

• A scope gap (toolkit exists but OAuth grant is missing scopes) — see scope-gap.md
• A connection that needs to be initiated (toolkit exists but this user_id hasn’t connected yet) — use onboard-client skill

Resolution paths (canonical ordering, post ADR-061)

Priority	Path	When
1	Composio (native)	Toolkit is in Composio catalog. Always first choice.
2	Path D — Pipedream Connect	Toolkit not in Composio but in Pipedream’s 2,700+ catalog. Default for all SaaS gaps.
3	Path A — PENDING-NATIVE	Toolkit absent from both. Low criticality. File Composio GH feature request and wait ≤14 days.
4	Path C — Dedicated CF Worker	Toolkit absent from both AND criticality forces immediate access AND Path D ruled out.
5	Path B — Session-only SDK	Debugging only. Never production.

Path D — Pipedream Connect (DEFAULT for any SaaS gap)

Pipedream Connect is the sanctioned secondary OAuth vendor per ADR-061. Covers Google Tag Manager (live for Ascend) plus 2,700+ long-tail SaaS providers Composio does not.

Wire-up steps (already done for GTM; template for future toolkits):

1. Confirm Pipedream covers the upstream API — check pipedream.com/apps/{slug}.
2. BYO OAuth client in Pipedream when the API requires sensitive scopes or a distinct consent screen (Google, Microsoft, Meta). Otherwise use Pipedream-managed client.
3. Pipedream credentials live in Infisical (pipedream/client_id, pipedream/client_secret, pipedream/project_id). Workspace OAuth Bearer is minted per-invocation (1h TTL).
4. Run the Connect flow with external_user_id={client_slug} — once per tenant.
5. Add Pipedream MCP server entry to .mcp.json + all four IDE configs:

   "pipedream-{toolkit}-{tenant}": {
     "url": "https://remote.mcp.pipedream.net/v3",
     "headers": {
       "Authorization": "Bearer ${PIPEDREAM_OAUTH_BEARER}",
       "x-pd-project-id": "${PIPEDREAM_PROJECT_ID}",
       "x-pd-environment": "production",
       "x-pd-external-user-id": "{tenant}",
       "x-pd-app-slug": "{toolkit_slug}"
     }
   }

6. Add row to toolkit-registry.md with vendor: PIPEDREAM + the MCP tool prefix.
7. Embed capability entries into Vectorize capability_index (standard embed script).

Per-tenant rollout: repeat step 4 for each tenant slug. Connection IDs and external_user_id are isolated per tenant just like Composio’s user_id pattern.

Cost reality check: Pipedream Connect is $99/mo flat for 10K credits (1 credit = 30s @ 256MB). Most GTM calls complete in <2s so realistic burn is 3–8K credits/mo. First overage threshold at ~10K credits; re-evaluate vendor selection if monthly spend exceeds $500.

When to use: Default for ALL toolkits Composio does not cover. No 14-day wait. No CF Worker engineering tax.

Path A — Wait for native Composio support

Only choose when the toolkit is on neither Composio nor Pipedream AND criticality allows a 14-day wait.

1. Search Composio’s GitHub issues for an existing request.
2. If none, open one at https://github.com/ComposioHQ/composio/issues.
3. Record in toolkit-registry.md with status: PENDING-NATIVE + GitHub issue link.
4. Set a 14-day calendar reminder.

Path B — Session-only SDK custom toolkit (dev/debug only)

composio.experimental.Toolkit() creates a toolkit for the current SDK session. Evaporates when the session ends. NEVER ship production code depending on a session-only toolkit. Document any session-scope use in LEDGER.

Path C — Dedicated CF Worker (LAST RESORT)

Reserved for cases where Pipedream cannot satisfy the requirement:

• Latency-sensitive hot path Pipedream’s MCP egress can’t meet.
• Custom request signing Pipedream doesn’t expose.
• Regulatory data-residency Pipedream can’t guarantee.

Building a Worker means: new ADR + Worker scaffold + OAuth flow + secret rotation + MCP framing + capability_registry entries + 5 IDE configs + ongoing maintenance. Engineering cost is linear per toolkit. This was the default before 2026-05-19 and is now the exception. See ADR-060 (superseded) for the GTM Worker plan that was cancelled in favor of Path D.

Decision tree

Provider needed?
  ↓
Search Composio catalog (multi-keyword)
  → Found: use Composio. Record in toolkit-registry.md (vendor: COMPOSIO).
  → Not found:
      ↓
    Check Pipedream catalog (pipedream.com/apps/{slug})
      → Found: PATH D — Pipedream Connect. Record (vendor: PIPEDREAM).
      → Not found:
          ↓
        Can wait ≤14 days AND non-critical?
          → Yes: Path A (PENDING-NATIVE) + Path B for prototyping
          → No: Path C (dedicated CF Worker) — needs ADR

Runbook reference

Step-by-step in .claude/skills/composio/missing-toolkit-resolver/SKILL.md. That skill is being updated to lead with Path D as part of the doc-consolidation plan (ADR-063).

Registry

All missing-toolkit cases live in toolkit-registry.md. Grep there before starting — a previous session may already have resolved the same provider.