Integrations - Crewship

Integrations connect agents to external tools through MCP (Model Context Protocol) servers. Crewship uses a three-tier model: workspace-level MCP servers cascade down to crews, which cascade down to agent bindings, and each level can override or extend the configuration. Servers can be defined directly, discovered from the MCP registry, and authenticated with stored credentials or a full OAuth 2.0 flow.

All integration endpoints require authentication. Workspace-scoped routes also require workspace context; OAuth provider/discovery routes and MCP registry list/search routes do not. Individual sections call out additional role requirements and the unauthenticated OAuth callback.

Endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/integrations`	List workspace MCP servers
`POST`	`/api/v1/integrations`	Create a workspace MCP server
`GET`	`/api/v1/integrations/{integrationId}`	Get a workspace integration
`PATCH`	`/api/v1/integrations/{integrationId}`	Update a workspace integration
`DELETE`	`/api/v1/integrations/{integrationId}`	Delete a workspace integration
`POST`	`/api/v1/integrations/{integrationId}/test`	Test a workspace MCP connection
`GET`	`/api/v1/integrations/crews`	Cross-crew integration overview
`GET`	`/api/v1/crews/{crewId}/integrations`	List crew MCP bindings
`POST`	`/api/v1/crews/{crewId}/integrations`	Create a crew MCP binding
`PATCH`	`/api/v1/crews/{crewId}/integrations/{integrationId}`	Update a crew binding
`DELETE`	`/api/v1/crews/{crewId}/integrations/{integrationId}`	Delete a crew binding
`POST`	`/api/v1/crews/{crewId}/integrations/{integrationId}/test`	Test a crew MCP connection
`GET`	`/api/v1/crews/{crewId}/integrations/{integrationId}/tools`	List per-tool bindings
`PATCH`	`/api/v1/crews/{crewId}/integrations/{integrationId}/tools/{toolName}`	Toggle a single tool
`POST`	`/api/v1/crews/{crewId}/integrations/{integrationId}/tools/refresh`	Reconcile tool bindings
`GET`	`/api/v1/agents/{agentId}/integrations`	List agent MCP bindings
`POST`	`/api/v1/agents/{agentId}/integrations`	Create an agent binding
`PATCH`	`/api/v1/agents/{agentId}/integrations/{integrationId}`	Update an agent binding
`DELETE`	`/api/v1/agents/{agentId}/integrations/{integrationId}`	Delete an agent binding
`GET`	`/api/v1/agents/{agentId}/integrations/resolved`	Resolve effective integrations
`GET`	`/api/v1/mcp-tool-calls`	Audit trail of MCP tool invocations
`GET`	`/api/v1/oauth/providers`	List OAuth providers
`POST`	`/api/v1/oauth/initiate`	Start an OAuth flow
`GET`	`/api/v1/oauth/callback`	Handle the OAuth callback
`POST`	`/api/v1/oauth/exchange`	Exchange code for tokens
`POST`	`/api/v1/oauth/loopback`	Handle loopback redirect
`POST`	`/api/v1/oauth/discover`	Discover OAuth endpoints
`POST`	`/api/v1/oauth/auto-connect`	Create integration from OAuth
`GET`	`/api/v1/mcp-registry`	List MCP registry entries
`GET`	`/api/v1/mcp-registry/search`	Search the MCP registry
`POST`	`/api/v1/mcp-registry/sync`	Sync the MCP registry
`GET`	`/api/v1/integrations/composio/inventory`	Composio catalog + connected accounts per user
`GET`	`/api/v1/integrations/composio/toolkits`	Browse the Composio app catalog (1000+ apps)
`GET`	`/api/v1/integrations/composio/tools`	List the tools a toolkit exposes
`GET`	`/api/v1/integrations/composio/triggers`	List available trigger types
`GET`	`/api/v1/integrations/composio/triggers/active`	List active trigger instances
`POST`	`/api/v1/integrations/composio/triggers`	Create/enable a trigger instance for a user
`POST`	`/api/v1/integrations/composio/connect`	Start an OAuth Connect Link for an app/user
`GET`	`/api/v1/integrations/composio/settings`	Get the workspace Composio config status
`PUT`	`/api/v1/integrations/composio/settings`	Set & validate the workspace Composio API key
`DELETE`	`/api/v1/integrations/composio/settings`	Remove the workspace API key (revert to env)
`GET`	`/api/v1/integrations/composio/default`	Inspect the default-connector state
`PUT`	`/api/v1/integrations/composio/default`	Provision/re-point the default connector
`GET`	`/api/v1/integrations/composio/agents/{agentId}/bind`	List an agent’s Composio user binding(s)
`POST`	`/api/v1/integrations/composio/agents/{agentId}/bind`	Bind a Composio user to an agent
`DELETE`	`/api/v1/integrations/composio/agents/{agentId}/bind`	Unbind a Composio user from an agent
`POST`	`/api/v1/integrations/composio/accounts/{accountId}/revoke`	Revoke (de-authorize) a connected account
`POST`	`/api/v1/integrations/composio/accounts/{accountId}/refresh`	Refresh a connected account’s credentials
`DELETE`	`/api/v1/integrations/composio/accounts/{accountId}`	Delete a connected account

Endpoint contract

Each endpoint below has Auth, Request, Response, and Status details. Workspace routes require a session or CLI token plus membership; OAuth provider/discovery and registry list/search routes explicitly do not. Requests and responses are JSON unless noted. Workspace reads return 200, creates 201, deletes use the status stated by the endpoint, and registry sync returns 202. The shared failures are 401 unauthenticated, 403 denied workspace/role, 400 invalid JSON or fields, 404 missing or foreign resource, 409 conflict, and 500/503 for handler or unavailable-backend failures. The route gates and handler branches are verified in internal/api/router_orchestration.go, internal/api/mcp_*.go, and internal/api/oauth*.go. Auth: The endpoint-specific role or capability is authoritative; otherwise the route requires an authenticated workspace member. Request: Query parameters and JSON bodies are shown immediately under each operation. Read and delete operations have no body unless stated. Response: Successful responses are the JSON object/array described under the operation; connection tests return { "status", "message?", "server_info?" }. Status: In addition to the success status, invalid input is 400, denied access is 403, a missing resource is 404, and backend/provider failures are 500 or 503 as noted by the operation.

Managed Integrations (Composio)

Read-only inventory of the Composio managed-integration provider. See the Integrations guide for the object model. Requires COMPOSIO_API_KEY on the server; when unset the endpoint returns enabled: false with empty lists rather than an error.

Composio Inventory

GET /api/v1/integrations/composio/inventory?workspace_id={workspaceId}

Returns the connector catalog (auth configs) and every connected account grouped by Composio user_id. Gated on workspace read. This is an operator view; agents are scoped to a single user_id and never receive the full list. Response: 200 OK

{
  "enabled": true,
  "auth_configs": [
    {
      "id": "ac_JE6J7fDSsneA",
      "name": "gmail-i6p1sb",
      "status": "ENABLED",
      "toolkit": { "slug": "gmail", "logo": "https://logos.composio.dev/api/gmail" }
    }
  ],
  "users": [
    {
      "user_id": "pg-test-8acca167",
      "connected_accounts": [
        {
          "id": "ca_2pjydr0oHqiI",
          "user_id": "pg-test-8acca167",
          "status": "ACTIVE",
          "toolkit": { "slug": "gmail" },
          "auth_config": { "id": "ac_JE6J7fDSsneA", "auth_scheme": "OAUTH2", "is_composio_managed": true, "is_disabled": false }
        }
      ]
    }
  ]
}

Field	Type	Description
`enabled`	boolean	Whether the provider is configured (`COMPOSIO_API_KEY` set)
`auth_configs`	array	Connector catalog — one entry per configured app
`users`	array	Connected accounts grouped by Composio `user_id`, sorted by `user_id`

CLI: crewship integration composio inventory.

Composio Toolkits

GET /api/v1/integrations/composio/toolkits?workspace_id={workspaceId}&search={q}&category={cat}&limit={n}

Proxies the Composio app catalog (1000+ connectable apps). search, category, and limit (max 100, default 40) are optional server-side filters. Read-gated; returns enabled: false when the provider is unconfigured. Response: 200 OK

{
  "enabled": true,
  "total": 1047,
  "toolkits": [
    {
      "slug": "github",
      "name": "GitHub",
      "no_auth": false,
      "meta": {
        "description": "Code hosting platform…",
        "logo": "https://logos.composio.dev/api/github",
        "tools_count": 846,
        "categories": [{ "id": "developer-tools", "name": "developer tools" }]
      }
    }
  ]
}

Field	Type	Description
`enabled`	boolean	Whether the provider is configured
`total`	integer	Total apps matching the filter in the Composio catalog
`toolkits`	array	The current page of apps (slug, name, meta)

CLI: crewship integration composio toolkits [--search] [--category] [--limit].

Composio Tools

GET /api/v1/integrations/composio/tools?workspace_id={workspaceId}&toolkit={slug}&search={q}&limit={n}

Lists the tools a single toolkit exposes (e.g. github has 846, gmail 61). toolkit is required (400 otherwise). search and limit (max 100, default 40) are optional server-side filters. Read-gated; returns enabled: false when the provider is unconfigured. Response: 200 OK

{
  "enabled": true,
  "total": 846,
  "tools": [
    {
      "slug": "GITHUB_CREATE_AN_ISSUE",
      "name": "Create an issue",
      "description": "Create a new issue in a repository",
      "toolkit": { "slug": "github" }
    }
  ]
}

Field	Type	Description
`enabled`	boolean	Whether the provider is configured
`total`	integer	Total tools matching the filter for the toolkit
`tools`	array	The current page of tools (slug, name, description, toolkit)

CLI: crewship integration composio tools <toolkit> [--search] [--limit].

Composio Triggers

GET /api/v1/integrations/composio/triggers?workspace_id={workspaceId}&toolkit={slug}&search={q}&limit={n}

Lists the available trigger types — event subscriptions a toolkit exposes (e.g. GMAIL_NEW_MESSAGE, GITHUB_PR_OPENED). toolkit, search, and limit (max 100, default 40) are optional server-side filters. Read-gated; returns enabled: false when the provider is unconfigured. Response: 200 OK

{
  "enabled": true,
  "total": 12,
  "triggers": [
    {
      "slug": "GMAIL_NEW_GMAIL_MESSAGE",
      "name": "New Gmail message",
      "description": "Triggers when a new email arrives",
      "type": "poll",
      "toolkit": { "slug": "gmail" }
    }
  ]
}

Field	Type	Description
`enabled`	boolean	Whether the provider is configured
`total`	integer	Total trigger types matching the filter
`triggers`	array	The current page of trigger types (slug, name, description, type, toolkit)

CLI: crewship integration composio triggers types [--toolkit] [--search] [--limit].

Composio Active Triggers

GET /api/v1/integrations/composio/triggers/active?workspace_id={workspaceId}

Lists the live trigger instances in the project across all users. Read-gated; returns enabled: false when the provider is unconfigured. Response: 200 OK

{
  "enabled": true,
  "triggers": [
    {
      "id": "ti_abc123",
      "trigger_name": "GMAIL_NEW_GMAIL_MESSAGE",
      "user_id": "user-1",
      "connected_account_id": "ca_1",
      "trigger_config": { "interval": 60 }
    }
  ]
}

Field	Type	Description
`enabled`	boolean	Whether the provider is configured
`triggers`	array	The active trigger instances (id, trigger_name, user_id, connected_account_id, trigger_config, disabled_at)

CLI: crewship integration composio triggers active.

Composio Create Trigger

POST /api/v1/integrations/composio/triggers?workspace_id={workspaceId}

Creates (or re-enables) a trigger instance for a Composio user. OWNER/ADMIN only. Returns 400 if slug or user_id is empty, or if the provider is unconfigured. Request body:

{
  "slug": "GMAIL_NEW_GMAIL_MESSAGE",
  "user_id": "user-1",
  "config": { "interval": 60 }
}

Field	Type	Description
`slug`	string	Trigger-type slug to enable (required)
`user_id`	string	Composio user the trigger fires for (required)
`config`	object	Trigger-type-specific configuration (optional)

Response: 200 OK

{
  "enabled": true,
  "trigger": {
    "id": "ti_new",
    "trigger_name": "GMAIL_NEW_GMAIL_MESSAGE",
    "user_id": "user-1",
    "trigger_config": { "interval": 60 }
  }
}

CLI: crewship integration composio triggers enable <slug> --user <id>.

Composio Connect

POST /api/v1/integrations/composio/connect?workspace_id={workspaceId}

Starts an OAuth Connect Link for an app and user. Requires workspace manage (OWNER/ADMIN). Finds the toolkit’s auth config (creating a managed one on demand if none exists), then creates a Composio Connect Link for the given user. Request body:

{ "toolkit": "gmail", "user_id": "user-42" }

Field	Type	Description
`toolkit`	string	App slug to authorize (required)
`user_id`	string	Composio user to connect the account under (required)

Returns 400 if either field is empty, or if Composio is unconfigured. Response: 200 OK

{
  "redirect_url": "https://…",
  "connected_account_id": "ca_…",
  "user_id": "user-42"
}

The end-user opens redirect_url to authorize. Returns 502 on an upstream Composio failure. CLI: crewship integration composio connect <toolkit> --user <id>.

Composio Settings

Manage the per-workspace Composio API key from the app instead of the server env. The key is validated against Composio before being stored encrypted (AES-GCM). The effective key is resolved per request: the workspace key first, then the server COMPOSIO_API_KEY env fallback. The key is never returned by any endpoint.

GET    /api/v1/integrations/composio/settings?workspace_id={workspaceId}
PUT    /api/v1/integrations/composio/settings?workspace_id={workspaceId}
DELETE /api/v1/integrations/composio/settings?workspace_id={workspaceId}

GET (read) returns the status; PUT/DELETE require workspace manage (OWNER/ADMIN). PUT body: { "api_key": "ak_…", "label": "" }. The Composio host is server-controlled via the COMPOSIO_BASE_URL env var, not via this API. Response (GET / PUT / DELETE): 200 OK

{ "configured": true, "source": "workspace", "label": "Crewship_dev_1" }

Field	Type	Description
`configured`	boolean	Whether a usable key exists (workspace or env)
`source`	string	`workspace`, `env`, or `none`
`label`	string	Optional project label (workspace source only)

A PUT with an invalid key returns 400 (Composio rejected it). CLI: crewship integration composio key {show,set,remove}.

Composio Default Connector

Inspect / provision the workspace-wide default connector. When the server flag COMPOSIO_DEFAULT_CONNECTOR is ON, every agent without an explicit per-agent binding inherits this connector (full access to all the workspace’s connected apps), and legacy non-Composio MCP servers are turned off at resolve time (not deleted). See the Integrations guide.

GET /api/v1/integrations/composio/default?workspace_id={workspaceId}
PUT /api/v1/integrations/composio/default?workspace_id={workspaceId}

GET (read) reports state; PUT requires workspace manage (OWNER/ADMIN). PUT body is optional: { "user_id": "<id>" } pins the default Composio user; omit it to auto-derive the user when exactly one is connected. PUT errors 400 when zero users are connected (“connect an account first”) or when multiple users exist (pin one). Re-running is idempotent and refreshes the connector’s app set. Response (GET / PUT): 200 OK

{ "enabled_flag": true, "default_user_id": "user-a", "default_mcp_server_id": "mcp_srv_1", "connected_user_count": 1 }

Field	Type	Description
`enabled_flag`	boolean	Whether `COMPOSIO_DEFAULT_CONNECTOR` is armed on the server
`default_user_id`	string	The Composio user the default is scoped to (`""` if unset)
`default_mcp_server_id`	string	The provisioned Composio MCP server id (`""` if not provisioned)
`connected_user_count`	integer	Live count of Composio users with connected accounts

CLI: crewship integration composio default {show,set,enable}.

Composio Agent Binding

Grant an agent per-app, tool-scoped access to a Composio user’s connected apps. For each granted app the binding provisions one tool-scoped Composio MCP server and persists the rows the runtime resolver reads — a per-(agent, app) workspace MCP server pointing at the per-user Composio MCP URL, a workspace credential holding the Composio API key, and an agent MCP binding joining them (cred_type: api_key, cred_header: x-api-key). No resolver change is needed: the sidecar injects the x-api-key header on the streamable-http request. Each app carries a mode that maps to the MCP server’s allowed_tools:

Mode	`allowed_tools`	Effect
`full`	(empty)	Every tool the app exposes (no enumeration).
`read`	the app’s read-ish tools	Server-resolved: tools whose slug carries a read verb (`GET`, `LIST`, `FETCH`, `SEARCH`, `READ`, …). Conservative — unknown verbs are treated as not-read.
`custom`	the picked tool slugs	The request’s `tools`, intersected with the app’s real tools (bogus slugs are dropped).

GET    /api/v1/integrations/composio/agents/{agentId}/bind?workspace_id={workspaceId}
POST   /api/v1/integrations/composio/agents/{agentId}/bind?workspace_id={workspaceId}
DELETE /api/v1/integrations/composio/agents/{agentId}/bind?workspace_id={workspaceId}[&toolkit={slug}]

GET (read) lists the agent’s per-app Composio bindings; POST/DELETE require workspace manage (OWNER/ADMIN). POST body:

{
  "user_id": "user-42",
  "apps": [
    { "toolkit": "gmail", "mode": "read" },
    { "toolkit": "github", "mode": "full" },
    { "toolkit": "gmail", "mode": "custom", "tools": ["GMAIL_FETCH_EMAILS", "GMAIL_LIST_THREADS"] }
  ]
}

user_id is required (the Composio user the agent is scoped to). The legacy shape { "user_id": "…", "toolkits": ["gmail"] } is still accepted — each toolkit becomes an app at full. When neither apps nor toolkits is given, every connected app is bound at full. Re-binding replaces the agent’s app set: apps no longer present are removed (their server row + binding deleted). read/custom with an empty resolved tool set returns 400. DELETE with ?toolkit=<slug> removes one app; without it, removes all the agent’s Composio apps. Response (POST): 200 OK

{
  "agent_id": "clx…",
  "user_id": "user-42",
  "apps": [
    { "toolkit": "gmail", "mode": "read", "endpoint": "https://mcp.composio.dev/server/…?user_id=user-42" },
    { "toolkit": "github", "mode": "full", "endpoint": "https://mcp.composio.dev/server/…?user_id=user-42" }
  ]
}

Response (GET): 200 OK

{ "agent_id": "clx…", "bindings": [ { "toolkit": "gmail", "mode": "read", "user_id": "user-42", "endpoint": "https://mcp.composio.dev/server/…?user_id=user-42" } ] }

POST returns 404 for an unknown/foreign agent and 400 when Composio is unconfigured or no apps resolve. CLI: crewship integration composio {bind,unbind,bindings} <agent> --user <id> [--app toolkit[:mode[:t1,t2]]]….

Composio Connected-Account Management

Lifecycle operations on an existing connected account. The accountId is the Composio account id surfaced by the inventory endpoint. All three require workspace manage (OWNER/ADMIN) and return 400 when Composio is unconfigured.

POST   /api/v1/integrations/composio/accounts/{accountId}/revoke?workspace_id={workspaceId}
POST   /api/v1/integrations/composio/accounts/{accountId}/refresh?workspace_id={workspaceId}
DELETE /api/v1/integrations/composio/accounts/{accountId}?workspace_id={workspaceId}

revoke — de-authorizes the account at the provider. Its credentials are invalidated upstream; the user must re-connect before it can be used again.
refresh — refreshes the account’s credentials (e.g. exchanging a refresh token for a new access token).
delete — permanently removes the connected account at the provider.

Response: 204 No Content on success; 502 when Composio returns an error. CLI: crewship integration composio account {revoke,refresh,remove} <account-id>.

Workspace Integrations

Workspace-level MCP server definitions available to all crews and agents.

List Workspace Integrations

GET /api/v1/integrations?workspace_id={workspaceId}

Auth: Authenticated workspace member (workspace_id is required). Request: No body. Response: 200 OK

[
  {
    "id": "int_abc",
    "workspace_id": "ws_123",
    "name": "github-mcp",
    "display_name": "GitHub MCP Server",
    "transport": "stdio",
    "endpoint": null,
    "command": "npx",
    "args_json": "[\"-y\", \"@modelcontextprotocol/server-github\"]",
    "env_json": "{\"GITHUB_TOKEN\": \"{{credential:github-token}}\"}",
    "config_json": null,
    "icon": "github",
    "enabled": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "agent_binding_count": 5,
    "crew_server_count": 2
  }
]

Response Fields

Field	Type	Description
`id`	string	Integration ID
`workspace_id`	string	Workspace ID
`name`	string	Internal name
`display_name`	string	Human-readable name
`transport`	string	Transport type (validated set: `streamable-http` or `stdio`)
`endpoint`	string?	Server endpoint URL (required when transport is `streamable-http`)
`command`	string?	Command to execute (required when transport is `stdio`)
`args_json`	string?	JSON array of command arguments
`env_json`	string?	JSON object of environment variables
`config_json`	string?	Additional configuration JSON
`icon`	string?	Display icon name
`enabled`	boolean	Whether the integration is active
`agent_binding_count`	integer	Number of agent bindings
`crew_server_count`	integer	Number of crew-level servers

Create Workspace Integration

POST /api/v1/integrations?workspace_id={workspaceId}

Auth: OWNER or ADMIN role Request Body:

Field	Type	Required	Default	Description
`name`	string	Yes	—	Internal name
`display_name`	string	No	`name`	Display name (defaults to `name` when omitted)
`transport`	string	No	`"streamable-http"`	`streamable-http` or `stdio`
`endpoint`	string	Conditional	`null`	Required when `transport` is `streamable-http`
`command`	string	Conditional	`null`	Required when `transport` is `stdio`
`args_json`	string	No	`null`	JSON array of arguments
`env_json`	string	No	`null`	JSON object of env vars
`config_json`	string	No	`null`	Additional config JSON
`icon`	string	No	`null`	Display icon

{
  "name": "github-mcp",
  "display_name": "GitHub MCP Server",
  "transport": "stdio",
  "command": "npx",
  "args_json": "[\"-y\", \"@modelcontextprotocol/server-github\"]",
  "env_json": "{\"GITHUB_TOKEN\": \"{{credential:github-token}}\"}"
}

Response: 201 Created — integration object (enabled defaults to true).

Status	Condition
`400`	Missing `name`, invalid `transport`, or `endpoint`/`command` missing for the chosen transport
`403`	Insufficient role
`409`	Integration with this name already exists

Get Workspace Integration

GET /api/v1/integrations/{integrationId}?workspace_id={workspaceId}

Auth: Authenticated workspace member (workspace_id is required). Request: No body. Response: 200 OK

Status	Condition
`400`	Missing workspace context
`404`	Integration not found in the workspace

Update Workspace Integration

PATCH /api/v1/integrations/{integrationId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN role All fields optional: display_name, transport, endpoint, command, args_json, env_json, config_json, icon, enabled. Response: 200 OK

Status	Condition
`400`	Invalid JSON or invalid merged transport configuration
`404`	Integration not found

Delete Workspace Integration

DELETE /api/v1/integrations/{integrationId}?workspace_id={workspaceId}

Cascade-deletes agent bindings, crew-level overrides, and finally the workspace server, all in one transaction.

This cascades: every agent binding and crew-level override of the integration is removed alongside the workspace server, in a single transaction.

Auth: OWNER or ADMIN role Response: 200 OK

{ "status": "deleted" }

Status	Condition
`404`	Integration not found

Test Workspace Integration

POST /api/v1/integrations/{integrationId}/test?workspace_id={workspaceId}

Auth: Authenticated member with the create capability (the route’s roleCreate gate); workspace context is required. Request: No body. Tests the MCP server connection. For stdio transport the server is not actually launched (that only happens inside a container at runtime) — instead the config is statically validated (the command must tokenize to a single executable — a full launch line that splits into more than one token is rejected, while a quoted path containing spaces is fine; args_json must be a valid JSON string array), returning status: "ok" when well-formed or status: "error" otherwise. Tokenizing is quote-aware, matching the CLI/UI split rules (see the MCP guide). For streamable-http (also http/sse) an MCP initialize handshake is attempted via an SSRF-safe HTTP client (private/loopback IPs blocked). Response: 200 OK

{
  "status": "ok",
  "message": "Connected to MCP server",
  "server_info": { "name": "github-mcp", "version": "1.2.3" }
}

Field	Description
`status`	`ok`, `error`, or `auth_required` (the struct also defines `skipped`, but the current handlers never emit it)
`message`	Optional human-readable description (omitted when empty)
`server_info`	Optional raw `initialize` `result` from the server (omitted when empty)

Status	Condition
`404`	Integration not found
`401`	Missing or invalid authentication
`403`	Caller lacks the required capability

Crew Integrations

Crew-level MCP bindings — either standalone servers or overrides linked to a workspace integration. This tier also carries per-tool enable/disable state.

All Crew Integrations

GET /api/v1/integrations/crews?workspace_id={workspaceId}

Auth: Authenticated workspace member (workspace_id is required). Request: No body. Cross-crew overview of all crew-level integration bindings. Response: 200 OK — array of crew integration objects.

Status	Condition
`400`	Missing workspace context
`500`	Database failure while loading the overview

List Crew Integrations

GET /api/v1/crews/{crewId}/integrations?workspace_id={workspaceId}

Auth: Authenticated workspace member (workspace_id is required). Request: No body. Response: 200 OK — array of crew MCP server bindings.

Status	Condition
`400`	Missing workspace context
`404`	Crew not found in the workspace

Create Crew Integration

POST /api/v1/crews/{crewId}/integrations?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Default	Description
`workspace_mcp_server_id`	string	No	`null`	Link to an existing workspace integration (must be in same workspace)
`name`	string	Yes	—	Internal name
`display_name`	string	No	`name`	Display name
`transport`	string	No	`"streamable-http"`	`streamable-http` or `stdio`
`endpoint`	string	Conditional	`null`	Required when `transport` is `streamable-http`
`command`	string	Conditional	`null`	Required when `transport` is `stdio`
`args_json`	string	No	`null`	JSON array of arguments
`env_json`	string	No	`null`	JSON object of env vars
`config_json`	string	No	`null`	Additional config JSON
`icon`	string	No	`null`	Display icon

Response: 201 Created — crew MCP server object.

Status	Condition
`400`	Missing `name`, invalid `transport`, missing endpoint/command for transport, or referenced workspace integration not in same workspace
`404`	Crew not found
`409`	Integration with this name already exists in this crew

Update Crew Integration

PATCH /api/v1/crews/{crewId}/integrations/{integrationId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN role All fields optional: display_name, transport, endpoint, command, args_json, env_json, config_json, icon, enabled. Changing transport re-validates against the merged final endpoint/command. Response: 200 OK — updated crew integration object.

Status	Condition
`400`	Invalid `transport`, or endpoint/command missing for new transport
`404`	Crew integration not found

Delete Crew Integration

DELETE /api/v1/crews/{crewId}/integrations/{integrationId}?workspace_id={workspaceId}

Cascade-deletes agent bindings and any OAuth credentials that were auto-created for this integration (only when no other binding still references them).

This cascades: agent bindings are removed, and OAuth credentials auto-created for this integration are deleted too — but only when no other binding still references them.

Auth: OWNER or ADMIN role Response: 200 OK

{ "status": "deleted" }

Status	Condition
`404`	Crew integration not found

Test Crew Integration

POST /api/v1/crews/{crewId}/integrations/{integrationId}/test?workspace_id={workspaceId}

Auth: Authenticated member with the create capability; workspace context is required. Request: No body. Same probe semantics as the workspace test endpoint. Response: 200 OK — { status, message?, server_info? } (see Test Workspace Integration).

Status	Condition
`404`	Crew or integration not found
`401`	Missing or invalid authentication
`403`	Caller lacks the required capability

List Crew Integration Tools

GET /api/v1/crews/{crewId}/integrations/{integrationId}/tools?workspace_id={workspaceId}

Returns the recorded per-tool enable/disable bindings for the crew’s MCP server (mcp_tool_bindings). Only tools that have been toggled or seen via Refresh have a row; a tool with no row is treated as enabled by default. This endpoint does not contact the MCP server. Response: 200 OK — a JSON array of tool-binding objects (no wrapper).

[
  { "id": "tb_abc", "tool_name": "search", "description": "...", "enabled": true, "created_at": "2026-05-14T09:12:44Z", "updated_at": "2026-05-14T09:12:44Z" },
  { "id": "tb_def", "tool_name": "create_issue", "description": null, "enabled": false, "created_at": "2026-05-14T09:12:44Z", "updated_at": "2026-05-14T09:12:44Z" }
]

Field	Type	Description
`id`	string	Tool-binding row ID
`tool_name`	string	MCP tool name
`description`	string?	Tool description (nullable)
`enabled`	boolean	Per-crew enabled state
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Status	Condition
`404`	Crew or integration not found
`500`	Database error (a real DB failure is not collapsed to 404)

Update Crew Integration Tool

PATCH /api/v1/crews/{crewId}/integrations/{integrationId}/tools/{toolName}?workspace_id={workspaceId}
Content-Type: application/json

Upsert a single tool’s binding for this crew. If no row exists for the tool it is materialised (a fresh row defaults to enabled = true). Wraps the crewship integration tool enable/disable CLI subcommands. Auth: OWNER or ADMIN role (canRole(role, "manage")) Request Body: provide at least one of the following fields.

Field	Type	Description
`enabled`	boolean	New enabled state (omit to leave unchanged)
`description`	string	Tool description to store (omit to leave unchanged)

{ "enabled": false }

Response: 200 OK — the upserted tool-binding object (same shape as the List entries).

Status	Condition
`400`	Empty `toolName`, invalid JSON, or neither `enabled` nor `description` supplied
`403`	Insufficient role
`404`	Crew or integration not found

Refresh Crew Integration Tools

POST /api/v1/crews/{crewId}/integrations/{integrationId}/tools/refresh?workspace_id={workspaceId}

Reconcile the mcp_tool_bindings rows for this crew server against a tool list supplied in the request body (typically posted by the frontend after a successful test-connection round-trip). The server does not contact the MCP server itself: new tools are inserted enabled = true, existing tools have their description refreshed but their enabled state left untouched, and tools absent from the payload are left in place (never auto-revoked). An empty list is a no-op. Auth: OWNER or ADMIN role (canRole(role, "manage")) Request Body:

{
  "tools": [
    { "name": "search", "description": "Search issues" },
    { "name": "create_issue", "description": null }
  ]
}

Response: 200 OK

{ "created": 1, "updated": 1, "total": 2 }

total is the number of entries in the request tools array.

Status	Condition
`400`	Invalid JSON body
`403`	Insufficient role
`404`	Crew or integration not found

Agent MCP Bindings

Agent bindings link MCP servers (workspace or crew level) to specific agents, optionally with credential overrides.

List Agent Bindings

GET /api/v1/agents/{agentId}/integrations?workspace_id={workspaceId}

Auth: Authenticated workspace member (workspace_id is required). Request: No body. Response: 200 OK — array of agent MCP binding objects.

Status	Condition
`400`	Missing workspace context
`404`	Agent not found or outside the workspace

Create Agent Binding

POST /api/v1/agents/{agentId}/integrations?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Default	Description
`mcp_server_id`	string	Yes	—	ID of the MCP server to bind
`mcp_server_scope`	string	Yes	—	`workspace` or `crew`
`credential_id`	string	No	`null`	Workspace credential to attach for auth
`cred_type`	string	No	`"bearer"`	`bearer`, `api_key`, or `basic`
`cred_header`	string	No	`null`	Custom header name (used when `cred_type` is `api_key`)
`env_var_name`	string	No	`null`	Env var name for stdio credential injection
`enabled`	boolean	No	`true`	Whether the binding is active
`config_override_json`	string	No	`null`	Per-binding config override JSON

Response: 201 Created — binding object.

Status	Condition
`400`	Missing/invalid `mcp_server_id`, `mcp_server_scope`, `cred_type`, or referenced integration/credential not in this workspace
`404`	Agent not found
`409`	Agent already has a binding for this integration

Update Agent Binding

PATCH /api/v1/agents/{agentId}/integrations/{integrationId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role All fields optional: credential_id (empty string clears), cred_type, cred_header, env_var_name (empty string clears), enabled, config_override_json. Response: 200 OK

{ "status": "updated" }

Status	Condition
`400`	Invalid `cred_type`, credential not in this workspace, or no fields to update
`404`	Agent binding not found

Delete Agent Binding

DELETE /api/v1/agents/{agentId}/integrations/{integrationId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

{ "status": "deleted" }

Status	Condition
`404`	Agent binding not found

Resolve Agent Integrations

GET /api/v1/agents/{agentId}/integrations/resolved?workspace_id={workspaceId}

Returns the effective set of enabled MCP servers for an agent after cascading workspace and crew servers and applying the agent’s bindings. Credential IDs and names may be present, but secret values are never returned. The response is a JSON array; a missing agent returns 404.

[
  {
    "server_id": "srv_abc",
    "scope": "workspace",
    "name": "github-mcp",
    "display_name": "GitHub MCP Server",
    "transport": "streamable-http",
    "endpoint": "https://mcp.example.com",
    "command": null,
    "args_json": null,
    "env_json": null,
    "config_json": null,
    "icon": "github",
    "enabled": true,
    "credential_id": "cred_abc",
    "credential_name": "github-primary"
  }
]

Auth: authenticated workspace member. Request: No body. workspace_id is required; the agent must belong to that workspace. Response: 200 OK — a JSON array. The array is empty when the agent has no effective enabled integrations. endpoint, command, args_json, env_json, config_json, icon, credential_id, and credential_name are nullable; credential values and other secret material are never returned.

Status	Condition
`400`	Missing workspace context
`401`	Missing or invalid authentication
`403`	Caller is not an authorized workspace member
`404`	Agent not found in the workspace
`500`	Database failure while resolving integrations

MCP Tool Call Audit

GET /api/v1/mcp-tool-calls?workspace_id={workspaceId}

Returns the workspace’s MCP tool-invocation audit trail — one row per tool call an agent made through an MCP server — newest first, capped at 200 rows (internal/api/mcp_audit.go:69). Use the filters to scope to a single agent, server, status, or time window. Auth: authenticated workspace member (authed + workspace context — internal/api/router_orchestration.go:416). workspace_id is required (internal/api/mcp_audit.go:38). Query Parameters:

Parameter	Type	Description
`workspace_id`	string	Required. Workspace whose tool calls are returned.
`agent_id`	string	Optional. Filter to one agent (`internal/api/mcp_audit.go:48`).
`server_id`	string	Optional. Filter to one MCP server (`mcp_server_id`) (`internal/api/mcp_audit.go:52`).
`status`	string	Optional. Filter by call status (`internal/api/mcp_audit.go:56`).
`since`	string	Optional. Lower bound on `created_at` (`datetime()`-parsed, inclusive) (`internal/api/mcp_audit.go:60`).
`until`	string	Optional. Upper bound on `created_at` (inclusive) (`internal/api/mcp_audit.go:64`).

Response: 200 OK — a JSON array (empty [] when nothing matches — internal/api/mcp_audit.go:96-99).

[
  {
    "id": "mcp-call-uuid",
    "workspace_id": "ws-uuid",
    "crew_id": "crew-uuid",
    "agent_id": "agent-uuid",
    "mcp_server_id": "srv-uuid",
    "mcp_server_scope": "crew",
    "tool_name": "search_files",
    "input_hash": "sha256:…",
    "status": "success",
    "duration_ms": 142,
    "error_message": null,
    "created_at": "2026-06-30T14:02:11Z"
  }
]

Field	Type	Description
`crew_id`	string?	Owning crew; `null` for workspace-scoped servers (`internal/api/mcp_audit.go:23`).
`mcp_server_scope`	string	Scope the server was bound at, e.g. `workspace` / `crew` (`internal/api/mcp_audit.go:26`).
`input_hash`	string?	Hash of the tool input (arguments are not stored in cleartext) (`internal/api/mcp_audit.go:28`).
`status`	string	Call outcome (e.g. `success`, `error`) (`internal/api/mcp_audit.go:29`).
`duration_ms`	integer?	Wall-clock duration; `null` when not recorded (`internal/api/mcp_audit.go:30`).
`error_message`	string?	Failure detail; `null` on success (`internal/api/mcp_audit.go:31`).

Status	Condition
`200`	Audit rows returned (possibly empty).
`400`	`workspace_id` missing (`internal/api/mcp_audit.go:38-41`).

OAuth Flow

OAuth 2.0 flow for connecting external services (GitHub, Slack, Google, etc.) and storing tokens as credentials.

List OAuth Providers

GET /api/v1/oauth/providers

Returns available OAuth provider configurations. Auth: Session or CLI token (no workspace context needed) Response: 200 OK Request: No body.

Status	Condition
`200`	Provider catalog returned
`401`	Missing or invalid authentication

Initiate OAuth Flow

POST /api/v1/oauth/initiate?workspace_id={workspaceId}

Starts the OAuth authorization flow by generating an authorization URL. Auth: MANAGER+ role, or a member with the credential.create capability. Request Body:

{ "credential_id": "cred_oauth", "redirect_uri": "https://app.example/callback" }

redirect_uri is optional; when omitted, Crewship uses its backend callback. Response: 200 OK

{ "auth_url": "https://provider.example/authorize?...", "state": "..." }

OAuth Callback

GET /api/v1/oauth/callback?code={code}&state={state}

Handles the OAuth callback from the provider.

No authentication required — this endpoint uses the state token for validation instead.

Request: code and state query parameters are required; error may be returned by the provider. Response: 200 OK is an HTML success page that closes the authorization window. It is not a JSON endpoint.

Status	Condition
`400`	Missing/invalid/expired state, missing code, or provider error
`404`	Credential referenced by a valid state no longer exists
`500`	State, credential, or token-storage failure
`502`	Provider token exchange failed

Exchange Token

POST /api/v1/oauth/exchange?workspace_id={workspaceId}

Exchanges an authorization code for access and refresh tokens. Auth: MANAGER+ role, or a member with the credential.create capability. Request Body: credential_id and code are required; redirect_uri, code_verifier, and state are optional. When state is supplied without a code_verifier, the server recovers the stored PKCE verifier.

{ "credential_id": "cred_oauth", "code": "provider-code", "state": "..." }

Response: 200 OK — { "status": "ok", "credential_id": "cred_oauth" }.

Loopback

POST /api/v1/oauth/loopback?workspace_id={workspaceId}

Handles loopback redirect for local OAuth flows. Auth: MANAGER+ role, or a member with the credential.create capability. Request Body: { "credential_id": "cred_oauth" }. Response: 200 OK

{ "auth_url": "https://provider.example/authorize?...", "loopback_port": 43127, "state": "..." }

Discover OAuth Endpoints

POST /api/v1/oauth/discover

Discovers OAuth endpoints from an OpenID Connect discovery document or well-known URL. Auth: Session or CLI token (no workspace context needed) Request Body: { "mcp_url": "https://mcp.example.com" }. Response: 200 OK — { "auth_url", "token_url", "registration_endpoint?", "scopes?", "supports_pkce", "supports_dcr" }.

Status	Condition
`400`	Missing/invalid `mcp_url`
`404`	Discovery failed and the URL does not match a known provider

Auto-Connect Integration

POST /api/v1/oauth/auto-connect?workspace_id={workspaceId}

Automatically creates an integration from an OAuth connection. Auth: OWNER or ADMIN role. Request Body:

{ "mcp_url": "https://mcp.example.com", "server_name": "linear", "provider_hint": "linear" }

mcp_url is required; server_name defaults to mcp-server and provider_hint is optional. With dynamic client registration, the response is { "status": "authorize", "auth_url": "...", "credential_id": "..." }. When client registration is unavailable it returns 200 with status: "needs_client_id", auth_url, token_url, scopes, and a message so the caller can collect a client ID.

Status	Condition
`400`	Missing `mcp_url`, or OAuth discovery/provider resolution failed
`403`	Caller lacks workspace manage permission
`500`	Credential/state creation failed

MCP Registry

Public registry of MCP server definitions for easy discovery and installation.

List Registry Entries

GET /api/v1/mcp-registry

Auth: Session or CLI token (no workspace context needed) Request: no body. Response: {servers, total, limit, offset}. Query Parameters: limit (default 50, max 200), offset (default 0), trust_tier (anthropic, crewship, or community), and featured (true/false/1/0). Response: 200 OK

{ "servers": [], "total": 0, "limit": 50, "offset": 0 }

Status	Condition
`200`	Registry page returned.
`400`	Invalid `limit`, `offset`, `trust_tier`, or `featured` filter.
`401`	Missing or invalid authentication.
`500`	Registry database query failed.

Search Registry

GET /api/v1/mcp-registry/search?q={query}

Auth: Session or CLI token Request: no body. Response: {servers, total, limit, offset, query}. Query Parameters: q, plus the same limit, offset, trust_tier, and featured filters as List. An empty q behaves like List. Response: 200 OK — { "servers": [], "total": 0, "limit": 50, "offset": 0, "query": "github" }.

Status	Condition
`200`	Search results returned; an empty `q` delegates to List.
`400`	Invalid pagination or registry filter.
`401`	Missing or invalid authentication.
`500`	Registry database query failed.

Sync Registry

POST /api/v1/mcp-registry/sync?workspace_id={workspaceId}

Triggers a manual sync of the MCP registry. Auth: OWNER or ADMIN role on the workspace. Request: no body. Response: JSON status envelope below. Response: 202 Accepted — { "status": "sync_started", "message": "..." }. Manual sync is limited to once per hour; a request during the cooldown returns 429.

Status	Condition
`202`	Sync started in the background.
`401`	Missing or invalid authentication.
`403`	Caller lacks `manage` permission.
`429`	A sync was triggered within the last hour.

​Endpoints

​Endpoint contract

​Managed Integrations (Composio)

​Composio Inventory

​Composio Toolkits

​Composio Tools

​Composio Triggers

​Composio Active Triggers

​Composio Create Trigger

​Composio Connect

​Composio Settings

​Composio Default Connector

​Composio Agent Binding

​Composio Connected-Account Management

​Workspace Integrations

​List Workspace Integrations

​Response Fields

​Create Workspace Integration

​Get Workspace Integration

​Update Workspace Integration

​Delete Workspace Integration

​Test Workspace Integration

​Crew Integrations

​All Crew Integrations

​List Crew Integrations

​Create Crew Integration

​Update Crew Integration

​Delete Crew Integration

​Test Crew Integration

​List Crew Integration Tools

​Update Crew Integration Tool

​Refresh Crew Integration Tools

​Agent MCP Bindings

​List Agent Bindings

​Create Agent Binding

​Update Agent Binding

​Delete Agent Binding

​Resolve Agent Integrations

​MCP Tool Call Audit

​OAuth Flow

​List OAuth Providers

​Initiate OAuth Flow

​OAuth Callback

​Exchange Token

​Loopback

​Discover OAuth Endpoints

​Auto-Connect Integration

​MCP Registry

​List Registry Entries

​Search Registry

​Sync Registry

Endpoints

Endpoint contract

Managed Integrations (Composio)

Composio Inventory

Composio Toolkits

Composio Tools

Composio Triggers

Composio Active Triggers

Composio Create Trigger

Composio Connect

Composio Settings

Composio Default Connector

Composio Agent Binding

Composio Connected-Account Management

Workspace Integrations

List Workspace Integrations

Response Fields

Create Workspace Integration

Get Workspace Integration

Update Workspace Integration

Delete Workspace Integration

Test Workspace Integration

Crew Integrations

All Crew Integrations

List Crew Integrations

Create Crew Integration

Update Crew Integration

Delete Crew Integration

Test Crew Integration

List Crew Integration Tools

Update Crew Integration Tool

Refresh Crew Integration Tools

Agent MCP Bindings

List Agent Bindings

Create Agent Binding

Update Agent Binding

Delete Agent Binding

Resolve Agent Integrations

MCP Tool Call Audit

OAuth Flow

List OAuth Providers

Initiate OAuth Flow

OAuth Callback

Exchange Token

Loopback

Discover OAuth Endpoints

Auto-Connect Integration

MCP Registry

List Registry Entries

Search Registry

Sync Registry