| 1 | --- |
| 2 | name: mcp-discovery |
| 3 | description: "Find and start a zero-environment local MCP server when the session lacks a capability that no available tool, project script, or ordinary local code can cover." |
| 4 | --- |
| 5 | |
| 6 | # mcp-discovery |
| 7 | |
| 8 | The public MCP Registry ships hundreds of ready-made stdio servers |
| 9 | (filesystems, databases, browsers, media processing, developer utilities, cloud |
| 10 | APIs, SaaS integrations, …). This skill is how you reach one when the session |
| 11 | is genuinely missing a capability. |
| 12 | |
| 13 | It is a fallback, not a first step. Discovery costs a `tool_search` to load the |
| 14 | deferred tools, a query, an approval, and an install — spend that only when it |
| 15 | buys a capability you do not have. |
| 16 | |
| 17 | ## When to use |
| 18 | |
| 19 | - An available tool, a project script or test, or a few lines of local code |
| 20 | cannot do the job. |
| 21 | - The task needs an external service, database, or protocol client that this |
| 22 | session has no access to. |
| 23 | - You would otherwise install a package or reimplement a well-known converter |
| 24 | or client by hand. |
| 25 | |
| 26 | ## When not to use |
| 27 | |
| 28 | - Ordinary work: writing and editing files, reading fixtures, running repo |
| 29 | commands, and checking your own output. Do those directly. |
| 30 | - A capability an already-loaded tool covers, even partially — try it first. |
| 31 | - A near-miss row in a result list. A scored match is a suggestion; the missing |
| 32 | capability is what decides. |
| 33 | |
| 34 | ## Workflow |
| 35 | |
| 36 | 1. **Name the gap.** State the capability you lack before searching. If you |
| 37 | cannot name one, you do not need the Registry. |
| 38 | 2. **Load and query.** `registry_sync` and `start_registry_mcp_server` are |
| 39 | deferred: load one with `tool_search` and use the returned schema. If a call |
| 40 | only loads the schema without executing, retry once with that schema. Then call |
| 41 | `registry_sync {query: "<the missing capability>"}`. It scores a host-side |
| 42 | snapshot and returns at most eight matches; the full index never enters the |
| 43 | conversation. Packages declaring any environment variable (including API |
| 44 | keys/tokens) are excluded and never written to the cache. |
| 45 | 3. **Judge the matches.** Take a server when it covers the gap you named. If |
| 46 | nothing does, refine the query once, then continue with local tools. |
| 47 | 4. **Install + run transactionally.** Call |
| 48 | `start_registry_mcp_server {registry_name: "<exact name>", arguments: {...}}`. |
| 49 | Supply only values listed in `required_args`; omit `arguments` when none are |
| 50 | required. Never install or launch the package through the shell. Starting a |
| 51 | server requires approval. |
| 52 | 5. **Solve the task with the new tools.** Their complete schemas are added to |
| 53 | the current turn immediately after a successful connection; call the exact |
| 54 | names returned by the start result. |
| 55 | |
| 56 | ## If a server fails to start |
| 57 | |
| 58 | `start_registry_mcp_server` reports when a package exits before the handshake |
| 59 | (often CLI help output = incomplete launch args). Verify the exact required |
| 60 | arguments, retry once with the corrected structured values, and if it still |
| 61 | fails move on to the next candidate or to a local approach. Failed starts are |
| 62 | rolled back, so retrying the same Registry name is safe. |
| 63 | |
| 64 | ## Don't |
| 65 | |
| 66 | - Don't attempt to pass env vars or secrets; this flow has no env channel. |
| 67 | - Don't reconstruct or edit the Registry-provided package command. |
| 68 |