Skip to main content

​
crewship ai

The Crewship binary includes an MCP stdio server, its API operation catalog, and an Agent Skill. The normal and CLI-only builds contain the same integration. No Node/Python runtime, separate MCP package, provider SDK, or downloaded skill is needed. Authenticate to your Crewship server with crewship login first. The AI client still needs its own normal model access.

​
Quick start

For an installed Codex or Claude Code client:
These run the client’s native MCP registration command. The executable path preserves the invoked symlink (for example Homebrew’s bin/crewship) instead of pinning a version inside Cellar. Install at a permanent location before connecting. Claude Code uses user scope; Codex uses its normal MCP configuration. Restart or reload the client after registration. ai connect records ownership of the exact entry. Repeating the same connection is a no-op; changing an owned entry stages the native client commands in an isolated copy of the user configuration. Failed replacement or verification preserves the previous registration and receipt. Publication refuses a configuration or receipt that changed during staging; reconnect after inspecting any concurrent edits. Reconnection requires a regular configuration file (not a symlink). Publication and rollback preserve the inspected permission bits, including broader modes such as 0644, independently of umask; they do not tighten an existing client configuration. Crewship’s new receipts and staging files request 0600. The first native client configuration is created by that client’s registration command, so its initial permissions follow the client’s policy. Atomic publication replaces the configuration inode. Permission-bit preservation does not preserve the previous inode’s owner, ACLs, extended attributes or hardlink relationships: the new file belongs to the writing user and uses filesystem defaults for other metadata. These metadata cases are not covered by the registration fixtures. Entries created by older versions or changed manually are refused: inspect them and remove them explicitly with the client before reconnecting. Other entries are untouched. Receipts contain configuration fingerprints, never tokens. Codex ownership also fingerprints its complete native JSON inspection output. A client upgrade that changes that output can make an unchanged registration appear modified; inspect it and remove it with the native client before reconnecting. --install-skill also installs the bundled guide in the client’s user skill folder, honoring CODEX_HOME or CLAUDE_CONFIG_DIR. Existing custom content is never overwritten. A content-hash receipt allows later bundles to update an unchanged guide installed by Crewship. The exact pre-workflow bundled guide can also be adopted without a receipt; other unowned guides require explicit removal or another directory. Symlinked guide files and receipts are refused. Discovery and the bundled guide work without login. The default connection executes catalog-classified reads only, including six audited POST reads: conversation and memory search, automation preview, backup content preview and restore checks, and OAuth metadata discovery. Reads can contact configured providers and still require server permissions. To enable mutations:
Each mutating call must also set confirm_write=true. This does not grant server permissions or substitute for user authorization. Select a named server/workspace explicitly when you have several:
The preview prints a command/argument array and makes no changes. Registration never copies a token into the client config. The MCP process reads Crewship’s stored credentials again before each request. A new login to the pinned profile is picked up without restart; logout refuses subsequent requests. Profile, server and workspace selection stay pinned for the session. Changing the profile’s server requires reconnecting. Environment-only credentials are captured at startup and must be available to the process. A custom CREWSHIP_CONFIG path is carried as --credential-config; the file’s contents are never copied. Administrators can narrow writes with --allow-write --write-tags crews (for operations tagged crews). Routine routes are tagged workspaces; use the operation allowlist below when enabling only routine start. Tags match exactly and unknown tags are rejected by the server. With no tag filter, non-admin writes are enabled; admin must always be listed explicitly. This is not a full authorization system: server permissions still apply. For finer control, --write-operations post_api_v1_workspaces_workspaceId_pipelines_slug_run restricts mutations to exact operation IDs. It intersects tag restrictions and does not bypass the explicit admin opt-in. Pending human approvals are bound to the current login as well as the exact request. Changing login while a form is pending invalidates that approval; submit a new request. --require-approval requests human confirmation through MCP form elicitation before each real write. The client is trusted to present the form to a human; this is not proof against a malicious client. Approval continuations expire after five minutes and are single-use, session-bound and tied to the exact arguments. Unsupported clients, cancellation and rejection fail closed. Without it, confirm_write is only the model’s acknowledgment. Tool annotations help clients apply separate approval policies but are not enforcement.

​
crewship ai connect

Supported positional clients are codex and claude. The client must be on PATH. Registration invokes an executable directly, without a shell. Registration and skill-installation receipts go to stderr, keeping stdout available for data.

​
crewship ai status

Status reports registration, ownership and whether the executable still exists. Doctor adds client paths and warnings for temporary/versioned installation paths. Neither starts the MCP server or prints tokens, environment values or unrelated client settings. Codex inspection uses its native JSON command; Claude inspection reads only its user registration. Native client commands have bounded timeouts.

​
crewship ai doctor

crewship ai doctor [codex|claude] adds installed client paths and installation warnings to the status report. With no client argument it checks both clients.

​
crewship ai disconnect

Disconnect removes only an unchanged entry owned by this CLI in that same client configuration directory. It preserves the installed skill and unrelated entries.

​
crewship ai config

For clients configured through a settings file, print a snippet:
Merge the printed entry into the client’s settings; do not replace an existing settings file with the snippet. This command itself writes no client files. codex emits TOML, vscode emits a servers JSON object with type: stdio, and generic, claude, cursor, and gemini emit an mcpServers JSON object. Configuration output uses the requested client’s syntax regardless of the CLI’s global output-format preference. The selected profile and workspace are carried into the launch arguments. Without a named profile the effective server URL is pinned. Tokens are omitted. The host-mismatch escape hatch is not automatically propagated. Compatibility depends on the client, not the model/provider name. Any client that can launch a local MCP stdio process can use this interface; configuration syntax may differ. A Grok-backed agent can use it if its host supports MCP stdio, or use the skill if it supports shell execution and Agent Skills. A hosted chat that accepts only remote HTTP MCP cannot directly launch this local adapter. Crewship does not open a public MCP listener or claim universal client support.

​
crewship ai skill

Print the exact skill embedded in this binary, or install it into a chosen skill directory (the directory containing SKILL.md, not its parent collection):
Choose a skill location supported by your client. crewship ai guide is an alias. MCP clients can read the same guide through crewship_guide, so separate skill installation is optional for MCP users. The guide explains progressive discovery, JSON input/output, profiles, mutation acknowledgments, retries, run receipts and CLI fallbacks for streaming/binary operations. Installation creates parent directories and an owner-only file. Identical content is a no-op; differing content or a symlink at SKILL.md is refused. To update an exported skill after a CLI upgrade, review/remove the old file or choose another directory. The embedded MCP guide always matches the running binary.

​
crewship mcp serve

This long-running command reserves stdout for MCP JSON-RPC and writes diagnostics to stderr. It communicates over stdin/stdout; it does not bind a port. The SDK handles initialization, tool discovery, calls and cancellation. EOF terminates the session.

​
Small tool surface

At startup, auto fetches /openapi.json from the selected server with a five-second maximum wait, a 10 MiB bound and no redirects. Failure falls back to the embedded catalog. crewship_guide reports catalog source, version, catalog SHA-256, and any fallback reason. server fails startup if the catalog cannot be loaded; embedded performs no catalog network request. Restart to refresh the catalog. Remote schemas and descriptions are untrusted data. Only method/path pairs already known to this binary are retained; operation IDs, read/write classification and tags come from the local catalog. Empty summaries/descriptions retain the local prose. Remote metadata cannot grant new write permissions. Unknown server operations require a newer binary. External schema references are refused. A fresh catalog still does not prove that every endpoint works. Routine start returns the server’s durable receipt. wait_seconds is optional for start and defaults to 30 for wait; both are capped at 300 seconds. A timeout returns the run ID, last observed state and resume_tool, without restarting or cancelling the background run. Clients requesting progress receive status notifications. A deferred receipt without run_id is returned without guessing an ID or resubmitting. Reuse the receipt and inspect state before retrying an uncertain start. A receipt marked restricted=true uses the actor-scoped restricted routine endpoint. Carry this flag into subsequent status/wait calls; the adapter never follows a server-supplied status URL. Restricted diagnosis does not query public run logs. Use crewship_list_routines with restricted=true to read the authorized private projection, including definition and execution hashes accepted by routine start. Requests accept operation_id, path_params, repeated query and headers entries (name=value), a JSON body, dry_run, confirm_write, and an optional idempotency_key. Success returns {status, headers, body}; tool failures carry isError and the CLI error envelope (error.message, error.exit_code, and HTTP status/detail/extensions when available). Responses include a text fallback for clients that do not consume structured content. The adapter shares the CLI request implementation: no redirects or automatic retries, bounded input/output, managed auth/workspace/transport headers, and normal server authorization. Tool arguments cannot choose another server, token, profile, output file, shell command or arbitrary route. Path parameters must be single segments; traversal and encoded separators are rejected. Input frames are capped at 12 MiB and JSON bodies at 10 MiB. Mutation acknowledgments and MCP annotations are not a replacement for server-side access controls. dry_run=true checks request metadata without network access; it does not validate the body against OpenAPI or predict authorization. An oversized response may arrive after a mutation succeeded. Inspect state before repeating such calls. For binary bodies/downloads, interactive authentication, streaming, WebSockets or file access, use the dedicated CLI commands or API request. The MCP adapter intentionally exposes JSON HTTP operations, not local shell execution.

​
Integration references

​
Scope and remaining limits

MCP pins the server, profile and workspace selectors. {workspaceId} is filled from the launch workspace; a conflicting value is rejected. Such routes require an explicit configured workspace. Omit that parameter when using a workspace slug; real calls resolve it under a deadline and fail closed on resolution errors. Dry-run remains offline and uses the configured selector. This does not validate workspace membership of every resource ID or JSON body: server authorization is still responsible for that. Global endpoints retain their global scope. The server catalog is loaded at startup; restart MCP to pick up schema changes. Stored credentials refresh per request, while environment tokens require a restart. An explicitly selected --credential-config file must exist and parse at startup. Its selected profile must exist and provide a valid server; without a profile, the file must provide a valid server unless a valid --server is supplied. Missing, empty or serverless files fail before replacing the active CLI state, loading a catalog or sending credentials to an environment/default fallback. Stable symlinks survive upgrades only when the installer preserves that path. Native client commands do not provide atomic compare-and-remove: avoid editing the same registration concurrently with connect or disconnect. Active Claude Code sessions can rewrite the shared user configuration and cause reconnect to refuse publication. Close those sessions, inspect the changes, then retry. The final configuration check and rename are separate operations: a write in that window can be overwritten. Active-session concurrency has not been accepted by the isolated native-client checks. Skill content and its hash receipt are likewise separate publications, not an atomic transaction; after a partial failure, inspect both files before explicitly repairing a stale receipt. Receipt recovery is manual: connect and disconnect refuse a registration whose ownership fingerprint no longer matches, including after a native client upgrade changes its reported configuration. Inspect the registration, remove it with the native client if appropriate, and reconnect; there is no automatic receipt repair. Hosted MCP with OAuth is not included. Client registration tests are not model task evaluations; no model success-rate, token-saving or speedup claim is made for 1.0. Comparable model workflow benchmarks are deferred to 1.1.