Connect to Conductor¶

This page is the only document you need. Fetch it, follow it top to bottom, then call setup. Do not chase satellite pages unless something below fails.

Live: https://conductor-konstant.hectorsanchez.eu/connect.md
Offline (cloned repo): docs/guides/connecting.md

Never put the auth token value in chat, commits, or vault notes. Verify by length only.

What you are connecting to¶

Conductor is a knowledge base + Streamable HTTP MCP (2025-03-26) at https://conductor-konstant.hectorsanchez.eu/mcp.

Only MCP tool: setup(role, harness, model="").
Compiler-era tools (start_conversation, list_business_lines, …) are gone.

Do this in order¶

1) Shell / OS¶

Linux/macOS: bash/zsh is fine.
Windows: pwsh 7.2+ only. Windows PowerShell 5.1 breaks secret-gate.

2) Install secret-gate (if missing)¶

if command -v uv >/dev/null 2>&1; then
  uv tool install --force \
    'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
elif python3 -m pip --version >/dev/null 2>&1; then
  python3 -m pip install --user --upgrade \
    'git+https://github.com/Konstant-Ventures/secret-gate.git@main'
else
  echo "Install uv or pip, then retry." >&2; exit 1
fi
secret-gate status

3) Auth + export token¶

secret-gate auth   # visible terminal / zenity; never paste master password in chat
eval "$(secret-gate refresh --set ci --print-env)"
printf 'CONDUCTOR_MCP_AUTH_TOKEN present (%s chars)\n' \
  "${#CONDUCTOR_MCP_AUTH_TOKEN}"

PowerShell (pwsh):

Invoke-Expression (& secret-gate refresh --set ci --print-env --shell pwsh)
Write-Host "present ($($env:CONDUCTOR_MCP_AUTH_TOKEN.Length) chars)"

If token length is already > 0, skip refresh. Bitwarden key name: CONDUCTOR_MCP_AUTH_TOKEN (only authoritative store).

4) Configure your client (env-var references only — never literals)¶

Pick the block that matches your client. Restart the client after writing config so it inherits the parent-shell env.

OpenCode (preferred: JSON {env:…}; CLI Authorization=Bearer $… KEY=VALUE only):

{
  "mcp": {
    "conductor": {
      "type": "remote",
      "url": "https://conductor-konstant.hectorsanchez.eu/mcp",
      "headers": {
        "Authorization": "Bearer {env:CONDUCTOR_MCP_AUTH_TOKEN}"
      }
    }
  }
}

Cursor (.cursor/mcp.json) / Claude Code / generic JSON clients:

{
  "mcpServers": {
    "conductor": {
      "url": "https://conductor-konstant.hectorsanchez.eu/mcp",
      "headers": {
        "Authorization": "Bearer ${CONDUCTOR_MCP_AUTH_TOKEN}"
      }
    }
  }
}

Cursor Agent CLI: after writing mcp.json, start a new agent --print --approve-mcps … process (agent mcp enable conductor helps). Server approval ≠ tool-call approval.

Codex (bearer_token_env_var; needs network + non-git workdirs):

codex mcp add conductor \
  --url https://conductor-konstant.hectorsanchez.eu/mcp \
  --bearer-token-env-var CONDUCTOR_MCP_AUTH_TOKEN
# later runs:
codex exec -C . --sandbox danger-full-access --skip-git-repo-check "…"

Pi: stock Pi has no native MCP. Do not invent an MCP JSON file for Pi. Use the smoke script + Streamable HTTP tools/call for setup, or a Pi extension that speaks MCP. HTTP calls need Accept: application/json, text/event-stream and must reuse Mcp-Session-Id from initialize.

Query ?key= auth: last resort only (leaks easily). Prefer Bearer header.

5) Smoke (no repo clone required)¶

curl -fsS https://conductor-konstant.hectorsanchez.eu/connect/mcp-smoke.sh | bash

Expect: health OK, unauthenticated /mcp → 401, tools/list includes setup.

6) Call setup¶

setup("engineering-lead", "opencode")   # change role/harness as needed

Then clone/pull the conductor repo and read conductor/docs/agents/<role>.md as setup instructs.

Endpoints¶

Purpose	URL
MCP	`https://conductor-konstant.hectorsanchez.eu/mcp`
Health	`https://conductor-konstant.hectorsanchez.eu/health`
Status (non-secret)	`https://conductor-konstant.hectorsanchez.eu/connect/status`
Smoke script	`https://conductor-konstant.hectorsanchez.eu/connect/mcp-smoke.sh`
This page	`https://conductor-konstant.hectorsanchez.eu/connect.md`
Docs site	`https://conductor-docs.hectorsanchez.eu`

Unauthenticated: /, /health, /connect, /connect.md, /connect/*.

If something fails¶

Symptom	Fix
Relative link → 401	Stay on this page; use absolute URLs only
secret-gate fails on Windows	Use `pwsh` 7.2+, not 5.1
Auth prompt invisible	Human runs `secret-gate auth` in a visible terminal
Token missing after refresh	Re-`eval` / `Invoke-Expression` in the same shell that launches the client
OpenCode echoes token in error	Use `Authorization=Bearer …` (equals) or JSON `{env:…}`
Codex cannot fetch HTTPS	`--sandbox danger-full-access`
Codex “not trusted directory”	`--skip-git-repo-check`
Tools missing after config	Restart client from the exporting shell
Looking for `list_business_lines`	Archived — only `setup` exists

References¶

Source: https://github.com/hector-sanchez-eu/conductor
secret-gate: https://github.com/Konstant-Ventures/secret-gate
Operate / konstant: konstant · hosts · tooling
Konstant lab repo (recovery): hector-sanchez-eu/konstant-server
Tailscale fallback: Konstant ops (Host header to Funnel)