crewship integration

Manage MCP server integrations at workspace scope, crew scope, and through agent bindings. The alias is intg.

crewship integration <subcommand> [flags]
crewship intg <subcommand> [flags]

Every integration command requires crewship login and an active workspace. Arguments named id-or-name accept either the integration ID or its name; crew and agent arguments accept slugs (and the Composio agent commands also accept agent IDs). All commands also inherit the global --server/-s, --workspace/-w, --profile, --format/-f, --verbose/-v, --no-color, and --server-allow-mismatch flags. --format defaults to table; it is honored by commands that use the formatter, while commands whose output is explicitly described as text or JSON below keep that output shape.

Command reference

Workspace scope

Command	Human output	Structured output
`integration list`	Table: `NAME`, `DISPLAY`, `TRANSPORT`, `ENDPOINT`, `ENABLED`, `ACCESS`, `AGENTS`, `CREWS`. Long endpoints are shortened.	The API list.
`integration add`	`Integration created: <name> (<id>)`	No structured output; the success line is always printed.
`integration get <id-or-name>`	Detail fields: ID, name, display, transport, endpoint, command, enabled, access, icon, created, updated. Empty optional fields show `-`.	The integration object.
`integration remove <id-or-name>`	Confirmation prompt, then `Integration <arg> deleted.`	No structured output.
`integration enable <id-or-name>`	`Integration <arg> enabled.`	No structured output.
`integration disable <id-or-name>`	`Integration <arg> disabled.`	No structured output.
`integration access <id-or-name> <all\|bound-only>`	`Integration <arg> is now available to all agents in the workspace.` or `Integration <arg> is now bound-only: only agents with an explicit binding can use it.`	No structured output.
`integration test <id-or-name>`	The server result is printed as JSON.	The server result object.
`integration crews-overview`	The server result is printed as JSON.	The server result array.

remove accepts -y/--yes to skip its confirmation prompt. add requires --name; --display defaults to the name, and --transport defaults to streamable-http. For stdio, --command is split into an executable and arguments before it is sent to the server; no shell is run. add --access takes all (the default) or bound-only; anything else is rejected before the request is sent.

Who can use an integration

ACCESS is the integration’s stored audience, and it is the only thing that decides who resolves it:

Value	Who resolves the integration
`all` (default for new integrations)	every agent in the workspace
`bound-only`	only agents with an explicit binding

crewship integration access github bound-only   # narrow it
crewship integration bind --agent pepa --server github
crewship integration access github all          # open it back up

integration bind grants one agent a credential and a config override on a server. It does not change the audience and does not affect any other agent — before Crewship 2026.08 it did both, because “available to everyone” was inferred from the binding count being zero and evaporated the moment it wasn’t. Use integration resolve <agent-slug> to see what a given agent actually gets.

Agent bindings

Command	Human output	Structured output
`integration bind`	`Agent <agent> bound to integration <server>.`	No structured output.
`integration unbind`	`Binding <binding-id> removed from agent <agent>.`	No structured output.
`integration agent-bindings <agent-slug>`	Table: `BINDING ID`, `SERVER`, `SCOPE`, `CREDENTIAL`, `TYPE`, `ENABLED`. Missing credentials show `-`; missing types display `bearer`.	The binding list.
`integration resolve <agent-slug>`	Table: `NAME`, `DISPLAY`, `SCOPE`, `TRANSPORT`, `CREDENTIAL`. Missing credentials show `-`.	The resolved integration list.
`integration agent update-binding <agent-slug> <binding-id>`	`Binding <binding-id> on agent <agent> updated.`	No structured output.

bind requires --agent and --server; unbind requires --agent and --binding-id. The binding ID is the value in the BINDING ID column, not the workspace integration ID.

Crew scope

Command	Human output	Structured output
`integration crew list <crew-slug>`	Table: `ID`, `NAME`, `DISPLAY`, `TRANSPORT`, `ENDPOINT`, `ENABLED`, `ACCESS`. Long endpoints are shortened.	The crew integration list.
`integration crew create <crew-slug>`	`Crew integration created: <name> (<id>)`	No structured output.
`integration crew update <crew-slug> <integration-id>`	`Crew integration <id> updated.`	No structured output.
`integration crew delete <crew-slug> <integration-id>`	Confirmation prompt, then `Crew integration <id> deleted.`	No structured output.
`integration crew test <crew-slug> <integration-id>`	The server result is printed as JSON.	The server result object.

crew delete accepts -y/--yes. crew create requires --name; its --display and --transport defaults match workspace add. --link-workspace-server links the new crew integration to a workspace integration by ID. Both crew create and crew update take --access all|bound-only, the crew-scoped equivalent of integration access.

Per-tool controls

These commands apply only to crew-scoped integrations. What disable stops. On the self-hosted/legacy MCP path a disabled tool is removed from the agent’s connected-integrations prompt block, and the crew sidecar’s MCP gateway refuses to advertise or call it from the sidecar’s next start. Agent CLIs that reach an HTTP MCP server directly through their own MCP config are not gated per tool yet. Composio-routed integrations are enforced separately, through Composio’s own allowed_tools scope, not through these bindings. See #2178.

Command	Human output	Structured output
`integration tools list <crew-slug> <integration-id>`	Table: `TOOL`, `ENABLED`, `DESCRIPTION`, `UPDATED`; missing descriptions show `-`, and long descriptions are shortened.	The tool-binding list.
`integration tools enable <crew-slug> <integration-id> <tool-name>`	`Tool <tool> on <crew>/<integration-id> enabled.`	No structured output.
`integration tools disable <crew-slug> <integration-id> <tool-name>`	`Tool <tool> on <crew>/<integration-id> disabled.`	No structured output.
`integration tools refresh <crew-slug> <integration-id>`	If the server returns an empty body: `Tool bindings refresh requested for <crew>/<integration-id>.`; otherwise the server result is printed as JSON.	The server result when it returns one.

Supplying the discovered tools to `tools refresh`

tools refresh does not perform live MCP discovery itself — you hand it the tool list a probe (or the dashboard’s test-connection round-trip) already found, and it reconciles the bindings:

Flag	Meaning
`--tool NAME` / `--tool NAME=DESCRIPTION`	One discovered tool. Repeatable. The description is everything after the first `=`, so it may itself contain `=` and `,`. Omit the `=` part when the probe found no description.
`--tools-file PATH`	Read the tools from a file. `-` reads standard input.

--tools-file accepts either a bare JSON array of {"name", "description"} objects or an MCP tools/list result verbatim ({"tools": [...]}); extra keys such as inputSchema are ignored. When both flags are given the file is read first and a --tool with the same name overrides that entry.

# From a captured probe result
crewship integration tools refresh backend intg_123 --tools-file tools.json

# Straight off a pipe
mcp-probe list-tools | crewship integration tools refresh backend intg_123 --tools-file -

# Ad hoc
crewship integration tools refresh backend intg_123 \
  --tool search="Full-text search over the issue tracker" \
  --tool create_issue

Reconciliation rules, enforced server-side:

A tool the workspace has not seen before is created enabled.
A tool that already has a binding keeps its enabled/disabled state — a refresh never silently re-enables something an operator turned off.
An entry without a description leaves the stored description alone.
A tool absent from the payload is left in place. A refresh never auto-revokes; use tools disable for that.

At least one of --tool or --tools-file is required. Running with neither exits 2 (validation) rather than posting an empty list: the server treats an empty list as a no-op, so the command would otherwise report success while changing nothing. If a probe legitimately discovered zero tools, say so explicitly with a --tools-file whose content is [].

Composio managed integrations

The integration composio group contains inventory, toolkits, tools <toolkit>, triggers types, triggers active, triggers enable <slug>, key show, key set, key remove, default show, default enable, default set <user_id>, connect <toolkit>, bind <agent-slug-or-id>, unbind <agent-slug-or-id>, bindings <agent-slug-or-id>, and the account commands account revoke <account-id>, account refresh <account-id>, and account remove <account-id>. Read commands (inventory, toolkits, tools, triggers types, triggers active, default show, key show, and bindings) use human tables or notices by default and honor --format json, yaml, or ndjson for the raw API response. Mutation commands print the text shown below.

Command	Human output / behavior
`composio inventory`	Connector catalog table (`TOOLKIT`, `NAME`, `STATUS`) and connected-users table (`USER_ID`, `APPS`, `ACCOUNTS`). If unconfigured, prints a configuration notice.
`composio toolkits`	Table `SLUG`, `NAME`, `CATEGORY`, `TOOLS`, followed by the number shown and total.
`composio tools <toolkit>`	Table `SLUG`, `NAME`, `DESCRIPTION`, followed by the number shown and total.
`composio triggers types`	Table `SLUG`, `TOOLKIT`, `TYPE`, `DESCRIPTION`, followed by the number shown and total.
`composio triggers active`	Table `ID`, `TRIGGER`, `USER_ID`, `STATE`.
`composio triggers enable <slug>`	`Trigger <slug> enabled for user "<user>" (id: <id>).` Requires `--user`.
`composio key show`	Prints whether the key is configured, its source, and optional label; never prints the key.
`composio key set`	`Composio key saved & validated (source: <source>).` Requires `--key`.
`composio key remove`	`Composio workspace key removed.`
`composio default show`	Table `FLAG`, `DEFAULT_USER`, `DEFAULT_SERVER`, `CONNECTED_USERS`; when the flag is off, also prints a note.
`composio default enable`	`Default Composio connector provisioned for user "<user>" (server <id>).`
`composio default set <user_id>`	`Default Composio connector set to user "<user>" (server <id>).`
`composio connect <toolkit>`	Prints an OAuth URL to open. Requires `--user`.
`composio bind <agent-slug-or-id>`	Prints the bound user and one indented line per provisioned app (toolkit, mode, endpoint). Requires `--user`.
`composio unbind <agent-slug-or-id>`	Removes one app with `--app`, or all apps when omitted, and prints the result.
`composio bindings <agent-slug-or-id>`	Table `TOOLKIT`, `MODE`, `USER_ID`, `ENDPOINT`; an agent with none gets a no-bindings message.
`composio account revoke <account-id>`	`Connected account <id> revoked.` The account row survives.
`composio account refresh <account-id>`	`Connected account <id> refreshed.`
`composio account remove <account-id>`	`Connected account <id> deleted.`

When Composio is unconfigured, the catalog read commands print a notice and return successfully in human mode. Set a workspace key with key set, or use the server-level COMPOSIO_API_KEY fallback.

Flags

Workspace `add`

Flag	Default	Meaning
`--name <slug>`	empty; required by the command	Integration name.
`--display <string>`	empty; becomes `--name`	Display name.
`--transport <string>`	`streamable-http`	`streamable-http` or `stdio`.
`--endpoint <url>`	empty	MCP endpoint URL.
`--command <string>`	empty	Stdio launch line.
`--icon <name>`	empty	Lucide icon name.

Workspace `bind`

Flag	Default	Meaning
`--agent <slug>`	empty; required	Agent slug.
`--server <name>`	empty; required	Integration name.
`--credential <name>`	empty	Credential to bind.
`--cred-type <string>`	`bearer`	`bearer`, `api_key`, or `basic`.
`--cred-header <name>`	empty	Custom header for `api_key`.

Workspace `unbind`

Flag	Default	Meaning
`--agent <slug>`	empty; required	Agent slug.
`--binding-id <id>`	empty; required	Agent binding row ID.

Deletes

integration remove and integration crew delete each support -y or --yes, default false, to skip confirmation.

Crew `create`

Flag	Default	Meaning
`--name <slug>`	empty; required	Integration name.
`--display <string>`	empty; becomes `--name`	Display name.
`--transport <string>`	`streamable-http`	`streamable-http` or `stdio`.
`--endpoint <url>`	empty	MCP endpoint URL.
`--command <string>`	empty	Stdio launch line.
`--icon <name>`	empty	Lucide icon name.
`--link-workspace-server <id>`	empty	Workspace integration ID to link.

Crew `update`

All flags default to empty/unset except --enabled, whose default is true. Only flags explicitly supplied are patched.

Flag	Meaning
`--display <string>`	New display name.
`--transport <string>`	New transport: `streamable-http` or `stdio`.
`--endpoint <url>`	New endpoint URL.
`--command <string>`	New stdio launch line.
`--icon <name>`	New Lucide icon name.
`--enabled <bool>`	Set enabled state.

Agent `update-binding`

All string flags default to empty/unset. --enabled defaults to true; only changed flags are sent.

Flag	Meaning
`--credential <name>`	Credential name; an explicitly empty value clears it.
`--cred-type <string>`	Credential type: `bearer`, `api_key`, or `basic`.
`--cred-header <name>`	Custom header for `api_key`.
`--env-var-name <name>`	Environment variable name; an explicitly empty value clears it.
`--enabled <bool>`	Set enabled state.

Composio filters and options

Command	Flag	Default
`toolkits`	`--search`, `--category`	empty/unset
`toolkits`	`--limit`	`0` (server-side default)
`tools <toolkit>`	`--search`	empty/unset
`tools <toolkit>`	`--limit`	`0` (server-side default)
`triggers types`	`--toolkit`, `--search`	empty/unset
`triggers types`	`--limit`	`0` (server-side default)
`triggers enable <slug>`	`--user <id>`	empty; required
`connect <toolkit>`	`--user <id>`	empty; required
`key set`	`--key <ak_…>`	empty; required
`key set`	`--label <string>`	empty; optional
`bind <agent>`	`--user <id>`	empty; required
`bind <agent>`	repeatable `--app toolkit[:mode[:tool1,tool2]]`	`[]`; mode defaults to `full`
`bind <agent>`	`--toolkits a,b`	empty; each listed toolkit gets `full` scope
`unbind <agent>`	`--app <toolkit>`	empty; empty removes all apps

For --app, mode is full, read, or custom; custom requires a comma-separated tool list. Rebinding replaces the agent’s Composio app set.

Examples

# Add a workspace HTTP integration.
crewship integration add --name gmail --display "Google Gmail" \
  --transport streamable-http --endpoint https://mcp.example.com/gmail

# Add a local stdio integration. The CLI splits this into command + args.
crewship integration add --name local-tools --transport stdio \
  --command "npx @modelcontextprotocol/server-github"

# Bind, inspect, and resolve an agent integration.
crewship integration bind --agent daniel --server gmail \
  --credential daniel-gmail-token
crewship integration agent-bindings daniel
crewship integration resolve daniel --format json

# Create and test a crew integration, then toggle a discovered tool.
crewship integration crew create engineering --name linear \
  --transport streamable-http --endpoint https://mcp.linear.app/sse
crewship integration crew test engineering intg_abc123
crewship integration tools disable engineering intg_abc123 delete_issue

# Connect an app and bind selected Composio tools.
crewship integration composio connect gmail --user user-42
crewship integration composio bind daniel --user user-42 \
  --app gmail:read --app github:full

integration test and integration crew test return whatever JSON result the server provides. For workspace HTTP integrations the server probes the endpoint; for stdio integrations it validates the configured command. The CLI does not launch a stdio server during this check. For the complete command tree as emitted by the running binary, use crewship commands --format json.

Exact command references

These headings mirror the live Cobra command paths, including commands whose details are covered in the tables above.

`crewship integration agent update-binding <agent-slug> <binding-id>`

Updates an agent integration binding; see Agent bindings above.

`crewship integration composio account`

Groups connected-account actions; see Composio managed integrations above.

`crewship integration composio account refresh <account-id>`

Refreshes a connected account.

`crewship integration composio account remove <account-id>`

Deletes a connected account at the provider.

`crewship integration composio account revoke <account-id>`

Revokes a connected account while retaining its row.

`crewship integration composio bindings <agent-slug-or-id>`

Lists an agent’s Composio bindings.

`crewship integration composio default`

Groups workspace-wide default Composio connector actions.

`crewship integration composio default enable`

Enables and provisions the workspace-wide default connector.

`crewship integration composio default set <user_id>`

Sets the connected user used by the default connector.

`crewship integration composio default show`

Shows the default connector state.

`crewship integration composio inventory`

Shows Composio toolkits and connected users.

`crewship integration composio key`

Groups workspace Composio-key actions.

`crewship integration composio key remove`

Removes the workspace Composio key.

`crewship integration composio key set`

Stores and validates a workspace Composio key.

`crewship integration composio key show`

Shows Composio-key configuration without revealing the key.

`crewship integration composio toolkits`

Lists available Composio toolkits.

`crewship integration composio tools <toolkit>`

Lists tools in a Composio toolkit.

`crewship integration composio triggers`

Groups Composio trigger actions.

`crewship integration composio triggers active`

Lists active Composio triggers.

`crewship integration composio triggers enable <slug>`

Enables a Composio trigger for a user.

`crewship integration composio triggers types`

Lists available Composio trigger types.

`crewship integration composio unbind <agent-slug-or-id>`

Removes an agent’s Composio bindings.

`crewship integration crew delete <crew-slug> <integration-id>`

Deletes a crew-scoped integration.

`crewship integration crew list <crew-slug>`

Lists integrations for a crew.

`crewship integration crew update <crew-slug> <integration-id>`

Updates a crew-scoped integration.

`crewship integration crews-overview`

Lists integrations across all crews.

`crewship integration disable <id-or-name>`

Disables a workspace integration.

`crewship integration enable <id-or-name>`

Enables a workspace integration.

`crewship integration get <id-or-name>`

Shows a workspace integration.

`crewship integration list`

Lists workspace integrations.

`crewship integration remove <id-or-name>`

Removes a workspace integration.

`crewship integration test <id-or-name>`

Tests a workspace integration connection.

`crewship integration tools enable <crew-slug> <integration-id> <tool-name>`

Enables one tool on a crew-scoped integration.

`crewship integration tools list <crew-slug> <integration-id>`

Lists tool bindings for a crew-scoped integration.

`crewship integration tools refresh <crew-slug> <integration-id>`

Reconciles tool bindings with a discovered tool list supplied on --tool or --tools-file. See Per-tool controls.

`crewship integration unbind`

Removes an integration binding from an agent.

​crewship integration

​Command reference

​Workspace scope

​Who can use an integration

​Agent bindings

​Crew scope

​Per-tool controls

​Supplying the discovered tools to tools refresh

​Composio managed integrations

​Flags

​Workspace add

​Workspace bind

​Workspace unbind

​Deletes

​Crew create

​Crew update

​Agent update-binding

​Composio filters and options

​Examples

​Exact command references

​crewship integration agent update-binding <agent-slug> <binding-id>

​crewship integration composio account

​crewship integration composio account refresh <account-id>

​crewship integration composio account remove <account-id>

​crewship integration composio account revoke <account-id>

​crewship integration composio bindings <agent-slug-or-id>

​crewship integration composio default

​crewship integration composio default enable

​crewship integration composio default set <user_id>

​crewship integration composio default show

​crewship integration composio inventory

​crewship integration composio key

​crewship integration composio key remove

​crewship integration composio key set

​crewship integration composio key show

​crewship integration composio toolkits

​crewship integration composio tools <toolkit>

​crewship integration composio triggers

​crewship integration composio triggers active

​crewship integration composio triggers enable <slug>

​crewship integration composio triggers types

​crewship integration composio unbind <agent-slug-or-id>

​crewship integration crew delete <crew-slug> <integration-id>

​crewship integration crew list <crew-slug>

​crewship integration crew update <crew-slug> <integration-id>

​crewship integration crews-overview

​crewship integration disable <id-or-name>

​crewship integration enable <id-or-name>

​crewship integration get <id-or-name>

​crewship integration list

​crewship integration remove <id-or-name>

​crewship integration test <id-or-name>

​crewship integration tools enable <crew-slug> <integration-id> <tool-name>

​crewship integration tools list <crew-slug> <integration-id>

​crewship integration tools refresh <crew-slug> <integration-id>

​crewship integration unbind

​See also