Connected Services

Connect your own accounts — Gmail, GitHub, HubSpot, Notion, and 200+ more — via OAuth. Each connected service appears as its own endpoint with its full, unabstracted action catalogue. No wrappers, no abstractions: the exact Composio actions pass straight through.

How It Works

Connect a service via OAuth

Your agent calls handler_connect, or use the dashboard or CLI. The owner completes the OAuth flow once and the service is available to the agent immediately.

// MCP
handler_connect({ "service": "github" })

// REST API
POST /v2/connections/initiate
{ "toolkit": "github" }

Call the service directly

Each connected service appears as its own endpoint (REST) or tool (MCP). Pass the Composio action name directly — all params are forwarded as-is.

// REST API
POST /v2/superpowers/gmail
{ "action": "GMAIL_SEND_EMAIL", "to": "...", "subject": "...", "body": "..." }

POST /v2/superpowers/github
{ "action": "GITHUB_LIST_REPOSITORY_ISSUES", "owner": "myorg", "repo": "myapp" }

// MCP — each connected service is its own tool
gmail({ "action": "GMAIL_SEND_EMAIL", "to": "...", ... })
github({ "action": "GITHUB_LIST_REPOSITORY_ISSUES", ... })

Discover available actions

The full action catalogue for each connected service is available in GET /v2/agent/status under connected_services. Each entry lists every available action with its description and permission level.

GET /v2/agent/status

// Response (excerpt)
{
  "connected_services": [
    {
      "service": "gmail",
      "display_name": "Gmail",
      "cost": "$0.0005/call",
      "actions": [
        { "action": "GMAIL_SEND_EMAIL", "description": "Send an email", "permission": "write" },
        { "action": "GMAIL_LIST_EMAILS", "description": "List emails in inbox", "permission": "read" }
      ]
    }
  ]
}

Superpowers vs Connected Services. These are two distinct things. Superpowers (handler_research, handler_intel, etc.) are shipped with Handler and always available. Connected services are accounts you own, connected via OAuth — each gets its own endpoint with its full, unabstracted action catalogue piped from Composio.

Per-Agent Isolation

Connections are never shared between agent profiles. Each profile must have its own OAuth connection for each service it uses. This gives you precise control over what each agent can access.

Connect services via the dashboard (Agent Profiles → [profile] → Connected Services), the CLI, or the API.

Inline Auth

No separate connect step needed. When an agent calls a service that isn't connected yet, Handler returns an auth_required response with an OAuth URL. After authorization, retry the call and it goes through.

Available Services

200+ services available via the Composio catalog. Common examples:

Service slug	Example actions
`gmail`	`GMAIL_SEND_EMAIL`, `GMAIL_LIST_EMAILS`, `GMAIL_GET_EMAIL`
`github`	`GITHUB_LIST_REPOSITORY_ISSUES`, `GITHUB_CREATE_AN_ISSUE`, `GITHUB_LIST_PULL_REQUESTS`
`hubspot`	`HUBSPOT_GET_CONTACT_BY_ID`, `HUBSPOT_UPDATE_CONTACT`, `HUBSPOT_GET_COMPANY`
`notion`	`NOTION_CREATE_PAGE`, `NOTION_SEARCH_NOTION_PAGE`
`googlecalendar`	`GOOGLECALENDAR_LIST_EVENTS`, `GOOGLECALENDAR_CREATE_EVENT`
`zendesk`	`ZENDESK_LIST_TICKETS`, `ZENDESK_SHOW_TICKET`
`slack`	`SLACK_SENDS_A_MESSAGE`, `SLACK_LIST_CHANNELS`

See all available services: GET /v2/connections/catalog

Disconnecting

To revoke a connected service:

handler_disconnect({ "service": "github" })

POST /v2/connections/disconnect  { "service": "github" }

Governance for Connected Services

Connected service actions go through the same governance rules as built-in superpowers. Reads typically auto-approve; writes may require approval depending on your agent's rules.

Same rules, same controls. Connected service calls count toward your agent's budget and follow your auto-approve/notify/hard-cap settings.

See the Governance docs for full details.