From 48d4d7034f5b7f490c31a43a027a7fc2440b7f84 Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Fri, 19 Sep 2025 18:43:12 +0200 Subject: [PATCH 1/9] [Documentation] HF MCP Server --- docs/hub/agents.md | 6 ++-- docs/hub/hf-mcp-server.md | 65 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 3 deletions(-) create mode 100644 docs/hub/hf-mcp-server.md diff --git a/docs/hub/agents.md b/docs/hub/agents.md index e49aaaffd..d5b6cafa2 100644 --- a/docs/hub/agents.md +++ b/docs/hub/agents.md @@ -1,7 +1,7 @@ # Agents on the Hub This page compiles all the libraries and tools Hugging Face offers for agentic workflows: -- `HF MCP Server`: Connect your MCP-compatible AI assistant directly to the Hugging Face Hub. +- [HF MCP Server](./hf-mcp-server): Connect your MCP-compatible AI assistant directly to the Hugging Face Hub. - `tiny-agents`: A lightweight toolkit for MCP-powered agents, available in both JS (`@huggingface/tiny-agents`) and Python (`huggingface_hub`). - `Gradio MCP Server`: Easily create MCP servers from Gradio apps and Spaces. - `smolagents`: a Python library that enables you to run powerful agents in a few lines of code. @@ -16,7 +16,7 @@ With the HF MCP Server, you can enhance your AI assistant's capabilities by conn #### Getting Started -Visit [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp) to configure your MCP client and get started. +Visit [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp) to configure your MCP client and get started. Read the dedicated one‑page guide: [HF MCP Server](./hf-mcp-server). @@ -234,4 +234,4 @@ with MCPClient(server_parameters) as tools: agent.run("Please find the latest research on COVID-19 treatment.") ``` -Learn more [in the documentation](https://huggingface.co/docs/smolagents/tutorials/tools#use-mcp-tools-with-mcpclient-directly). \ No newline at end of file +Learn more [in the documentation](https://huggingface.co/docs/smolagents/tutorials/tools#use-mcp-tools-with-mcpclient-directly). diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md new file mode 100644 index 000000000..8093730b6 --- /dev/null +++ b/docs/hub/hf-mcp-server.md @@ -0,0 +1,65 @@ +# HF MCP Server + +The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor. + + +This feature is experimental and will continue to evolve. + + +## What you can do + +- Search and explore Hub resources: models, datasets, Spaces, and papers +- Run community tools via MCP‑compatible Gradio apps hosted on Spaces +- Bring results back into your assistant with metadata, links, and context + +## Get started + +1) Open your MCP settings: visit https://huggingface.co/settings/mcp while logged in. + +2) Pick your client: select your MCP‑compatible client (for example Cursor, VS Code, Zed, Claude Desktop). The page shows client‑specific instructions and a ready‑to‑copy configuration snippet. + +3) Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client. + + +The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. + + +## Using the server + +After connecting, ask your assistant to use the Hugging Face tools. Example prompts: + +- “Search Hugging Face models for Llama‑3.1 fine‑tunes for summarization.” +- “Find a Space that can transcribe audio files.” +- “Show datasets about weather time‑series.” +- “Look up papers on diffusion transformers and list recent ones.” + +Your assistant will call MCP tools exposed by the HF MCP Server and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. + +## Add community tools (Gradio MCP) + +You can extend your setup with MCP‑compatible Gradio apps built by the community: + +- Explore Spaces with MCP support: https://huggingface.co/spaces?filter=mcp-server +- Follow your client’s instructions to add an additional MCP server by URL, or use the prompts in https://huggingface.co/settings/mcp if available in your client’s card. + +Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. + +## Security and permissions + +- Scoped access: the server uses your authenticated Hugging Face account to access Hub resources. You can review or revoke access anytime from your Hugging Face settings. +- Least surprise: tools only perform actions you prompt them to do in your assistant; browsing and lookups are read‑only. +- Privacy: results returned to your client are based on your account’s visibility and permissions (for example, private org content remains private). + +## Troubleshooting + +- Not showing up in client: re‑open https://huggingface.co/settings/mcp and re‑copy the configuration for your specific client, then restart the client. +- Auth or 401/403 errors: ensure you are signed in on the Hugging Face website in the same browser/profile you used to open the settings page; if your client supports tokens, update them and try again. +- Enterprise network issues: some clients use Server‑Sent Events (SSE) or websockets—ensure your network/proxy allows these connections. + +## Learn more + +- Settings and client setup: https://huggingface.co/settings/mcp +- Changelog announcement: https://huggingface.co/changelog/hf-mcp-server +- Agents on the Hub overview: ./agents +- MCP spec and ecosystem: https://github.com/modelcontextprotocol/spec + From 615fe3078201606de8d1fb6bcd799b1655cd23ce Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Fri, 19 Sep 2025 18:58:45 +0200 Subject: [PATCH 2/9] up. --- docs/hub/hf-mcp-server.md | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index 8093730b6..442cae5d3 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -1,24 +1,20 @@ -# HF MCP Server +# Hugging Face MCP Server -The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor. - - -This feature is experimental and will continue to evolve. - +The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor. ## What you can do - Search and explore Hub resources: models, datasets, Spaces, and papers -- Run community tools via MCP‑compatible Gradio apps hosted on Spaces +- Run community tools via MCP‑compatible Gradio apps hosted on [Spaces](https://hf.co/spaces) - Bring results back into your assistant with metadata, links, and context ## Get started -1) Open your MCP settings: visit https://huggingface.co/settings/mcp while logged in. +1. Open your MCP settings: visit https://huggingface.co/settings/mcp while logged in. -2) Pick your client: select your MCP‑compatible client (for example Cursor, VS Code, Zed, Claude Desktop). The page shows client‑specific instructions and a ready‑to‑copy configuration snippet. +2. Pick your client: select your MCP‑compatible client (for example Cursor, VS Code, Zed, Claude Desktop). The page shows client‑specific instructions and a ready‑to‑copy configuration snippet. -3) Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client. +3. Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client. The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. @@ -28,19 +24,19 @@ The settings page generates the exact configuration your client expects. Use it After connecting, ask your assistant to use the Hugging Face tools. Example prompts: -- “Search Hugging Face models for Llama‑3.1 fine‑tunes for summarization.” +- “Search Hugging Face models for Qwen 3 Quantizatizations.” - “Find a Space that can transcribe audio files.” - “Show datasets about weather time‑series.” -- “Look up papers on diffusion transformers and list recent ones.” +- “Create a 1024 x 1024 image of a dof anime style.” -Your assistant will call MCP tools exposed by the HF MCP Server and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. +Your assistant will call MCP tools exposed by the HF MCP Server (including HF spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. ## Add community tools (Gradio MCP) You can extend your setup with MCP‑compatible Gradio apps built by the community: -- Explore Spaces with MCP support: https://huggingface.co/spaces?filter=mcp-server -- Follow your client’s instructions to add an additional MCP server by URL, or use the prompts in https://huggingface.co/settings/mcp if available in your client’s card. +- Explore Spaces with MCP support [here](https://huggingface.co/spaces?filter=mcp-server). +- Add the relevant space in your MCP settings on Hugging Face [here](https://huggingface.co/settings/mcp). Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. @@ -50,16 +46,9 @@ Gradio MCP apps expose their functions as tools (with arguments and descriptions - Least surprise: tools only perform actions you prompt them to do in your assistant; browsing and lookups are read‑only. - Privacy: results returned to your client are based on your account’s visibility and permissions (for example, private org content remains private). -## Troubleshooting - -- Not showing up in client: re‑open https://huggingface.co/settings/mcp and re‑copy the configuration for your specific client, then restart the client. -- Auth or 401/403 errors: ensure you are signed in on the Hugging Face website in the same browser/profile you used to open the settings page; if your client supports tokens, update them and try again. -- Enterprise network issues: some clients use Server‑Sent Events (SSE) or websockets—ensure your network/proxy allows these connections. - ## Learn more - Settings and client setup: https://huggingface.co/settings/mcp - Changelog announcement: https://huggingface.co/changelog/hf-mcp-server -- Agents on the Hub overview: ./agents -- MCP spec and ecosystem: https://github.com/modelcontextprotocol/spec +- Agents on the Hub overview: From 86e52bc0e250e4f30af21776536be378a682a137 Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Fri, 19 Sep 2025 19:10:16 +0200 Subject: [PATCH 3/9] reorganise + add images. --- docs/hub/_toctree.yml | 2 ++ docs/hub/hf-mcp-server.md | 10 +++++++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml index 437aa6184..6efbea911 100644 --- a/docs/hub/_toctree.yml +++ b/docs/hub/_toctree.yml @@ -436,6 +436,8 @@ title: "JFrog" - local: agents title: Agents on Hub + - local: hf-mcp-server + title: Hugging Face MCP Server - local: moderation title: Moderation - local: paper-pages diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index 442cae5d3..36a506b70 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -20,6 +20,8 @@ The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compati The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. +![MCP Settings Example](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hf-mcp-settings.png) + ## Using the server After connecting, ask your assistant to use the Hugging Face tools. Example prompts: @@ -31,9 +33,11 @@ After connecting, ask your assistant to use the Hugging Face tools. Example prom Your assistant will call MCP tools exposed by the HF MCP Server (including HF spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. -## Add community tools (Gradio MCP) +![HF MCP with Spaces in VS Code](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hf-mcp-vscode.png) + +## Add community tools (Spaces) -You can extend your setup with MCP‑compatible Gradio apps built by the community: +You can extend your setup with MCP‑compatible Gradio spaces built by the community: - Explore Spaces with MCP support [here](https://huggingface.co/spaces?filter=mcp-server). - Add the relevant space in your MCP settings on Hugging Face [here](https://huggingface.co/settings/mcp). @@ -50,5 +54,5 @@ Gradio MCP apps expose their functions as tools (with arguments and descriptions - Settings and client setup: https://huggingface.co/settings/mcp - Changelog announcement: https://huggingface.co/changelog/hf-mcp-server -- Agents on the Hub overview: +- HF MCP Server: https://huggingface.co/mcp From f5fa5a8f62230d110f53aa93d33771d958294160 Mon Sep 17 00:00:00 2001 From: vb Date: Fri, 19 Sep 2025 19:31:01 +0200 Subject: [PATCH 4/9] Apply suggestions from code review Co-authored-by: burtenshaw --- docs/hub/hf-mcp-server.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index 36a506b70..dafb497cd 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -1,6 +1,6 @@ # Hugging Face MCP Server -The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor. +The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor or chat. ## What you can do @@ -17,7 +17,9 @@ The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compati 3. Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client. + The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. + ![MCP Settings Example](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hf-mcp-settings.png) From f7ba29a7a34ca194401a07c8e8f7ee789c2b7a6e Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Fri, 19 Sep 2025 19:34:16 +0200 Subject: [PATCH 5/9] review. --- docs/hub/hf-mcp-server.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index dafb497cd..6094190f5 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -57,4 +57,5 @@ Gradio MCP apps expose their functions as tools (with arguments and descriptions - Settings and client setup: https://huggingface.co/settings/mcp - Changelog announcement: https://huggingface.co/changelog/hf-mcp-server - HF MCP Server: https://huggingface.co/mcp +- Build your own MCP Server with Gradio Spaces: https://www.gradio.app/guides/building-mcp-server-with-gradio From 8e9cd8bcb1c708a6e083381e410e3eb86c8b284e Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Sat, 20 Sep 2025 12:02:19 +0200 Subject: [PATCH 6/9] review + last edits. --- docs/hub/hf-mcp-server.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index 6094190f5..6215f3d4f 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -31,7 +31,7 @@ After connecting, ask your assistant to use the Hugging Face tools. Example prom - “Search Hugging Face models for Qwen 3 Quantizatizations.” - “Find a Space that can transcribe audio files.” - “Show datasets about weather time‑series.” -- “Create a 1024 x 1024 image of a dof anime style.” +- “Create a 1024 x 1024 image of a cat anime style.” Your assistant will call MCP tools exposed by the HF MCP Server (including HF spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. @@ -46,16 +46,10 @@ You can extend your setup with MCP‑compatible Gradio spaces built by the commu Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. -## Security and permissions - -- Scoped access: the server uses your authenticated Hugging Face account to access Hub resources. You can review or revoke access anytime from your Hugging Face settings. -- Least surprise: tools only perform actions you prompt them to do in your assistant; browsing and lookups are read‑only. -- Privacy: results returned to your client are based on your account’s visibility and permissions (for example, private org content remains private). - ## Learn more - Settings and client setup: https://huggingface.co/settings/mcp - Changelog announcement: https://huggingface.co/changelog/hf-mcp-server -- HF MCP Server: https://huggingface.co/mcp +- Hugging Face MCP Server: https://huggingface.co/mcp - Build your own MCP Server with Gradio Spaces: https://www.gradio.app/guides/building-mcp-server-with-gradio From dc6f489e85034e63e7bee9b3bfa643ca1e5ff8bc Mon Sep 17 00:00:00 2001 From: vb Date: Sat, 20 Sep 2025 12:07:02 +0200 Subject: [PATCH 7/9] Update docs/hub/hf-mcp-server.md Co-authored-by: Pedro Cuenca --- docs/hub/hf-mcp-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index 6215f3d4f..ec34c2acc 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -44,7 +44,7 @@ You can extend your setup with MCP‑compatible Gradio spaces built by the commu - Explore Spaces with MCP support [here](https://huggingface.co/spaces?filter=mcp-server). - Add the relevant space in your MCP settings on Hugging Face [here](https://huggingface.co/settings/mcp). -Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. +Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. Please, restart or refresh your client so it picks up new tools you select. ## Learn more From 5dae7289af14afa9d9d3e0c16a46cd40715bc9e7 Mon Sep 17 00:00:00 2001 From: Vaibhavs10 Date: Sat, 20 Sep 2025 12:10:43 +0200 Subject: [PATCH 8/9] last edits. --- docs/hub/hf-mcp-server.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index ec34c2acc..bc1a3a35b 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -1,12 +1,12 @@ # Hugging Face MCP Server -The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor or chat. +The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example Codex, Cursor, VS Code extensions, Zed, ChatGPT or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor, chat or CLI. ## What you can do -- Search and explore Hub resources: models, datasets, Spaces, and papers -- Run community tools via MCP‑compatible Gradio apps hosted on [Spaces](https://hf.co/spaces) -- Bring results back into your assistant with metadata, links, and context +- Search and explore Hub resources: models, datasets, Spaces, and papers. +- Run community tools via MCP‑compatible Gradio apps hosted on [Spaces](https://hf.co/spaces). +- Bring results back into your assistant with metadata, links, and context. ## Get started @@ -33,7 +33,7 @@ After connecting, ask your assistant to use the Hugging Face tools. Example prom - “Show datasets about weather time‑series.” - “Create a 1024 x 1024 image of a cat anime style.” -Your assistant will call MCP tools exposed by the HF MCP Server (including HF spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. +Your assistant will call MCP tools exposed by the Hugging Face MCP Server (including Spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat. ![HF MCP with Spaces in VS Code](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hf-mcp-vscode.png) @@ -44,7 +44,7 @@ You can extend your setup with MCP‑compatible Gradio spaces built by the commu - Explore Spaces with MCP support [here](https://huggingface.co/spaces?filter=mcp-server). - Add the relevant space in your MCP settings on Hugging Face [here](https://huggingface.co/settings/mcp). -Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. Please, restart or refresh your client so it picks up new tools you select. +Gradio MCP apps expose their functions as tools (with arguments and descriptions) so your assistant can call them directly. Please, restart or refresh your client so it picks up new tools you add. ## Learn more From 043a9d84fd01e3887b8b9192a32ffac9aa08912f Mon Sep 17 00:00:00 2001 From: vb Date: Sat, 20 Sep 2025 21:03:37 +0200 Subject: [PATCH 9/9] Update docs/hub/hf-mcp-server.md --- docs/hub/hf-mcp-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/hf-mcp-server.md b/docs/hub/hf-mcp-server.md index bc1a3a35b..4d68f8c94 100644 --- a/docs/hub/hf-mcp-server.md +++ b/docs/hub/hf-mcp-server.md @@ -31,7 +31,7 @@ After connecting, ask your assistant to use the Hugging Face tools. Example prom - “Search Hugging Face models for Qwen 3 Quantizatizations.” - “Find a Space that can transcribe audio files.” - “Show datasets about weather time‑series.” -- “Create a 1024 x 1024 image of a cat anime style.” +- “Create a 1024 x 1024 image of a cat ghibli style.” Your assistant will call MCP tools exposed by the Hugging Face MCP Server (including Spaces) and return results (titles, owners, downloads, links, and so on). You can then open the resource on the Hub or continue iterating in the same chat.