Integrations

The managed Composio UI is now the default. The /integrations page is the full managed integration platform (Composio) — a KPI header plus tabs for Catalog, Connected accounts, Agent access, Tools, Triggers, and MCP endpoints — so you can connect apps via OAuth without standing up and maintaining your own MCP servers.The legacy self-hosted MCP connector management UI is restorable by building the dashboard with NEXT_PUBLIC_LEGACY_MCP_INTEGRATIONS=true. No legacy code or API has been removed — the MCP endpoints documented below still work, and credentials are unaffected. The sections below describe the legacy mechanism.

Crewship supports two integration mechanisms: OAuth 2.0 connections for service authentication and MCP (Model Context Protocol) servers for extending agent tool capabilities.

Managed Integrations (Composio)

Crewship’s managed integration path uses Composio so you connect apps once instead of hosting MCP servers yourself. Object model

Concept	What it is
Auth config	Per-app OAuth blueprint (GitHub, Slack, Gmail, …). One per app, shared by all users. The “connector catalog”.
User (`user_id`)	An end-user identity — the isolation boundary. A user owns a set of connected accounts.
Connected account	One user’s authorised connection to an app (OAuth tokens).

How isolation works. An agent is bound to exactly one user_id and therefore sees only that user’s connected accounts — never anyone else’s. To give 30 mailboxes to 30 agents, create 30 users (one per mailbox) and bind each agent to its user; the per-agent MCP URL is scoped server-side, so an agent cannot reach another user’s accounts even in principle. Use Composio projects only for coarse isolation (per environment, or per customer/workspace) — not per agent. Enabling. Add a Composio project API key either per-workspace from the app (Integrations → API key, or crewship integration composio key set) — validated and stored encrypted — or server-wide via the COMPOSIO_API_KEY env. The effective key resolves workspace-first, then env. Billing is by tool calls (Composio free tier = 20K/mo), not by number of users or connected accounts.

Multi-tenant isolation. A Composio API key maps to a single Composio project, which is the isolation boundary — every connected account, user, and trigger under that key is visible to anyone with access to a workspace using it. The server-wide COMPOSIO_API_KEY env therefore puts all workspaces in one shared project: do not back multiple independent tenant workspaces with it. For true per-tenant isolation, give each workspace its own key (Integrations → API key) so it maps to a separate Composio project.

Inspecting the inventory. The operator view of the catalog and connected accounts (grouped by user):

crewship integration composio inventory

returns the same data as GET /api/v1/integrations/composio/inventory. This is an operator/admin view — agents are never handed the full list.

Connecting an account & binding an agent

The end-to-end flow from a fresh project key to an agent that can drive an app:

# 1. Set the project API key (per-workspace, validated + stored encrypted):
crewship integration composio key set --key ak_… [--label "My project"]

# 2. Browse the app catalog:
crewship integration composio toolkits --search gmail

# 3. Connect an account — open the printed redirect_url to authorize:
crewship integration composio connect gmail --user user-42

# 4. Verify the connected account (and its user_id) landed:
crewship integration composio inventory

# 5. Bind the connected user to an agent with per-app tool scope:
crewship integration composio bind <agent> --user user-42 \
  --app gmail:read --app github:full

# 6. Inspect / remove the agent's bindings:
crewship integration composio bindings <agent>
crewship integration composio unbind <agent> [--app gmail]

Account lifecycle. Refresh, revoke, or permanently remove a connected account at the provider:

crewship integration composio account {refresh,revoke,remove} <account-id>

Default connector (`COMPOSIO_DEFAULT_CONNECTOR`)

By default an agent only reaches Composio tools an operator explicitly bound to it (crewship integration composio bind). The server flag COMPOSIO_DEFAULT_CONNECTOR flips this to a default-on model so agents never lack a tool they should obviously have (e.g. calendar):

ON — every agent without an explicit per-agent Composio binding automatically gets a workspace-wide default connector: a Composio MCP server with full access to all the workspace’s connected apps, scoped to the workspace’s default Composio user. No manual bind needed.
A per-agent binding always overrides the default for that agent — the bound (tool-scoped) server resolves and the default is not added, so you can still restrict specific agents.
Legacy (non-Composio) MCP servers are turned OFF at resolve time while the flag is on (they are not deleted — flip the flag back off to restore them). This makes Composio the single managed connector surface.
OFF (default) — today’s behaviour, unchanged: agents get only what’s explicitly bound.

The flag is a behaviour switch layered on an already-configured Composio — it never auto-enables the provider (you still need a project API key). It is false unless COMPOSIO_DEFAULT_CONNECTOR=true (or 1) is set on the server. Provisioning the default. The default connector needs a Composio user_id (whose connected accounts back it) and a provisioned MCP server. Both are set with one operator call:

# Auto-derive the user when exactly one Composio user has connected accounts:
crewship integration composio default enable

# Or pin a specific user explicitly:
crewship integration composio default set <user_id>

# Inspect the current state (flag, default user/server, connected-user count):
crewship integration composio default show

enable errors if zero users have connected accounts (“connect an account first”) or if multiple users exist (pin one with default set). Re-running is idempotent and refreshes the connector’s app set, so apps you connect later show up in the default automatically. These map to GET/PUT /api/v1/integrations/composio/default.

Agent awareness of connected integrations

An agent is told up front, in its system prompt, which integrations it can already drive. Every MCP server that resolves for the agent — Composio apps as well as plain MCP servers — is listed in a [CONNECTED INTEGRATIONS] block, including the access mode encoded in the display name (e.g. Composio: youtube · Full). This exists so an agent never reflexively answers “I don’t have access to your YouTube account” when the YouTube tools are in fact wired in. The block instructs the agent to use the matching tools directly and to only report that something isn’t possible after checking the tools available for that app — so the user never has to tell it to “go look at the MCP server” first. Nothing to configure: the block appears automatically whenever the agent resolves at least one integration, and is omitted entirely when it has none.

Troubleshooting Composio errors

Commands that reach Composio’s live API (toolkits, inventory, connect, bind, trigger and account operations) surface any upstream failure as an API error (502) whose message classifies what went wrong:

Message starts with	Meaning	Fix
`Composio rejected the configured API key (… HTTP 401/403 …)`	The effective key (workspace or `COMPOSIO_API_KEY` env) is a placeholder, revoked, or from the wrong project	`crewship integration composio key set --key ak_…`, or fix the server env
`Composio rate-limited the request (… HTTP 429 …)`	Project hit Composio’s rate limit	Retry shortly
`Composio upstream error (… HTTP 5xx …)`	Composio itself is degraded	Retry shortly; check Composio status
`Composio rejected the request (… HTTP 4xx …)`	Bad request parameters (e.g. an invalid toolkit slug)	The included upstream message says what to change
`Composio API unreachable (…)`	Network failure between the Crewship server and Composio (DNS, dial, TLS, timeout)	Check the server’s outbound connectivity and `COMPOSIO_BASE_URL`

Each message includes Composio’s own error text (sanitized and truncated); the full upstream response is written to the server log. Note that crewship integration composio key show only reports whether a key is configured, not whether Composio accepts it — a placeholder key shows as configured but fails live calls with the rejected the configured API key message above. Setting a key with key set validates it against Composio first: a key Composio rejects is refused with a 400, while a network failure during validation is reported as a 502 (unreachable) instead of blaming the key.

OAuth 2.0 Integrations

Crewship includes pre-configured OAuth providers for popular services. The implementation uses PKCE (Proof Key for Code Exchange) per RFC 7636 for secure authorization.

Supported OAuth Providers

Provider	Auth URL	Default Scopes
Google	`accounts.google.com/o/oauth2/v2/auth`	Gmail, Calendar, Drive
Slack	`slack.com/oauth/v2/authorize`	channels:read, chat:write
GitHub	`github.com/login/oauth/authorize`	repo, user
Microsoft	`login.microsoftonline.com/.../authorize`	Mail, Calendars
Linear	`linear.app/oauth/authorize`	read, write
GitLab	`gitlab.com/oauth/authorize`	api, read_user
Cloudflare	`dash.cloudflare.com/oauth2/authorize`	(custom)
Stripe	`connect.stripe.com/oauth/authorize`	read_write
Notion	`api.notion.com/v1/oauth/authorize`	(custom)

OAuth Flow

Create OAuth credential

In Settings -> Credentials, create an OAuth2 credential with the client ID, client secret, and selected provider.

Authorize the connection

Click “Connect” to start the PKCE authorization flow:

Crewship generates a code_verifier (32 random bytes, base64url-encoded)
Computes code_challenge = SHA256(code_verifier), base64url-encoded
Redirects user to provider’s authorization URL

Token exchange

After the user authorizes, the provider redirects back with an authorization code. Crewship exchanges it for access and refresh tokens using the code_verifier.

Token storage

Tokens are encrypted with AES-256-GCM and stored in the credentials table. Refresh tokens are used automatically to maintain access.

Auto-Bind

When OAuth credentials are created, the oauth_autobind system can automatically configure MCP servers or other integrations that use the credential. This eliminates manual setup for common provider-integration pairs.

MCP Server Integration

Crewship integrates with the Model Context Protocol ecosystem, allowing agents to use tools from external MCP servers.

MCP Architecture

Agent (Claude Code)
    |
    | Reads .mcp.json config
    v
Sidecar MCP Gateway (internal/sidecar/mcp_gateway.go)
    |
    | Connects to MCP servers
    v
MCP Server (stdio or HTTP transport)
    |
    v
External Service (GitHub, Slack, etc.)

Transport Types

Transport	Description	Use Case
`stdio`	Server runs as a subprocess	Local tools, custom scripts
`streamable-http`	HTTP-based communication	Remote/cloud MCP servers
`sse`	Server-Sent Events	Legacy MCP servers

MCP Server Configuration

MCP servers are configured per-crew or per-agent via the .mcp.json file:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GH_TOKEN}"
      }
    }
  }
}

The sidecar merges crew-level and agent-level MCP configurations at runtime. The merged config is written to /crew/agents/{slug}/.mcp.json inside the container. When entering a stdio server through the web UI (integration form or config editor), the args string is tokenized quote-aware: --flag "hello world" becomes ["--flag", "hello world"], and an executable path with spaces stays one token when quoted. The exact rules are in the MCP guide.

MCP Gateway

The MCPGateway (internal/sidecar/mcp_gateway.go) manages MCP server connections:

Connect: Establishes connections to all configured MCP servers at sidecar startup (15-second timeout)
Discover tools: Queries each server for available tools
Route calls: Proxies tool calls from agents to the correct MCP server

Sidecar MCP Endpoints

Endpoint	Method	Description
`/mcp/tools`	GET	List all available tools from connected MCP servers
`/mcp/call`	POST	Call a specific tool on an MCP server
`/mcp/status`	GET	Check connection status of all MCP servers

MCP Credential Injection

MCP servers can have credentials associated with them:

type MCPCredInput struct {
    Token  string `json:"token"`   // Decrypted credential value
    Type   string `json:"type"`    // "bearer", "api_key", "basic"
    Header string `json:"header"`  // Custom header name (for api_key type)
}

The sidecar handles credential injection for MCP server authentication, keeping raw tokens out of the agent’s environment.

MCP Registry

Crewship syncs with the official MCP registry at registry.modelcontextprotocol.io/v0/servers. The SyncMCPRegistry function (internal/api/mcp_registry.go) fetches and caches all registered servers locally. This allows users to browse and install MCP servers from the registry without manual configuration.

What registry entries include

Server name and display name
Description and category
Package information (runtime, environment variables)
Remote transport configuration
Verification status

Crew Connections

Crews can be connected to share context and enable cross-crew operations:

Connection Endpoints (via Sidecar)

Endpoint	Method	Description
`/crew-connections`	GET	List crew connections
`/crew-connections`	POST	Create a crew connection
`/connections`	GET	List active connections
`/connections/{id}/message`	POST	Send a message to connected crew
`/connections/{id}/messages`	GET	Read messages from connection
`/connections/{id}/files`	GET	Read shared files
`/connections/{id}/files`	POST	Write shared files

Integration Testing

The integration_test_connection.go handler provides a test endpoint for verifying that integrations are properly configured and credentials are working before deploying to production.

When configuring OAuth integrations, always test the connection after setup. OAuth tokens can expire, scopes can be insufficient, and client secrets can be rotated.

Get Started

Guides

Security

Configuration

Manifest Reference

Integrations

Integrations

Managed Integrations (Composio)

Connecting an account & binding an agent

Default connector (`COMPOSIO_DEFAULT_CONNECTOR`)

Agent awareness of connected integrations

Troubleshooting Composio errors

OAuth 2.0 Integrations

Supported OAuth Providers

OAuth Flow

Auto-Bind

MCP Server Integration

MCP Architecture

Transport Types

MCP Server Configuration

MCP Gateway

Sidecar MCP Endpoints

MCP Credential Injection

MCP Registry

Crew Connections

Connection Endpoints (via Sidecar)

Integration Testing

​Integrations

​Managed Integrations (Composio)

​Connecting an account & binding an agent

​Default connector (COMPOSIO_DEFAULT_CONNECTOR)

​Agent awareness of connected integrations

​Troubleshooting Composio errors

​OAuth 2.0 Integrations

​Supported OAuth Providers

​OAuth Flow

​Auto-Bind

​MCP Server Integration

​MCP Architecture

​Transport Types

​MCP Server Configuration

​MCP Gateway

​Sidecar MCP Endpoints

​MCP Credential Injection

​MCP Registry

​Crew Connections

​Connection Endpoints (via Sidecar)

​Integration Testing

Integrations

Managed Integrations (Composio)

Connecting an account & binding an agent

Default connector (`COMPOSIO_DEFAULT_CONNECTOR`)

Agent awareness of connected integrations

Troubleshooting Composio errors

OAuth 2.0 Integrations

Supported OAuth Providers

OAuth Flow

Auto-Bind

MCP Server Integration

MCP Architecture

Transport Types

MCP Server Configuration

MCP Gateway

Sidecar MCP Endpoints

MCP Credential Injection

MCP Registry

Crew Connections

Connection Endpoints (via Sidecar)

Integration Testing