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.