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.

Every CLI adapter implements MCP (Model Context Protocol) differently. Crewship’s per-adapter WriteMCPConfig translates a single canonical MCP config into each CLI’s expected file path + format. This page documents the per-CLI schema so operators can debug MCP issues directly.

​
Quick reference

CLIConfig fileTop-level keyEnv-var syntaxBearer token fieldApprove flag
Claude Code/crew/agents/<slug>/.mcp.jsonmcpServers${VAR}(in headers)none
Codex/crew/agents/<slug>/.codex/config.toml[mcp_servers.X]TOML literalbearer_token_env_var = "VAR"none
Gemini/output/<slug>/.gemini/settings.jsonmcpServers${VAR} or $VAR(in headers)none
OpenCode/output/<slug>/opencode.jsonmcp{env:VAR}(in headers)none
Cursor/output/<slug>/.cursor/mcp.jsonmcpServers${env:VAR}(in headers)--approve-mcps
Factory Droid/output/<slug>/.factory/mcp.jsonmcpServers${VAR}(in headers)none

​
Schema differences

​
Stdio servers (local subprocess)

Claude / Cursor / Gemini / Droid — separate command + args: 
{"command": "npx", "args": ["-y", "@scope/pkg"], "env": {"FOO": "${VAR}"}}
OpenCode — command is an array (binary + args together), env field is environment: 
{"type": "local", "command": ["npx", "-y", "@scope/pkg"], "environment": {"FOO": "{env:VAR}"}}
Codex (TOML): 
[mcp_servers.fs]
command = "npx"
args = ["-y", "@scope/pkg"]
# env block omitted when values are ${VAR} refs — Codex doesn't interpolate

​
HTTP servers (remote)

Claude / Cursor / Droid — url + headers: 
{"type": "http", "url": "https://mcp.example.com", "headers": {"Authorization": "Bearer ${TOKEN}"}}
Gemini — preferred httpUrl (current) or legacy url (SSE): 
{"httpUrl": "https://mcp.example.com", "headers": {"Authorization": "Bearer ${TOKEN}"}}
OpenCode — type: remote: 
{"type": "remote", "url": "https://mcp.example.com", "headers": {"Authorization": "Bearer {env:TOKEN}"}}
Codex — narrower schema, uses dedicated env-var fields: 
[mcp_servers.linear]
url = "https://mcp.example.com"
bearer_token_env_var = "TOKEN"
# Optional generic headers:
env_http_headers = { "X-API-Key" = "API_KEY_VAR" }   # ${VAR} headers
http_headers = { "X-Custom" = "literal-value" }      # literal headers

​
Common pitfalls

​
1. Cursor MCP is currently inert in --print mode

cursor-agent --print does not invoke MCP servers at runtime even with --approve-mcps set — the binary lists registered servers via cursor-agent mcp list but never actually calls them in headless mode (forum #143045, #148397, confirmed against latest builds). The Crewship adapter reflects this honestly: adapter_cursor.go returns SupportsMCP() == false, which means the orchestrator skips WriteMCPConfig entirely — no .cursor/mcp.json is written and the --approve-mcps flag is suppressed despite being a known cmdline option. If a future Cursor release wires MCP into --print, flip SupportsMCP and the rest of the pipeline (config write, flag, table row above) lights up automatically.

​
2. Codex doesn’t interpolate ${VAR}

If you write env = { LINEAR_TOKEN = "${LINEAR_TOKEN}" } to Codex’s config, Codex passes the LITERAL string "${LINEAR_TOKEN}" as the env var to spawned MCP servers — they get the raw ${LINEAR_TOKEN} string instead of the secret. Crewship’s writer omits ${VAR}-style entries from the env block; Codex inherits container env instead.

​
3. OpenCode {env:VAR} syntax

Cursor’s ${env:VAR} and Anthropic’s ${VAR} are NOT recognised by OpenCode. Crewship’s translateEnvRefsToOpenCode converts standard forms — including substrings like "Bearer ${LINEAR_TOKEN}" (the dominant Authorization header pattern).

​
4. Codex config in $HOME, not project root

Codex’s project-scoped .codex/config.toml is only loaded for “trusted” projects, with trust established interactively. Headless invocations skip it. Crewship writes to /crew/agents/<slug>/.codex/config.toml (HOME) so Codex picks it up unconditionally.

​
Verifying MCP config

crewship agent mcp <agent-slug> --resolved
Dumps the resolved MCP config that the adapter writes. Useful for spot-checking env-var translation, file paths, and per-CLI schema differences before exec.

​
Adding an MCP server

Crew settings → MCP Servers → Add. Crewship merges crew + agent configs and writes per-adapter via mcp_writers.go. Standard input format is the Anthropic/Claude shape — every other adapter’s format is generated from it via the shared normaliseMCPInputs helper.