Integrations - Crewship

Crewship uses a three-tier integration model: workspace-level MCP servers cascade down to crews, which cascade down to agent bindings. Each level can override or extend the configuration. All integration endpoints require authentication and workspace context.

Workspace Integrations

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

List Workspace Integrations

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

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}

Response: 200 OK

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

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. 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}

Tests the MCP server connection. For stdio transport the test is skipped (servers can only be probed inside a container at runtime); for streamable-http an MCP initialize handshake is attempted via an SSRF-safe HTTP client. Response: 200 OK

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

Field	Description
`status`	One of `ok`, `error`, `auth_required`, `skipped`
`message`	Optional human-readable description
`server_info`	Optional raw `initialize` response from the server

Status	Condition
`404`	Integration not found

All Crew Integrations

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

Cross-crew overview of all crew-level integration bindings. Response: 200 OK — array of crew integration objects.

Crew Integrations

List Crew Integrations

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

Response: 200 OK — array of crew MCP server bindings.

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). 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}

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

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}

Response: 200 OK — array of agent MCP binding objects.

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 MCP servers for an agent after cascading workspace, crew, and agent-level configurations. Includes resolved credentials. Response: 200 OK — array of resolved integration objects.

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

Initiate OAuth Flow

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

Starts the OAuth authorization flow by generating an authorization URL. Auth: Session or CLI token + workspace membership Response: 200 OK — includes the authorization URL to redirect the user to.

OAuth Callback

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

Handles the OAuth callback from the provider. No authentication required — uses the state token for validation.

Exchange Token

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

Exchanges an authorization code for access and refresh tokens. Response: 200 OK

Loopback

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

Handles loopback redirect for local OAuth flows. Response: 200 OK

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) Response: 200 OK — discovered endpoints.

Auto-Connect Integration

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

Automatically creates an integration from an OAuth connection. Response: 200 OK

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) Response: 200 OK — array of registry entries.

Search Registry

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

Auth: Session or CLI token Response: 200 OK — matching registry entries.

Sync Registry

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

Triggers a manual sync of the MCP registry. Auth: Session or CLI token + workspace membership Response: 200 OK

API

Documentation Index

​Workspace Integrations

​List Workspace Integrations

​Response Fields

​Create Workspace Integration

​Get Workspace Integration

​Update Workspace Integration

​Delete Workspace Integration

​Test Workspace Integration

​All Crew Integrations

​Crew Integrations

​List Crew Integrations

​Create Crew Integration

​Update Crew Integration

​Delete Crew Integration

​Test Crew Integration

​Agent MCP Bindings

​List Agent Bindings

​Create Agent Binding

​Update Agent Binding

​Delete Agent Binding

​Resolve Agent Integrations

​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