# hf-discover

> Let an agent find the skills and MCP servers it needs at runtime

- Category: Agents & Automation / Agent Skills & Plugins
- Language: Python
- Licence: MIT
- Repository: https://github.com/huggingface/hf-discover
- Canonical page: https://ai-tldr.dev/tools/hf-discover/
- Updated: 2026-06-17

## In short

hf-discover is Hugging Face's implementation of Agentic Resource Discovery (ARD), the open specification for how an agent looks up the resources it needs — Skills, MCP servers and other endpoints — instead of having them hard-wired at configuration time. It sits in the Agent Skills & Plugins category of the Agents & Automation tools and is open-source, written in Python and licensed MIT.

## Overview

hf-discover is Hugging Face's implementation of Agentic Resource Discovery (ARD), the open specification for how an agent looks up the resources it needs — Skills, MCP servers and other endpoints — instead of having them hard-wired at configuration time. The repository ships both halves: a client you run as a `hf` CLI extension, and a server that exposes an ARD catalog over HTTP.

It works in two modes. Search queries a single catalog directly, running semantic search over indexed Skills and Hugging Face Spaces. Navigate does federated discovery: it fetches `/.well-known/ai-catalog.json` from a site, follows the registries that document links to within a depth limit, and merges the ranked results. That is the part that makes discovery decentralised — any site can publish a catalog and be found without registering anywhere central.

The server side implements the ARD v0.5 envelope: `POST /search` returns catalog entries typed by media type (`application/ai-skill`, `application/mcp-server-card+json`, `application/vnd.huggingface.space+json`), with domain-anchored `urn:air:` identifiers, alongside endpoints that serve a Space's `SKILL.md` or MCP `server.json`. A hosted instance runs as a Hugging Face Space from a reproducible Docker definition. The project is MIT-licensed and needs Python 3.10 or newer.

## What it does

- Client and server for the Agentic Resource Discovery v0.5 specification
- Search mode: semantic search over one catalog of Skills and Hugging Face Spaces
- Navigate mode: federated discovery that follows `/.well-known/ai-catalog.json` across registries with a depth limit
- Typed catalog entries for AI Skills, MCP server cards and Space descriptors, with `urn:air:` identifiers
- Installs as an extension of the `hf` CLI, or runs standalone as `hf-discover`
- Ships a Docker Space definition for hosting your own catalog endpoint

## Getting started

The recommended install adds hf-discover as an extension to the Hugging Face CLI, which then exposes the `hf discover` subcommand.

1. Install

   Install the CLI, then the extension, then check it registered.

```bash
uv tool install -U huggingface_hub
hf extensions install huggingface/hf-discover
hf discover --version
```

2. Search a catalog

   Filter by resource kind, ask for JSON when you are piping into an agent, or point at a different registry.

```bash
hf discover search "generate image" --limit 5
hf discover search "transcribe some audio" --kind mcp --json
hf discover search --registry-url https://registry.example "generate image"
```

3. Navigate, or serve your own catalog

   `navigate` follows catalogs across sites; `serve` runs the ARD server locally.

```bash
hf discover navigate "segment hockey players in an image"
hf discover navigate https://huggingface.co "help me set up an RL environment"
hf discover serve --port 8080
```

## When to use it

- Let an agent look up a Skill or MCP server mid-task instead of shipping a fixed tool list
- Publish your own site's tools as an ARD catalog that other agents can find
- Run a private registry of internal Skills and MCP servers behind the same API
- Explore what a domain exposes to agents before wiring anything up

## Version history

- 2026-06-17: Hugging Face, Microsoft, Google and GoDaddy announced Agentic Resource Discovery — an open spec defining an ai-catalog.json manifest and a POST /search registry API — with hf-discover as the reference client and server.
