Setup mcp

Init

Set up the developer environment for agent-flow pipeline. Generates .mcp.json (MCP server configuration) and .claude/settings.json (tool permissions).

This command is the counterpart to /agent-flow:onboard:

• onboard = project config (Automation Config in CLAUDE.md)
• init = developer environment (MCP servers, tokens, permissions)

Input: $ARGUMENTS = (none) | --update | --tracker-type <type> | --tracker-instance <url> | --sc-remote <owner/repo> (flags may be combined)

Scope

This command writes to the CURRENT WORKING DIRECTORY:

• .mcp.json — MCP server configuration
• .claude/settings.json — tool auto-approval (optional)
• .gitignore — adds .mcp.json if not present

Step 0: Parameter Override

Parse $ARGUMENTS for optional CLI flags:

• --tracker-type <type> → cli_tracker_type
• --tracker-instance <url> → cli_tracker_instance
• --sc-remote <owner/repo> → cli_sc_remote

If ANY of these flags is provided:

1. Validate --tracker-type (if provided) against the lookup table in ../../core/mcp-detection.md Process step 1. Valid values: youtrack, github, jira, linear, gitea, redmine. If invalid → error: "Invalid tracker type '{value}'. Valid types: youtrack, github, jira, linear, gitea, redmine."
2. Skip Step 1 (Automation Config read). Use flag values instead:

   • Type = cli_tracker_type (if not provided, infer from cli_sc_remote hostname: github.com → github; otherwise → error: "--tracker-type is required when CLAUDE.md is not available.")

   • Instance = cli_tracker_instance (if not provided, derive default:

     Path note: trackers.md lives in the plugin installation directory. Resolve via Glob before reading defaults.

     Resolve {trackers_md_path}: Glob .claude/plugins/**/docs/reference/trackers.md (prefer path containing .claude/plugins/ or agent-flow/); fallback **/docs/reference/trackers.md; last resort docs/reference/trackers.md. If not found → use hardcoded defaults per tracker type. Read the Instance & Project Defaults table from {trackers_md_path} for the given type.)

   • Remote = cli_sc_remote (if not provided, skip SC server — tracker-only setup)

3. Proceed to Step 1b (detect .mcp.json.example) with the overridden values.

If NO flags provided: proceed to Step 1 as normal.

Composability with --update: The 3 new flags compose with --update. Example: --update --tracker-type gitea updates an existing .mcp.json with a new/changed tracker type. The --update flag controls Step 2 behavior (preserve existing servers); the new flags control Step 1 behavior (value source).

Step 1: Read Automation Config

If Step 0 provided CLI overrides → skip this step entirely (values already set).

Read Automation Config from CLAUDE.md. Extract:

• Type from Issue Tracker (determines tracker MCP server)
• Instance from Issue Tracker (determines server URL/env vars)
• Remote from Source Control (determines SC MCP server and hostname)

If no Automation Config found → error: "No Automation Config found. Run /agent-flow:onboard first."

Step 1b: Detect .mcp.json.example

If .mcp.json.example exists in CWD (typically generated by /agent-flow:scaffold):

1. Parse the file to extract pre-fill values:

   • Tracker type: Identify from MCP server package name using the reverse mapping from ../../core/mcp-detection.md lookup table (e.g., @vitalyostanin/youtrack-mcp → youtrack, gitea-mcp → gitea)
   • Instance URL: Extract from environment variable values (e.g., YOUTRACK_URL, GITEA_HOST, REDMINE_URL)
   • Remote: Extract from SC MCP server config if present (e.g., GitHub server implies GitHub remote)

2. If parsing succeeds:

   • Display: Detected .mcp.json.example from previous /scaffold run. Pre-filling: Tracker={type}, Instance={url}, Remote={remote} (omit fields that were not detected)
   • Use extracted values as defaults for Steps 3-4 (user can still override at token collection)
   • Skip redundant questions where values are already known

3. If .mcp.json.example does not exist or parsing fails:

   • No action — proceed normally to Step 2 (no warning needed)

Step 2: Detect existing .mcp.json

• If .mcp.json exists in CWD:
  • If --update → parse existing config, preserve non-agent-flow servers
  • If no flag → "Found existing .mcp.json. Update it? [Y/n]"
    • Y → parse and preserve
    • N → skip MCP setup, go to Step 6
• If .mcp.json does NOT exist → fresh mode

Step 2b: Prerequisite check

Before determining MCP servers, verify required tooling is available:

1. Node.js / npx check: npx is only needed for the YouTrack community fallback path (@vitalyostanin/youtrack-mcp@latest) — specifically when the user explicitly selects the legacy on-prem route for YouTrack Server <2026.1. For all other tracker types (github, jira, linear — HTTP transport; redmine — uvx; gitea — binary), npx is NOT required.

   If the user later selects the YouTrack legacy fallback in Step 3 and npx is not found:

   • Display error: "npx not found. Node.js is required for the YouTrack community fallback (vitalyostanin). Install Node.js from https://nodejs.org/ and retry, or use the default HTTP transport if your YouTrack is 2026.1+." → STOP that fallback path.

   Do NOT perform an upfront npx check for all tracker types — it is not needed by default.

Step 3: Determine MCP servers needed

<!-- MCP detection logic: see ../../core/mcp-detection.md -->

For each required MCP server, follow ../../core/mcp-detection.md Process step 1 to determine the expected package name and tool prefix for the declared tracker type.

If Step 1b pre-filled tracker type from .mcp.json.example: use the pre-filled value as default (user can override).

Transport, endpoint, and credential information per tracker type:

Tracker Type	Transport	Endpoint / Invocation	Credentials
youtrack	HTTP	https://<INSTANCE>.youtrack.cloud/mcp	Bearer header YOUTRACK_TOKEN (env var)
github	HTTP	https://api.githubcopilot.com/mcp/	Bearer header GITHUB_PERSONAL_ACCESS_TOKEN (env var)
jira	HTTP	https://mcp.atlassian.com/v1/mcp	OAuth via Claude Code (no env vars required in template; Cloud only)
linear	HTTP	https://mcp.linear.app/mcp	OAuth via Claude Code (no env vars required in template)
gitea	stdio (binary)	gitea-mcp binary	GITEA_ACCESS_TOKEN env var, GITEA_HOST env var
redmine	stdio (uvx)	uvx --from mcp-redmine==2026.01.13.152335 mcp-redmine	REDMINE_URL env var, REDMINE_API_KEY env var (requires Python 3.10+ and uv toolchain)

YouTrack fallback for Server <2026.1 (on-prem legacy): If the user explicitly indicates their YouTrack is an on-prem instance older than version 2026.1, offer the community fallback:

• Use npx -y @vitalyostanin/youtrack-mcp@latest (stdio transport) with YOUTRACK_URL and YOUTRACK_TOKEN environment variables.
• Inform the user: "For YouTrack Server <2026.1, use community fallback: npx -y @vitalyostanin/youtrack-mcp@latest with YOUTRACK_URL + YOUTRACK_TOKEN env vars. For YouTrack Cloud or Server 2026.1+, the default HTTP transport is recommended."
• Check npx availability at this point only (lazy check, NOT upfront in Step 2b).

Redmine uvx prereq (lazy check): When redmine is selected, verify uv is installed (which uv or where uv on Windows). If not found, display: "uv not found. Install the uv toolchain (Python 3.10+ required) from https://docs.astral.sh/uv/getting-started/installation/ and retry." → STOP redmine setup.

Shared server detection: Compare tracker Type hostname with Source Control Remote hostname.

• Gitea tracker + Gitea SC → single gitea-mcp instance (shared)
• GitHub tracker + GitHub SC → single GitHub HTTP server instance (shared)
• Mixed (e.g. Jira + GitHub SC) → two separate servers

Determine which servers to configure:

1. Tracker MCP server (always)
2. Source control MCP server (if different from tracker)

Step 4: Collect tokens

For each required MCP server, offer two options:

Your tracker is {Type}. You need a {token_name} token.
See docs/guides/tokens.md for how to create one.

(a) Paste token now — I'll add it to .mcp.json directly
(b) Skip — I'll generate .mcp.json with a placeholder (<YOUR_*>).
    You can edit .mcp.json manually later with your token.

If user pastes a token → use it in Step 6. If user skips → keep <YOUR_*> placeholder in generated .mcp.json.

For extra env vars (Instance URL, email):

• Auto-fill from Automation Config where possible (Instance → base URL)
• Ask for remaining (e.g. ATLASSIAN_EMAIL for Jira)

If shared server detected: "Your tracker ({Type}) and source control ({Remote}) use the same MCP server. One configuration covers both."

If separate SC server needed:

Your source control is on {hostname}. You need a {sc_token_name} token.

(a) Paste token now
(b) Skip — edit .mcp.json manually later

Step 5: Platform-specific handling

For gitea-mcp (Gitea tracker):

Detect platform via Bash:

uname -s  # Linux, Darwin, MINGW*/MSYS* (Windows)
uname -m  # x86_64, arm64, aarch64

Based on result, determine the asset name (pinned to v1.1.0):

Platform	uname -s	uname -m	Binary name	Asset name
macOS ARM	Darwin	arm64	gitea-mcp	gitea-mcp_1.1.0_Darwin_arm64.tar.gz
macOS x86_64	Darwin	x86_64	gitea-mcp	gitea-mcp_1.1.0_Darwin_x86_64.tar.gz
Linux ARM64	Linux	arm64 / aarch64	gitea-mcp	gitea-mcp_1.1.0_Linux_arm64.tar.gz
Linux i386	Linux	i386 / i686	gitea-mcp	gitea-mcp_1.1.0_Linux_i386.tar.gz
Linux x86_64	Linux	x86_64	gitea-mcp	gitea-mcp_1.1.0_Linux_x86_64.tar.gz
Windows ARM64	MINGW*/MSYS*	arm64	gitea-mcp.exe	gitea-mcp_1.1.0_Windows_arm64.zip
Windows i386	MINGW*/MSYS*	i386 / i686	gitea-mcp.exe	gitea-mcp_1.1.0_Windows_i386.zip
Windows x86_64	MINGW*/MSYS*	x86_64	gitea-mcp.exe	gitea-mcp_1.1.0_Windows_x86_64.zip

Version is pinned to v1.1.0. Download base URL: https://gitea.com/gitea/gitea-mcp/releases/download/v1.1.0/{asset_name}

Auto-download (default behavior):

1. Check if already installed: Run test -f ~/.claude/bin/{binary_name}. If exists → reuse, skip download. Display: "gitea-mcp already installed at ~/.claude/bin/{binary_name}"
2. Create bin directory: mkdir -p ~/.claude/bin
3. Download archive (with failure detection):

   curl -sfL -o ~/.claude/bin/{asset_name} "https://gitea.com/gitea/gitea-mcp/releases/download/v1.1.0/{asset_name}"
   

   Note: The -f (--fail) flag causes curl to exit non-zero on HTTP errors (e.g. 404) instead of saving the error page as a file.
4. Extract archive:
   • Linux/macOS: tar xf ~/.claude/bin/{asset_name} -C ~/.claude/bin/ gitea-mcp
   • Windows (MINGW*/MSYS*): Expand-Archive -Path ~/.claude/bin/{asset_name} -DestinationPath ~/.claude/bin/ -Force or unzip -o ~/.claude/bin/{asset_name} gitea-mcp.exe -d ~/.claude/bin/
5. Validate file size (guards against truncated downloads, error pages, or missing platform assets):

   FILESIZE=$(wc -c < ~/.claude/bin/{binary_name} 2>/dev/null || echo 0)
   

   If FILESIZE < 102400 (100 KB) → remove the file (rm -f ~/.claude/bin/{binary_name}), treat download as failed. Valid gitea-mcp binaries are several MiB; anything under 100 KB is corrupt or an error page.
6. Set permissions (Linux/macOS only): chmod +x ~/.claude/bin/{binary_name}
7. Verify download: If ~/.claude/bin/{binary_name} exists and passed size validation:
   • Success → Display: "Downloaded gitea-mcp v1.1.0 to ~/.claude/bin/{binary_name}"
   • Failure → continue to step 9
8. Windows download fallback sequence: If curl download failed AND platform is Windows (MINGW*/MSYS*): a. PowerShell fallback (try first): curl via Bash is unreliable on Windows — use PowerShell's Invoke-WebRequest which does not have this limitation:

   $binDir = "$env:USERPROFILE\.claude\bin"
   New-Item -ItemType Directory -Force -Path $binDir | Out-Null
   Invoke-WebRequest -Uri "https://gitea.com/gitea/gitea-mcp/releases/download/v1.1.0/{asset_name}" -OutFile "$binDir\{asset_name}" -UseBasicParsing
   Expand-Archive -Path "$binDir\{asset_name}" -DestinationPath $binDir -Force
   

   • After extraction, run size validation (step 6) against $env:USERPROFILE\.claude\bin\gitea-mcp.exe
   • If file exists and passes size check → Display: "Downloaded gitea-mcp v1.1.0 via PowerShell to {path}" → Success
   • If Invoke-WebRequest or Expand-Archive fails → continue to Go install fallback b. Go install fallback: Check if Go is available: command -v go
   • If Go is available:

     GOBIN=~/.claude/bin go install gitea.com/gitea/gitea-mcp@latest
     

     • If ~/.claude/bin/gitea-mcp.exe exists after install → Display: "Built gitea-mcp from source via go install to ~/.claude/bin/gitea-mcp.exe" → Success
     • If go install fails → Display the error, then fall back to manual path collection
   • If Go is NOT available: fall back to manual path collection
9. Non-Windows download fallback (Linux/macOS): If curl download failed AND platform is NOT Windows: a. wget fallback: Check if wget is available: command -v wget
   • If available:

     wget -q --show-progress -O ~/.claude/bin/{asset_name} "https://gitea.com/gitea/gitea-mcp/releases/download/v1.1.0/{asset_name}"
     tar xf ~/.claude/bin/{asset_name} -C ~/.claude/bin/ gitea-mcp
     chmod +x ~/.claude/bin/gitea-mcp
     

     • Run size validation (step 6) against ~/.claude/bin/{binary_name}
     • If passes → Display: "Downloaded gitea-mcp v1.1.0 via wget to ~/.claude/bin/{binary_name}" → Success
     • If wget fails → fall back to manual path collection
   • If NOT available: fall back to manual path collection

The binary path for .mcp.json: resolve ~/.claude/bin/{binary_name} to its absolute path.

Manual path collection (fallback only — if auto-download fails):

Display: "Auto-download failed. Download gitea-mcp manually from: https://gitea.com/gitea/gitea-mcp/releases" "Enter the path to your gitea-mcp binary:"

Path validation (MANDATORY):

1. Run test -f "{path}" to verify the file exists.
2. If file does NOT exist → display: "File not found at {path}. Please check the path and try again." → re-ask for the path. Max 3 attempts, then STOP with error: "gitea-mcp binary not found. Download it from https://gitea.com/gitea/gitea-mcp/releases and re-run /agent-flow:setup-mcp."
3. On Linux/macOS: verify the file is executable (test -x "{path}"). If not → run chmod +x "{path}" and inform user.

For mcp-redmine (Redmine tracker):

Redmine uses the mcp-redmine Python package via uvx — no local clone or --prefix path required.

Invocation:

uvx --from mcp-redmine==2026.01.13.152335 mcp-redmine

Prerequisites: Python 3.10+ and the uv toolchain. Install from: https://docs.astral.sh/uv/getting-started/installation/

Lazy prereq check (at this point only — NOT upfront in Step 2b): Run which uv (or where uv on Windows). If uv is not found → display: "uv not found. Install the uv toolchain (Python 3.10+ required) from https://docs.astral.sh/uv/getting-started/installation/ and retry." → STOP redmine setup.

Environment variables required:

• REDMINE_URL — full URL of your Redmine instance (e.g., https://redmine.example.com)
• REDMINE_API_KEY — your Redmine API key

No path collection is needed — uvx handles the package download and execution automatically.

Step 6: Generate .mcp.json

Load the appropriate template from examples/mcp-configs/{type}.json.

• Replace placeholder tokens with user-provided values (or keep <YOUR_*> if skipped)
• Replace placeholder URLs with values from Automation Config
• If update mode: merge into existing .mcp.json (preserve unrelated servers)
• If shared server: emit only one server entry

Write .mcp.json to CWD.

Post-write placeholder validation (MANDATORY): After writing .mcp.json, scan every "command" field in the generated JSON:

1. If any command value contains <path-to-binary> or any args value contains <PATH_TO_ → the path collection in Step 5 was incomplete.
   • Display: "ERROR: .mcp.json contains unresolved placeholder in server '{server_name}'. Returning to path collection."
   • Return to Step 5 for the affected server type and re-collect the path.
   • After re-collection, rewrite the affected server entry in .mcp.json.
2. If all command and args values are placeholder-free → proceed.

If .mcp.json not in .gitignore:

• Add .mcp.json to .gitignore

Create .mcp.json.example (same structure, all tokens replaced with <YOUR_*>).

Step 7: Validate connectivity

<!-- MCP connectivity: see ../../core/mcp-detection.md -->

For each configured MCP server with non-placeholder tokens:

1. Pre-flight: binary/command existence check (for stdio servers — gitea binary, redmine uvx, YouTrack fallback npx):

   • Read the command field from the server entry in .mcp.json.
   • For HTTP-transport servers (github, jira, linear, youtrack default): skip this check (no local binary needed).
   • For stdio-transport servers: run command -v "{command}" (or where "{command}" on Windows) to verify the command exists in PATH.
   • If command not found → "[FAIL] {server_name}: command '{command}' not found. Re-run /agent-flow:setup-mcp to fix the setup." Skip connectivity check for this server.

2. Connectivity check: Follow ../../core/mcp-detection.md (with check_write: false):

   • If mcp_available: true → "[OK] {server_name} connected successfully"
   • If mcp_available: false → "[FAIL] {server_name}: {error}. Check your token and URL." (If error_type is "tls", append: " Try adding NODE_OPTIONS: --use-system-ca to the env block in .mcp.json.")

If any placeholder tokens remain:

• "[SKIP] {server_name}: token not configured. Add it to .mcp.json later."

Step 8: Permission setup

"Would you like to configure permanent tool permissions? This prevents permission prompts when resuming sessions."

Offer 4 levels:

[1] Full pipeline (recommended) — all tools needed for fix/implement/scaffold
[2] Read-only — analysis commands only (analyze-bug, status, dashboard)
[3] Minimal — basic tools, approve MCP per-call
[4] Custom — choose specific tools

Generate .claude/settings.json based on choice:

Full pipeline:

{
  "permissions": {
    "allow": [
      "Read", "Write", "Edit", "Glob", "Grep", "Bash",
      "mcp__{tracker_prefix}__*", "mcp__{sc_prefix}__*"
    ]
  }
}

Where {tracker_prefix} and {sc_prefix} are specific to the configured servers (e.g., youtrack, gitea, github). Use specific prefixes, NOT wildcard mcp__*.

Read-only:

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "mcp__{tracker_prefix}__*"
    ]
  }
}

Minimal:

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"]
  }
}

Custom: Let user select from list of tools.

If .claude/settings.json already exists:

• Merge: add missing permissions, don't remove existing ones
• Show diff before writing

Step 9: Closing message

Developer environment configured successfully.

  .mcp.json — MCP server configuration ({N} servers)
  .mcp.json.example — template for team sharing (no secrets)
  .claude/settings.json — tool permissions ({level})

Next steps:
1. Run /agent-flow:check-setup to verify everything works
2. If you skipped tokens, add them to .mcp.json before running the pipeline

Tip: You can re-run /agent-flow:setup-mcp --update anytime to update your setup.

Rules

• NEVER write tokens into CLAUDE.md — only into .mcp.json
• NEVER commit .mcp.json to git — always add to .gitignore
• In update mode: preserve existing non-agent-flow MCP servers in .mcp.json
• In update mode: preserve existing permissions in .claude/settings.json
• Auto-fill from Automation Config where possible — minimize questions
• All wizard text in English