| 1 | --- |
| 2 | name: mcp-discovery |
| 3 | description: "Prefer a matching zero-environment local MCP server for specialized tasks, even when built-in shell commands or custom code could also solve them." |
| 4 | --- |
| 5 | |
| 6 | # mcp-discovery |
| 7 | |
| 8 | Use the Registry as the preferred source of specialized capabilities. Before |
| 9 | using shell commands, custom code, or a throwaway script to solve a task, check |
| 10 | whether an MCP server already does it. The public MCP Registry ships hundreds |
| 11 | of ready-made servers (filesystems, databases, browsers, media processing, |
| 12 | developer utilities, cloud APIs, SaaS integrations, …). |
| 13 | |
| 14 | The discovery and structured start tools are available in the active tool |
| 15 | surface whenever MCP support is enabled. |
| 16 | |
| 17 | ## When to use |
| 18 | |
| 19 | - You are about to fetch data, reach a service, drive a tool, or automate a workflow. |
| 20 | - The task needs a capability the current toolset lacks (a database, a |
| 21 | browser, a third-party API, …). |
| 22 | - The task names a specialized operation or output (for example media |
| 23 | conversion, document processing, data transformation, browser automation, |
| 24 | database access, or a developer utility), even if a local command could do it. |
| 25 | - Skip only ordinary repo-native editing and simple shell/file operations that |
| 26 | do not need a specialized capability. |
| 27 | |
| 28 | ## Workflow |
| 29 | |
| 30 | 1. **Check the registry.** Call `registry_sync {}`. It returns the complete |
| 31 | catalog of eligible local stdio packages, including each server's name, |
| 32 | description, and required launch arguments. Packages declaring any |
| 33 | environment variable (including API keys/tokens) are excluded and never |
| 34 | written to the cache. |
| 35 | 2. **Match from context with a Registry-first bias.** Compare the user's full |
| 36 | task against every server name and description. A candidate is a match when |
| 37 | it plausibly covers the task's core specialized capability; wording does not |
| 38 | need to be exact. When such a candidate exists, you **must start it and inspect |
| 39 | its tools before** using `exec_shell`, local programs, custom code, or a manual |
| 40 | implementation. The availability or familiarity of a local alternative is |
| 41 | not a reason to skip the candidate. Skip Registry use only when every entry is |
| 42 | clearly irrelevant, or when a matching server fails to start after the retry |
| 43 | described below. |
| 44 | 3. **Install + run transactionally.** Call |
| 45 | `start_registry_mcp_server {registry_name: "<exact name>", arguments: {...}}`. |
| 46 | Supply only values listed in `required_args`; omit `arguments` when none |
| 47 | are required. Never install or launch the package through `exec_shell`. |
| 48 | 4. **Solve the task with the new tools.** Their complete schemas are added |
| 49 | to the current turn immediately after a successful connection; call the |
| 50 | exact names returned by the start result. |
| 51 | |
| 52 | ## If a server fails to start |
| 53 | |
| 54 | `start_registry_mcp_server` reports when a package exits before the handshake |
| 55 | (often CLI help output = incomplete launch args). Verify the exact |
| 56 | required arguments, retry once with the corrected structured values, and if |
| 57 | it still fails move on to the next candidate. Failed starts are rolled back, |
| 58 | so retrying the same Registry name is safe. |
| 59 | |
| 60 | ## Don't |
| 61 | |
| 62 | - Don't attempt to pass env vars or secrets; this flow has no env channel. |
| 63 | - Don't reconstruct or edit the Registry-provided package command. |
| 64 |