On this page
The Hugging Face MCP server is Hugging Face's official hosted server at
https://huggingface.co/mcp. It lets your agent search the Hub and call Gradio
Spaces as tools. TrustedMCP grades it A. Connect with a read-only token if
you only need search, and add Spaces sparingly.
What it connects
Hugging Face's MCP server docs say the server lets your assistant:
- search and explore Hub models, datasets, Spaces and papers,
- search the Hugging Face documentation in natural language,
- schedule and run Jobs and use sandboxes,
- run community tools through MCP-compatible Gradio apps hosted on Spaces.
Most Hub tasks go through one built-in tool, hf_fs. Extra tools are opt-in.
The code is open source (MIT) in the
hf-mcp-server repo, and you can
also run it yourself over stdio or HTTP, but most people use the hosted
endpoint.
Setup
These snippets come from the hf-mcp-server README.
Claude Code (sign-in flow):
claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login
Then start claude and follow the instructions to complete authentication.
Claude Code (Hugging Face token):
claude mcp add hf-mcp-server \
-t http https://huggingface.co/mcp \
-H "Authorization: Bearer <YOUR_HF_TOKEN>"
Don't type a real token into a command you'll keep in shell history. See keeping API keys out of your MCP config.
Gemini CLI:
gemini mcp add -t http huggingface https://huggingface.co/mcp?login
Other clients. The README documents a Claude Desktop and claude.ai connector
(add "Hugging Face" from the gallery at claude.ai/settings/connectors), plus
one-click installs for VS Code and Cursor. For a manual VS Code or Cursor
setup, the README adds a huggingface entry with "url": "https://huggingface.co/mcp" and an Authorization: Bearer header to your MCP
config. The docs also say the MCP settings page
generates the exact config for your client, and recommend using it rather than
writing config by hand.
Add ?no_image_content=true to the URL if you want to drop the image blocks
that Gradio Spaces return.
Anonymous, OAuth or token?
The hosted endpoint accepts three kinds of connection:
| Connection | How | What you get |
|---|---|---|
| Anonymous | https://huggingface.co/mcp with no header |
The README says token-less requests "continue with the anonymous tool set" |
| OAuth | https://huggingface.co/mcp?login |
Your client signs you in through Hugging Face in the browser |
| HF token | Authorization: Bearer <YOUR_HF_TOKEN> header |
Access set by the token you create |
Tools that create repositories, run Jobs, call Spaces dynamically or use sandboxes require you to be signed in. For a general look at these options, see MCP authentication explained.
What OAuth asks for. The server's OAuth metadata
(/.well-known/oauth-protected-resource/mcp) advertises these scopes:
openid, profile, read-mcp, read-repos, jobs, contribute-repos and
inference-api. The project's own OAuth diagnostics doc describes the full
set as identity, job, repository-write and inference scopes, and its test tool
narrows the request to read-mcp on purpose. So a client that signs in with
the advertised set asks for permission to run Jobs, write repos and use
inference on your account, not only to read.
Use a read-only token if you only search. Hugging Face's
token docs describe a read
role that "can only be used to provide read access to repositories you could
read", and fine-grained tokens limited to specific resources. They also
recommend one token per app. Create a dedicated read or fine-grained token for
MCP, pass it in the header, and revoke it without touching your other tools.
Choosing tools and Spaces
After you connect, go to huggingface.co/settings/mcp. There you choose which extra tools are on and which Spaces your agent can call. The docs list these optional tools:
- Contribute Repos: create repos and write files to them.
- Sandboxes: create and use sandboxes, including file management.
- Run and Manage Jobs: run, monitor and schedule jobs on Hugging Face infrastructure.
The settings page also has Dynamic Spaces, which lets the assistant "discover and use MCP-compatible Spaces on-the-fly without adding them manually", and an option to remove embedded images. Restart or refresh your client after you change tools.
Every Space you add brings its own tools and descriptions into the model's context. A handful is fine; dozens add up. See how MCP tools eat your context.
Security notes
Spaces are third-party apps. A Gradio Space is code written by whoever owns it, and the server sends its output straight to your model. A Space can return wrong results, or text that tries to steer your agent (prompt injection). Add Spaces from owners you trust, and think twice before you turn on Dynamic Spaces, since it lets the model pick Spaces you never reviewed.
Jobs and sandboxes run code on your account. With these tools on, the model can start compute on Hugging Face infrastructure under your account. Leave them off unless you need them, and keep tool approval on so you see each call.
Repo writes are real writes. Contribute Repos can create repositories and push files. If your token or OAuth grant includes write access, an injected instruction could use it.
The 5-minute safety check covers the general process for any server.
Why it grades A
It's first-party, open source, very active, and hosted over HTTPS, with no advisories on record. You also get real control: scoped OAuth or a token you choose, and a settings page that switches tools and Spaces on or off.
The biggest deduction is authentication. It's optional, since the bare endpoint works anonymously, and the default OAuth sign-in asks for Jobs, repo-write and inference scopes on top of read. A read-only or fine-grained token closes most of that gap, but we grade the default setup.
Full details on the Hugging Face MCP listing; the method is in how TrustedMCP scores servers.
Frequently asked questions
What's the Hugging Face MCP URL?
https://huggingface.co/mcp. Add ?login to start the sign-in flow, or send
an Authorization: Bearer header with a Hugging Face token.
Is there a Hugging Face MCP course?
Yes. Hugging Face publishes a free MCP course on its Learn site, built with Anthropic. It covers MCP fundamentals and architecture, then an end-to-end build: a Gradio-based MCP server deployed to Spaces, with clients in Python and TypeScript. It offers two free certificates, or you can audit it. It assumes basic LLM knowledge and some Python or TypeScript.
The course teaches you how MCP works and how to build your own server. The Hugging Face MCP server is a ready-made server you connect to so your agent can use the Hub. You don't need the course to use the server.
Is the Hugging Face MCP server free?
The server is open source and the hosted endpoint works without an account for the anonymous tool set. Jobs, inference and Spaces use your Hugging Face account, so check your account's limits and billing for those.
Can I use it without signing in?
Yes, for the anonymous tool set. Repo creation, Jobs, dynamic Spaces and sandboxes need authentication.
Can I run it locally?
Yes. The README covers stdio and HTTP transports and a Docker image. Locally,
the stdio server reads DEFAULT_HF_TOKEN (or HF_TOKEN).