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

# AI clients

> Connect AI clients to the MCP server and Agent Skill embedded in the Crewship binary.

# 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:

```bash theme={null}
crewship ai connect codex
crewship ai connect claude --install-skill
```

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:

```bash theme={null}
crewship ai connect codex --allow-write
```

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:

```bash theme={null}
crewship --profile staging --workspace engineering ai connect claude --allow-write
crewship --profile staging ai connect codex --dry-run
```

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

| Flag | Default | Purpose |
| - | - | - |
| `--catalog` | `auto` | Select `auto`, required `server`, or offline `embedded` catalog. |
| `--write-operations` | (unset) | Further restrict writes to exact operation IDs. |
| `--write-tags` | (unset) | Restrict mutations to exact catalog tags; admin requires explicit inclusion. |
| `--require-approval` | `false` | Require human approval through MCP elicitation. |
| `--allow-write` | `false` | Enable explicitly confirmed mutations in the registered server. |
| `--dry-run` | `false` | Print registration arguments without executing the client. |
| `--install-skill` | `false` | Install the bundled skill in the client’s user skill directory without overwriting custom content. |

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

```bash theme={null}
crewship ai status
crewship ai doctor claude
crewship ai disconnect codex --dry-run
crewship ai disconnect codex
```

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.

| Flag | Default | Purpose |
| - | - | - |
| `--dry-run` | `false` | Check ownership and report whether removal would occur without changing configuration. |

## crewship ai config

For clients configured through a settings file, print a snippet:

```bash theme={null}
crewship ai config cursor
crewship ai config vscode
crewship ai config gemini
crewship ai config generic
crewship ai config codex
```

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.

| Flag | Default | Purpose |
| - | - | - |
| `--catalog` | `auto` | Select `auto`, required `server`, or offline `embedded` catalog. |
| `--write-operations` | (unset) | Further restrict writes to exact operation IDs. |
| `--write-tags` | (unset) | Restrict mutations to exact catalog tags; admin requires explicit inclusion. |
| `--require-approval` | `false` | Require human approval through MCP elicitation. |
| `--allow-write` | `false` | Include the mutation opt-in in the launch arguments. |

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):

```bash theme={null}
crewship ai skill
crewship ai skill --directory .agents/skills/crewship
crewship ai skill --directory .claude/skills/crewship
```

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.

| Flag | Default | Purpose |
| - | - | - |
| `--directory` | (unset) | Install the bundled `SKILL.md` into this directory. |

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

```bash theme={null}
crewship mcp serve
crewship --profile staging mcp serve --allow-write
```

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.

| Flag | Default | Purpose |
| - | - | - |
| `--catalog` | `auto` | Select `auto`, required `server`, or offline `embedded` catalog. |
| `--write-operations` | (unset) | Further restrict writes to exact operation IDs. |
| `--write-tags` | (unset) | Restrict mutations to exact catalog tags; admin requires explicit inclusion. |
| `--require-approval` | `false` | Require human approval through MCP elicitation. |
| `--allow-write` | `false` | Allow mutations with per-call `confirm_write=true`. |
| `--credential-config` | (unset) | Explicit CLI credential file, usually generated from `CREWSHIP_CONFIG`. |
| `--timeout` | `30s` | Overall timeout for each API call; must be positive. |
| `--max-response-bytes` | `1048576` | API response cap, from 1 to 10485760 bytes. |

### Small tool surface

| Tool | Purpose |
| - | - |
| `crewship_guide` | Read the bundled skill and current write policy. |
| `crewship_search` | Rank whole-token matches across summaries, descriptions, paths, IDs and tags; supports common action synonyms. Defaults to 20 results, maximum 100; follow `next_offset`. |
| `crewship_schema` | Read one operation's OpenAPI contract with referenced schemas. |
| `crewship_read` | Execute only catalog-classified reads; annotated read-only. |
| `crewship_write` | Execute only mutations; conservatively annotated potentially destructive. |
| `crewship_list_agents`, `crewship_list_crews`, `crewship_list_routines` | Common discovery in the pinned workspace. |
| `crewship_routine_start` | Submit an asynchronous routine with optional bounded waiting. Same write and human-approval policy as raw writes. |
| `crewship_run_status`, `crewship_run_diagnose` | Read run state, or state together with logs. |
| `crewship_run_wait` | Wait for an existing run, with progress notifications and a resumable timeout receipt. |
| `crewship_crew_status` | Read crew configuration and runtime status together. |

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](/cli/api). The MCP
adapter intentionally exposes JSON HTTP operations, not local shell execution.

## Integration references

* [Official MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)

* [Agent Skills format](https://agentskills.io/specification)

* [Codex MCP configuration](https://developers.openai.com/codex/mcp)

* [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp)

* [Cursor MCP configuration](https://cursor.com/docs/mcp)

* [VS Code MCP configuration](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

* [Gemini CLI MCP configuration](https://geminicli.com/docs/tools/mcp-server/)

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.