/configure-server

name: configure-server
description: "Configures how the MCP Task Orchestrator SERVER runs and is reached — transport (HTTP vs STDIO), the REST API, port publishing, config mounts, and config-sync. Use when a user says: run the server, register the image, set up the Docker container, enable the REST API, set up config-sync, reconfigure the server, change transport, expose the API, reconnect to a different endpoint, or allow a hostname. NOT for first-time onboarding (that's quick-start), NOT for project/personal setup (that's init), and NOT for note schemas / gates / traits / actor_authentication policy (that's manage-schemas) — this skill only decides how the container is launched and reached."
argument-hint: "[optional: 'recommended', 'http', 'stdio', 'bearer', or a change request e.g. 'enable REST']"

Configure Server — Runtime & Transport Setup

Decides **how the MCP Task Orchestrator container is launched and reached**: transport, REST API mode, port publishing, config mount, and config-sync. This is a runtime/deployment concern, distinct from `quick-start` (first-time onboarding narrative) and `manage-schemas` (workflow gates/traits/ `resources:`/`actor_authentication` content inside `.taskorchestrator/config.yaml`). If the user wants schema or gate changes — including resource-lease declarations — redirect to `/manage-schemas` instead of proceeding here.

One operator escape hatch worth knowing when launching the container: `RESOURCE_LEASES_ENFORCED=false` (env, default true) disables resource-lease gate enforcement server-wide — a kill switch for lease contention incidents, same gate-policy category as `DEGRADED_MODE_POLICY`. Configuring which resources exist and which traits declare them stays in `/manage-schemas`; this skill only knows the switch.

The full fragment catalog (exact env tuples, loopback caveat, Windows/MSYS caveat, `.mcp.json` shapes) lives in `references/runtime-config.md` — this skill's job is the **decision flow** and **rendering**, not re-deriving that catalog. Read it before rendering any command.

---

Step 1 — Offer the recommended default first

Before walking the full decision tree, offer the one-tap recommended path via `AskUserQuestion`:

AskUserQuestion(questions: [{
  question: "How do you want to run the server?",
  header: "Server setup",
  multiSelect: false,
  options: [
    { label: "Recommended default", description: "HTTP + REST API enabled, unauthenticated, loopback-bound (127.0.0.1). Enables config-sync out of the box. Best for a single developer working across multiple projects." },
    { label: "Customize", description: "Walk through transport, REST mode, config mount, and debug logging one at a time." }
  ]
}])

**Recommended default** → skip straight to Step 5 (Render — HTTP) with: REST = unauthenticated, config mount = none, debug = off. **Customize** → Step 2.

Why this is the default: it is the majority deployment shape for a single developer who wants `config-sync` (per-project config that hot-reloads without a restart) to just work across every project they open, without hand-managing tokens. The image itself still ships conservative (STDIO, REST off, `0.0.0.0` bind) — this posture is entirely rendered by this skill, never an image change.

---

Step 2 — Transport

AskUserQuestion(questions: [{
  question: "Which transport?", header: "Transport", multiSelect: false,
  options: [
    { label: "HTTP (Recommended)", description: "Detached daemon, serves /mcp on a published port. Required for REST API and config-sync." },
    { label: "STDIO", description: "Per-session process, no port, no REST API, no config-sync. Simpler, no persistent daemon." }
  ]
}])

**STDIO ⊥ REST — hard constraint:** if the user picks STDIO, skip Steps 3-4 entirely (REST mode and port are incoherent for a `--rm -i` per-session process) and go straight to Step 5 (Render — STDIO). Tell the user plainly: *"STDIO has no REST API and no config-sync — those require a persistent HTTP daemon. If you want config-sync later, re-run this skill and choose HTTP."*

HTTP → Step 3.

---

Step 3 — REST API mode (HTTP only)

AskUserQuestion(questions: [{
  question: "REST API mode?", header: "REST API", multiSelect: false,
  options: [
    { label: "Unauthenticated (Recommended)", description: "No token needed. Loopback-bound only. Enables config-sync with zero extra setup." },
    { label: "Bearer token", description: "Token-authenticated. For shared/multi-user setups." },
    { label: "Off", description: "MCP only, no REST, no config-sync." }
  ]
}])

• **Unauthenticated** → always render the loopback SECURITY caveat from `references/runtime-config.md`

("Loopback footgun") before the command, and force `-p 127.0.0.1:3001:3001` in the render — never a wider publish.

• **Bearer** → ask for the host path to the token YAML (free-text/"Other" answer), e.g.

`~/.taskorchestrator-secrets/api-tokens.yaml`. If the file doesn't exist yet, point at `current/docs/api-rest.md` §1 for the token-generation snippet — this skill does not generate tokens.

• **Off** → REST fragment is just `-e API_ENABLED=false`; config-sync will no-op (tell the user).

---

Step 4 — Config mount and debug (HTTP only)

AskUserQuestion(questions: [{
  question: "Mount this project's config as the server's global/fallback config?", header: "Config mount", multiSelect: false,
  options: [
    { label: "This project (fallback)", description: "Mount ./.taskorchestrator read-only as AGENT_CONFIG_DIR — good for a single-project server." },
    { label: "None (multi-project)", description: "No mount. Per-project config flows in via config-sync into the DB per root — good for one server shared across projects." }
  ]
}])

Then ask Yes/No for debug logging (`LOG_LEVEL=DEBUG` + `DATABASE_SHOW_SQL=true`).

---

Step 5 — Render

Look up the exact fragments in `references/runtime-config.md` — do not improvise env values.

STDIO

Render the `.mcp.json` **args a