💡 Conversational MCP Onboarding: Avatar-Guided Tool Marketplace

[github-actions[bot]]

Summary

Let the avatar walk users through discovering, installing, and authenticating MCP servers conversationally — turning "set up your Azure DevOps integration" from a JSON-editing chore into a 60-second dialog with Mary. The PRD already requires MCP-based writeback to Azure DevOps, GitHub, and Confluence (FR48-56), but gives no story for how non-technical users add an MCP server in the first place. This proposal closes that gap using the avatar as a guided installer over the emerging MCP marketplace ecosystem.

Market Signal

2026 has been the year MCP onboarding matured. Claude Desktop now ships one-click extension install via Settings → Extensions → Browse (April 2026); Cline runs an official MCP Marketplace that auto-clones and configures servers; Visual Studio added one-click MCP server install from the web in its April 2026 release. Every major MCP client is converging on "discover in a catalog → click → installed." The MCP spec is on the 2025-11-25 revision and The New Stack published an MCP Roadmap 2026 piece highlighting onboarding friction as the #1 remaining pain point. Crucially, none of the one-click installers are wrapped in a conversational persona — they all still require the user to know what "MCP" means, what a server does, and whether they want one. That semantic gap is exactly where TalkTerm's avatar wins.

User Signal

The PRD dedicates seven functional requirements to external-system writeback (FR48-56) — Azure DevOps, GitHub PRs, Confluence — and every one of them presumes MCP servers are already connected. FR49 literally requires "a list of available connected systems detected via MCP" but is silent on how the non-technical persona Sarah got those systems connected in the first place. Sarah cannot edit ~/.config/claude/mcp.json. Journey 1's resolution ("Sarah shares the output document with her team") is crippled if sharing means exporting a file instead of writing directly into her team's ADO board — which is precisely the promise of FR48-56. This idea is the missing prerequisite for the entire external-writeback feature set to be usable by the target persona.

Technical Opportunity

The planned architecture already defines clean extension points: src/main/agent/ hosts the agent session layer where MCP tool registration happens, and the Claude Agent SDK exposes MCP tools as first-class citizens that can be added/removed at session construction time. A new McpCatalogPort interface in src/shared/types/ports/ (fetch catalog, install server, check status, list authenticated) plus a simple GitHubMcpCatalog implementation pointing at public MCP server registries delivers the catalog layer. The avatar's overlay card system (FR18, FR45's clustered cards mode) is already the right UI primitive: render catalog entries as cards, let the user pick by voice or click, and reuse the existing confirm-plan pattern (FR20) for the install step. OAuth flows for ADO/GitHub/Confluence already have standard redirect handlers Electron can host. Nothing about this proposal requires architectural invention — it reuses ports and UI primitives that exist for other purposes.

Assessment

Dimension	Score	Rationale
Feasibility	high	No new frameworks; reuses existing overlay cards, confirm-plan, and SDK MCP tool registration. Catalog can start as a hand-curated list of 5-10 MCP servers relevant to BMAD workflows.
Impact	high	Unblocks the entire FR48-56 external-writeback feature set for the non-technical persona. Without this, those FRs cannot be used by Sarah — only by Marcus, who doesn't need them as badly.
Urgency	medium	MCP marketplaces are a commoditizing feature across all clients. TalkTerm doesn't win by being first; it wins by being the first to wrap it in a persona. The urgency is moderate — but the dependency it creates for FR48-56 is not.

Adversarial Review

Strongest objection: MCP marketplaces are already being built by Cline, Claude Desktop, VS, and others. Building yet another one is duplicative and reduces to a thin re-skin. Worse, TalkTerm does not yet have a single shipped feature — adding catalog/OAuth infrastructure now inflates the MVP.

Rebuttal: The proposal explicitly does not build a new marketplace. It builds an avatar-guided reader over existing public MCP registries — the same lists Cline and others consume. The novel work is the conversational onboarding flow, not the catalog infrastructure. MVP impact is contained by scoping the first release to a hardcoded list of 3 MCP servers (Azure DevOps, GitHub, local filesystem) with install flows tested end-to-end — catalog growth is Phase 2. This is roughly one sprint of work for a solo dev, and it is a direct precondition for FR48-56 to deliver value to the persona the PRD targets. Without it, those FRs ship dead.

Suggested Next Step

Product brief: draft a focused brief for "MCP Onboarding v0" scoped to three hand-picked servers (Azure DevOps, GitHub, local filesystem), with the conversational flow scripted end-to-end and a mocked catalog. Include an ADR deciding whether the catalog lives in the repo (static JSON) or is fetched at runtime from a public source. Validate with one non-technical user before expanding.

---

Proposed by the BMAD Analyst (Mary) on 2026-04-06.
Workflow run