azidan/archflow/archflow-setup-mcp

Invoke with $archflow-setup-mcp. Arguments are the text after the mention.

Arguments: [tool-name]

$archflow-setup-mcp — MCP Server Setup Helper

Argument (the text the user wrote after the skill mention): optional tool name (e.g. jira, notion). Empty → list the registry.

Configure external tool MCP servers for use with Codex.

Usage

$archflow-setup-mcp              → List available MCPs from registry
$archflow-setup-mcp [tool-name]  → Configure a specific MCP server

Registry

The curated MCP registry is stored in .codex/archflow/skills/archflow/mcp-registry.yaml. Read that file to look up tool details. Edit it to add or update MCP servers.

Invocation

When the user runs $archflow-setup-mcp, follow this flow exactly.

Flow

Step 1: Check If Already Configured

claude mcp list

Parse the output. If the requested tool is already listed:

"[Tool] MCP is already configured. No action needed."

If not found, proceed to Step 2.

Special case — shared MCPs: Some tools share a server (e.g., Jira and Confluence both use Atlassian Rovo). If the registry entry has shared_with, check if that sibling is already configured. If so:

"[Tool] is available through the already-configured [sibling] MCP (same server). No additional setup needed."

Step 2: Lookup in Registry

Read .codex/archflow/skills/archflow/mcp-registry.yaml and search for the tool name (case-insensitive). If found, show:

"[Tool] MCP uses [command/url] via [transport] transport."

Purpose: [purpose]

If the entry has notes, show those too.

If not found, go to Fallback section.

Step 3: Collect Credentials

For tools with env_required, ask the user for each variable one at a time:

• Show the description and help_url (if available)
• Wait for user input before proceeding to the next variable

For tools with auth: oauth, inform the user:

"This MCP uses OAuth authentication. The browser will open for authorization during setup."

Step 4: Install

Build and run the appropriate command based on transport type:

For `stdio` transport:

claude mcp add --transport stdio \
  --env KEY1=val1 --env KEY2=val2 \
  [tool-name] -- [command]

For `http` transport with OAuth:

claude mcp add --transport http \
  [tool-name] [url]

Then verify:

claude mcp get [tool-name]

Step 5: Confirm

"Configured [Tool] MCP. Restart Codex or run /mcp to verify the connection."

If the tool is onboarding_only: true and was set up during $archflow-onboard:

"Tip: This MCP was added for onboarding import. You can remove it later with: claude mcp remove [tool-name]"

Fallback: Tool Not in Registry

If the tool name is not in the registry:

1. Search npm for mcp-[tool] or @modelcontextprotocol/server-[tool]:

npm search mcp-[tool] --json 2>/dev/null | head -20
npm search @modelcontextprotocol/server-[tool] --json 2>/dev/null | head -20

1. If a package is found, show it to the user:

"Found [package-name]: [description]"

"Install this MCP? [Yes / No]"

1. If confirmed, build the stdio command:

claude mcp add --transport stdio [tool-name] -- npx -y [package-name]

1. If nothing found:

"No MCP package found for '[tool]'. You can add it manually:"

```

claude mcp add --transport stdio [name] -- [command]

claude mcp add --transport http [name] [url]

```

Listing Available MCPs

When invoked without arguments ($archflow-setup-mcp), read .codex/archflow/skills/archflow/mcp-registry.yaml and show the registry as a table:

Available MCP Servers:
 
| Tool         | Transport | Auth   | Purpose                              |
|--------------|-----------|--------|--------------------------------------|
| jira         | http      | oauth  | Fetch epics, stories, sprint data    |
| confluence   | http      | oauth  | Fetch Confluence pages and spaces    |
| notion       | http      | oauth  | Fetch pages and databases            |
| linear       | http      | oauth  | Fetch issues, projects, cycles       |
| github       | http      | oauth  | Fetch issues, PRs, project boards    |
| google-drive | stdio     | oauth  | Fetch Google Docs, Sheets            |
| slack        | http      | oauth  | Fetch context from channels/threads  |
| trello       | stdio     | env    | Fetch boards, lists, cards           |
| superdesign  | stdio     | —      | Generate hi-fi UI screens (Phase 2.25)|
 
Usage: $archflow-setup-mcp [tool-name]

Note: Jira and Confluence share the same Atlassian Rovo MCP server — configuring one gives access to both.

Notes

• The registry file (mcp-registry.yaml) is the single source of truth. Edit it to add new tools.
• Package names are best-effort. If claude mcp add fails, try the fallback npm search.
• Some MCPs require Codex restart after configuration.
• OAuth MCPs will open a browser window for authorization.