Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Integrations

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

​
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

ProviderAuth URLDefault Scopes
Googleaccounts.google.com/o/oauth2/v2/authGmail, Calendar, Drive
Slackslack.com/oauth/v2/authorizechannels:read, chat:write
GitHubgithub.com/login/oauth/authorizerepo, user
Microsoftlogin.microsoftonline.com/.../authorizeMail, Calendars
Linearlinear.app/oauth/authorizeread, write
GitLabgitlab.com/oauth/authorizeapi, read_user
Cloudflaredash.cloudflare.com/oauth2/authorize(custom)
Stripeconnect.stripe.com/oauth/authorizeread_write
Notionapi.notion.com/v1/oauth/authorize(custom)

​
OAuth Flow

1

Create OAuth credential

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

Authorize the connection

Click “Connect” to start the PKCE authorization flow:
  1. Crewship generates a code_verifier (32 random bytes, base64url-encoded)
  2. Computes code_challenge = SHA256(code_verifier), base64url-encoded
  3. Redirects user to provider’s authorization URL
3

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

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

TransportDescriptionUse Case
stdioServer runs as a subprocessLocal tools, custom scripts
streamable-httpHTTP-based communicationRemote/cloud MCP servers
sseServer-Sent EventsLegacy 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.

​
MCP Gateway

The MCPGateway (internal/sidecar/mcp_gateway.go) manages MCP server connections:
  1. Connect: Establishes connections to all configured MCP servers at sidecar startup (15-second timeout)
  2. Discover tools: Queries each server for available tools
  3. Route calls: Proxies tool calls from agents to the correct MCP server

​
Sidecar MCP Endpoints

EndpointMethodDescription
/mcp/toolsGETList all available tools from connected MCP servers
/mcp/callPOSTCall a specific tool on an MCP server
/mcp/statusGETCheck 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. Registry entries include:
  • Server name and display name
  • Description and category
  • Package information (runtime, environment variables)
  • Remote transport configuration
  • Verification status
This allows users to browse and install MCP servers from the registry without manual configuration.

​
Crew Connections

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

​
Connection Endpoints (via Sidecar)

EndpointMethodDescription
/crew-connectionsGETList crew connections
/crew-connectionsPOSTCreate a crew connection
/connectionsGETList active connections
/connections/{id}/messagePOSTSend a message to connected crew
/connections/{id}/messagesGETRead messages from connection
/connections/{id}/filesGETRead shared files
/connections/{id}/filesPOSTWrite 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.