codewhale-hq / mcp-discovery

mcp-discovery

The public MCP Registry ships hundreds of ready-made stdio servers
(filesystems, databases, browsers, media processing, developer utilities, cloud
APIs, SaaS integrations, …). This skill is how you reach one when the session
is genuinely missing a capability.

It is a fallback, not a first step. Discovery costs a tool_search to load the
deferred tools, a query, an approval, and an install — spend that only when it
buys a capability you do not have.

When to use

• An available tool, a project script or test, or a few lines of local code
  cannot do the job.

• The task needs an external service, database, or protocol client that this
  session has no access to.

• You would otherwise install a package or reimplement a well-known converter
  or client by hand.

When not to use

• Ordinary work: writing and editing files, reading fixtures, running repo
  commands, and checking your own output. Do those directly.

• A capability an already-loaded tool covers, even partially — try it first.

• A near-miss row in a result list. A scored match is a suggestion; the missing
  capability is what decides.

Workflow

1. Name the gap. State the capability you lack before searching. If you
   cannot name one, you do not need the Registry.

2. Load and query. registry_sync and start_registry_mcp_server are
   deferred: load one with tool_search and use the returned schema. If a call
   only loads the schema without executing, retry once with that schema. Then call
   registry_sync {query: "<the missing capability>"}. It scores a host-side
   snapshot and returns at most eight matches; the full index never enters the
   conversation. Packages declaring any environment variable (including API
   keys/tokens) are excluded and never written to the cache.

3. Judge the matches. Take a server when it covers the gap you named. If
   nothing does, refine the query once, then continue with local tools.

4. Install + run transactionally. Call
   start_registry_mcp_server {registry_name: "<exact name>", arguments: {...}}.
   Supply only values listed in required_args; omit arguments when none are
   required. Never install or launch the package through the shell. Starting a
   server requires approval.

5. Solve the task with the new tools. Their complete schemas are added to
   the current turn immediately after a successful connection; call the exact
   names returned by the start result.

If a server fails to start

start_registry_mcp_server reports when a package exits before the handshake
(often CLI help output = incomplete launch args). Verify the exact required
arguments, retry once with the corrected structured values, and if it still
fails move on to the next candidate or to a local approach. Failed starts are
rolled back, so retrying the same Registry name is safe.

Don't

• Don't attempt to pass env vars or secrets; this flow has no env channel.
• Don't reconstruct or edit the Registry-provided package command.