Composio Multi-Client Routing — Canonical Reference

Composio Multi-Client Routing — Canonical Reference

Last verified: 2026-05-19
Source of truth for: Composio project membership, MCP server IDs, API key env vars, and the decision rule for project-vs-user_id routing.

---

The three Composio projects

Project name	Project ID	API key env var	Infisical path	MCP server key	Used for
ascend	pr_8AjnN9gdcrYt	COMPOSIO_API_KEY_PROD	composio/projects/ascend/api-key	composio-ascend	All Ascend agency clients (default project). Multi-tenant via user_id={slug}.
kahuna_prod	pr_ZMOhNqFRKhVj	COMPOSIO_API_KEY_KAHUNA	composio/projects/kahuna/api-key	composio-kahuna	Kahuna client. Separate project for billing isolation.
FleetView	pr_8AjnN9gdcrYt	(FleetView-managed)	—	composio (FleetView plugin)	FleetView platform default Composio plugin. Accessed via mcp__composio__* tool prefix. Same project as ascend; FleetView manages its own auth token.

Never infer “no connections” from 0 results. “0 connections found” is only valid if you used the correct API key for the target project. Wrong key always returns 0. Verify the env var before concluding absence.

---

Decision rule: project vs user_id

Use user_id within the ascend project (default)

Route the new client as user_id={slug} within the shared ascend project (pr_8AjnN9gdcrYt, key $COMPOSIO_API_KEY_PROD). All connected accounts attach to the entity {slug}. The MCP server is already in all five IDE configs — no config changes required.

When to use:

• New agency clients with a standard toolset (HubSpot, Google Workspace/Ads, Slack, Gong, Apollo, SEMrush, LinkedIn, Gamma, QuickBooks).
• No custom auth_config conflicts with the shared project.
• No hard compliance/billing isolation requirement.

Result: user_id={slug} on every tool call; routing record at ~/.claude/clients/{slug}.json.

Create a new Composio project

Create a separate project only when one or more of these conditions is true:

Condition	Reason
Client requires separate billing	Composio charges per project; separate project = separate invoice.
Custom OAuth app conflicts	Client needs a different OAuth client_id/secret for a provider already configured in the shared project with a different config.
Compliance isolation	Security/regulatory requirement mandates separate admin credentials and audit trail.
Client is a Composio reseller	They manage their own Composio subscription.

Result: New pr_XXXX project; new API key stored in Infisical; new MCP server entry in all five IDE configs (one atomic commit).

---

Credential lookup order (Credential-First Mandate)

For any Composio operation, resolve credentials in this order:

1. Infisical MCP (mcp__infisical__get-secret, project 1c1907fa-ee74-4d52-ba1a-839fc71e855d, env prod, path composio/projects/{slug}/api-key)
2. ~/.zprofile env var (COMPOSIO_API_KEY_PROD, COMPOSIO_API_KEY_KAHUNA)
3. Never ask the user to paste a key that’s already in one of the above.

---

MCP server URL format

All five IDE configs use connect.composio.dev/mcp/{project_id} with Streamable HTTP transport and x-consumer-api-key header. This is the canonical URL for this project.

Note: backend.composio.dev/v3/mcp/{server_id}/sse?user_id={slug} is the per-user_id SSE endpoint that Composio returns for some per-client routing scenarios. Before using this URL format, fetch current Composio docs to confirm it is still valid (the Composio platform ships changes without notice). # cutover-2026-05-19

The current canonical MCP URL pattern in all five IDE configs:

https://connect.composio.dev/mcp/{project_id}

Auth header: x-consumer-api-key: <project-api-key>

---

Allowed tools per project

Both projects expose the full Composio catalog. The actual available tools depend on which toolkits are installed in the project and which accounts are connected for a given user_id.

ascend project active connections (as of 2026-05-19): googlesuper, googleads, linkedin, slack, apollo, gamma, perplexityai, quickbooks, vercel (user_id=ascend). Additional client slugs listed in ~/.claude/clients/ROUTING.md.

kahuna_prod active connections (as of 2026-05-19): googlesuper, googleads, linkedin, linkedin_ads, hubspot, salesforce, gong, semrush, gamma (user_id=kahuna).

---

Adding a new client

See .claude/skills/composio/onboard-client/SKILL.md for the full runbook. Short path for standard new clients:

source ~/.zprofile
npm run onboard:client -- --slug <slug> --name "<Name>" --level developer \
  --tools hubspot,salesforce,gong,slack,googlesuper,googleads,apollo \
  --client-email <client@email.com>

---

Drift check

Check #22 (scripts/checks/22-no-retired-names.ts) verifies that composio-ascend and composio-kahuna server entries are present in all five IDE config files on every pre-commit. Missing either entry = hard fail.

Run manually: npm run check:pre-commit