---
description: "System workflow for resolving reusable MCP server support"
targets:
  - issue
  - unplanned
  - followup
autoSelect: false
updateMode: strict
requires:
  skills: []
  mcp: []
---
# MCP Resolution

## Goal

Resolve missing reusable MCP server support by finding, installing, or configuring the smallest fitting MCP server definition. Catalog new candidates only as setup references; the parent issue can resume only after `alpaca mcp verify` reports the required server or tool as usable by the target worker. If human-only setup remains, document exact steps and defer verification.

## Rules

- Treat this issue as MCP capability resolution, not as the parent issue implementation.
- Before adding MCP setup, compare skill and MCP candidates with `alpaca capability list` and `alpaca capability search`; choose MCP only when it is the better fit, including cases where configured live tool/resource/API/server access is the core missing capability.
- Prefer existing configured MCP servers and catalog-backed candidates before adding new catalog entries. Treat discovery-only catalog entries as research leads until they have reviewed server specs.
- Install only catalog-backed entries that explicitly mark setup as safe for non-interactive install and include a server spec for the selected worker target.
- Runtime dependencies for the MCP server, such as required CLI tools, packages, companion apps, or daemons, should normally be installed when they are needed and have a documented safe non-auth setup path, but only after explicit human confirmation of the exact install command or setup action.
- Never write secret values, OAuth tokens, personal access tokens, or browser session data into catalog entries, issues, comments, workflow templates, or logs.
- Keep Codex and Claude MCP differences explicit instead of assuming one server configuration fits both workers.
- Before creating or changing MCP server definitions, verify current MCP requirements from official Model Context Protocol docs and provider CLI help.

## Required Process

- Run `alpaca capability list` and `alpaca capability search "<capability>"` first to compare installed and installable skill/MCP candidates in one view.
- Use the capability results to check whether a skill fits as well as MCP, because equal-fit candidates should prefer the skill path.
- If a skill is the better fit, document that path and avoid adding MCP catalog entries or worker MCP configuration.
- Run `alpaca mcp list` and identify currently configured server refs and their usable status for the target worker set only after the MCP path remains the best fit.
- Run `alpaca mcp catalog list --include-system` only when MCP-specific catalog setup is still the chosen path, and distinguish installable entries from discovery-only entries without `servers`.
- Run `alpaca mcp search "<capability>"` and evaluate installed, installable catalog-backed, and discovery-only catalog MCP servers only after the MCP path remains the best fit. Treat `kind: "discovered"` catalog results without `servers` as research leads, not auto-install candidates.
- Install a fitting catalog-backed candidate only when its catalog setup has `safeAutoInstall: true` and a server spec for the selected target, then confirm `alpaca mcp verify --ref <ref>` passes.
- Inspect the catalog `setup` metadata, installed server command, official server docs, package metadata, and nearby README files for required runtime dependencies such as CLI binaries, npm packages, Python packages, native apps, daemons, and permission steps.
- For missing non-auth runtime dependencies, prepare the smallest documented install command or setup action, ask a human to confirm it, then run it when confirmed. Do not silently skip dependency installation when the dependency is required for the MCP server to expose tools.
- Do not install arbitrary MCP URLs or commands directly. Inspect the repository docs and add or update a reviewable catalog entry first when a new MCP definition is required.
- Before adding or recommending a new MCP server definition, check `https://modelcontextprotocol.io/specification` and `https://modelcontextprotocol.io/llms.txt`, including the relevant Transports, Tools, Resources, Prompts, Authorization, and changelog sections.
- Check `codex mcp --help` / `codex mcp add --help` and `claude mcp --help` / `claude mcp add-json --help` when command syntax or provider differences matter.
- Store only environment variable names in catalog setup metadata, and document the human steps needed to create or expose any required secret values.
- If OAuth, token creation, browser login, admin approval, secret entry, policy approval, OS permission grants, or GUI-only setup is required, complete any confirmed safe non-secret setup, write the exact human steps, and hand off instead of pretending the MCP server is fully verified.
- Verify configured refs with `alpaca mcp verify --ref <ref>` when possible without human-only authentication. If required runtime dependencies are missing, or credentials/permissions block verification, report completed setup and the remaining human step instead of treating configuration presence alone as full verification.
- Update workflow `requires.mcp` only when the workflow should depend on the resolved MCP server for future runs and the ref is not excluded from workflow requires.
- Run `alpaca workflow lint` and fix any workflow or required MCP failures.

## Handoff To Human When

- The needed MCP server requires token creation, OAuth, browser login, admin approval, secret entry, or policy approval.
- Multiple installable or discovery-only MCP candidates fit and choosing one changes security, licensing, hosting, or maintenance ownership.
- The requested capability is too broad to validate as reusable MCP server support in this issue.

## Success Criteria

- The capability is satisfied for the target worker set by a fitting skill, a configured MCP server, or exact human-only setup steps are documented.
- Any catalog entry added or updated contains no secret values.
- Safe catalog-backed install steps are completed when possible.
- Required non-auth runtime dependencies are either installed after explicit human confirmation or documented as the remaining blocker with exact commands or setup steps.
- `alpaca mcp verify --ref <ref>` passes when verification is possible without human-only authentication; otherwise verification is explicitly deferred until after auth.
- Any workflow `requires.mcp` updates use refs that `alpaca mcp verify` reports as usable by the target worker and are not excluded from workflow requires.
- `alpaca workflow lint` passes.
- The issue result names what was installed, configured, cataloged, or intentionally reused.
