Your agent needs to read and act on Hugging Face. Hugging Face ships two ways in: an official MCP server at huggingface.co/mcp and the Hub REST API your training and deployment code already calls. They are not the same object. Different capability coverage, different (though overlapping) auth, different operational surface in production. Here is how to pick, and the one problem you own either way.
Two objects, one platform. You have almost certainly used the API. You may not have wired up the MCP server.
Hugging Face maintains an official, open-source MCP server, announced in June 2025. It is hosted (remote) at huggingface.co/mcp over Streamable HTTP, and it also runs locally over STDIO if you self-host. It is built for LLM consumption: a consolidated hf_fs filesystem tool over hf:// URIs, plus search tools across the Hub. The tool surface is configurable per user from the MCP settings page and is explicitly experimental, so it changes as Hugging Face ships updates. Auth is Sign in with Hugging Face OAuth (via a login flow) or a Hugging Face user access token passed as Authorization: Bearer. Full detail lives in Hugging Face's official MCP server documentation.
"The API" here means two programmatic surfaces. The Hub REST API (base huggingface.co, under /api) exposes models, datasets, Spaces, repositories, files and commits, discussions and pull requests, org and member management, resource groups, and webhooks. Inference Providers exposes a separate OpenAI-compatible router at router.huggingface.co/v1 for running models. Auth is User Access Tokens (fine-grained, read, write) sent as Bearer, plus OAuth and Enterprise service accounts. Official client libraries wrap it: huggingface_hub for Python, @huggingface/hub and @huggingface/inference for JavaScript. The endpoint reference is the Hugging Face Hub API documentation.
Four axes decide this: what your agent can do, the auth path each puts you on, what you operate in production, and when each one wins.
The MCP server is a discovery and community-tools surface. The API is the management and inference surface.
Anything that writes to the Hub at volume, automates discussions and pull requests, manages an org, or serves model inference through the router lives in the API. Those are not missing MCP tools shipping next month; repository write depth, admin endpoints, and the inference router are architectural features of the API. The reverse gap is real too. Calling an arbitrary community Gradio Space as a typed tool, or running semantic documentation search, is an MCP convenience the raw REST API does not hand you.
Here is the Hugging Face twist most comparisons miss: both paths draw on the same credential system.
The failure mode is not bot identity, the way it is on some other platforms. On Hugging Face it is the shared org service account. A service account is one credential shared across every user, and service accounts are usually provisioned with admin-level scope for convenience. Point your agent at one and every user gets identical, over-broad access, cross-tenant reach becomes possible, and the audit trail shows the service account rather than the person who triggered the action. A per-user token inverts that: the agent inherits exactly what that user authorized.
Both paths require per-user credential isolation in a multi-tenant B2B agent. OAuth gives you a token per user; a user access token is a credential per user. Neither path stores, rotates, or revokes those for you. Because both draw on the same Hugging Face token system, choosing MCP or the API barely changes the token type; it does not change the isolation problem at all. This is where infrastructure, not the path, decides whether the agent is production-safe. The broader tradeoffs of this decision are explored in How Tool Calling Auth Changes When You Move from Single-Tenant to Multi-Tenant.
Hugging Face manages the server, the tool schemas, and the hf_fs surface. You own per-user token storage, refresh, revocation, and tenant isolation. You also inherit surface drift: the tool set is experimental and configurable per user, so what a given user's client sees is not guaranteed stable release to release.
You own the full surface: schema, pagination, error handling, token lifecycle, and rate limits. Hub API rate limits are tier-based, signaled by HTTP 429 with a RateLimit header; the huggingface_hub client retries on that header, but a raw HTTP integration is yours to back off correctly. High-volume Hub operations need explicit pagination and retry logic that the MCP path abstracts away.
The two surfaces age differently. The MCP tool surface is explicitly evolving, so treat it as a moving contract and pin behavior where you can. The Hub REST API is comparatively stable, which is exactly why deterministic pipelines prefer it. Pick based on how much contract stability the agent needs to keep working unattended.
MCP wins when a user is present and the work is discovery, not deterministic writes. These are Hugging Face specific, not generic MCP advice.
The API wins for headless, high-volume, or admin work the MCP server does not cover.
Both paths give you a token or credential per user. Neither gives you a vault, rotation logic, or a revocation flow. That infrastructure is built separately, whichever path you chose. Understanding why static credentials break at scale is covered in depth in OAuth vs API Keys for AI Agents: Why Static Credentials Break in Production Systems.
In a multi-tenant Hugging Face agent, which is the B2B default rather than the exception, every user has their own Hugging Face credential. That is N connected accounts to store, refresh, and revoke at scale. Offboarding is the sharp edge: the Okta account gets disabled, but a fine-grained token minted eight months ago and stored locally is still valid. The agent does not decide to keep using it. It just does.
A shared org service account looks correct in a demo. In production it hands every user the same access, and because service accounts skew admin-scoped, that access is usually broader than any individual should have. Attribution collapses: the audit trail shows the service account, not the person, and one credential now reaches across tenants. Shared credentials are a single-user solution; they do not survive a second user. The patterns of credential ownership across agent tool-calling patterns explain exactly why this breaks at scale.
Scalekit's Hugging Face connector handles the OAuth flow, token storage, and rotation for the path you choose, so the MCP vs API decision does not change your auth infrastructure. It resolves the per-user connected account on every tool call, and credentials never touch the agent runtime. The same model is covered in more depth in OAuth vs API keys for AI agents and handling token refresh for long-running agents.
Scalekit ships a Hugging Face MCP connector that wraps the official server and solves the per-user auth the raw paths leave to you. It exposes the Hub as prebuilt tools with LLM-ready schemas, so the team builds the agent, not the tooling. The walkthrough below is Python with LangChain, in discovery, scope, execution order.
Create the connection once in the Scalekit dashboard under AgentKit, Connections, add huggingfacemcp, and confirm the connection name matches character for character. Then generate a per-user authorization link.
Before the agent runs, it does not load a flat connector catalog. It loads the tools the current user's connected account is authorized to call. The LangChain adapter below calls list_scoped_tools under the hood, returns them as LangChain StructuredTool objects, and binds each one to that user's connected account. Scope is a function of identity: what the user cannot do, the agent cannot do. For a deeper look at why this matters, see LangChain Tool Calling: How It Works, Where It Stops, and How Scalekit Completes It.
The tools are standard LangChain tools, so they drop into any agent constructor. The loop below is shown in full: model, prompt, agent, executor, invocation.
For deterministic steps, skip the model and execute one tool. Use the exact tool name from the connector's tool list; if unsure, list the scoped tools for the user first.
The connector surfaces eleven tools. The stable core covers discovery and retrieval: huggingfacemcp_hf_fs for filesystem-style navigation and search over hf:// URIs, huggingfacemcp_hub_repo_search and huggingfacemcp_hub_repo_details for repositories, huggingfacemcp_paper_search, huggingfacemcp_space_search, huggingfacemcp_hf_doc_search, huggingfacemcp_hf_doc_fetch, huggingfacemcp_hf_hub_query, and huggingfacemcp_hf_whoami. huggingfacemcp_dynamic_space calls community Gradio Spaces as tools, including inference apps such as image generation. This is a discovery and Spaces surface; it does not expose Jobs, sandboxes, or repository writes. The full schema per tool is on the connector docs page, and you can browse every connector in the AgentKit connector directory.
The connector solves auth. Three further properties matter once the agent is multi-tool and multi-tenant.
The Hugging Face MCP surface is dynamic and grows as users add community Spaces, so a naive setup can hand the model a large, shifting tool list. That is an accuracy problem and a cost problem: LLMs select the wrong tool from a bloated surface, and 40 tools at roughly 200 tokens each burn 8,000 tokens before the agent does any work. list_scoped_tools returns only the tools the current user is authorized to call, often 5 to 10. The fix is not better prompting. It is surface reduction — the same principle behind agent tool calling auth production patterns.
Every tool call runs through a per-user connected account, and every call is logged with the identity it acted as. When a security reviewer asks under whose credentials the agent searched the Hub or invoked a Space, the answer is a real user, not a shared service account. That observability is the difference between an answerable audit and a shrug; the pattern is detailed in Agent Tool Observability: Your Agent Is Running. Is It Actually Working?
A standard MCP server exposes every tool it has. A research agent needs huggingfacemcp_hub_repo_search, huggingfacemcp_paper_search, and huggingfacemcp_hf_fs, not the full surface. Scalekit Virtual MCP Servers enforce least privilege at the tool level: the agent sees only what you explicitly allow. One server definition serves all users, and a short-lived session token scoped to that user's connected accounts is minted before each run. The endpoint is static; the identity is per-user. There is no MCP server to deploy, host, or maintain — as explored in secure token management for AI agents at scale.
If your agent is interactive and discovery-heavy, browsing the Hub, searching papers, and calling Spaces in natural language, build on the MCP server; it is the faster route and the tool surface is expanding. If your agent runs headless, writes to the Hub, serves inference through the router, or touches org and admin surfaces the MCP server does not expose, build against the Hub REST API directly. On Hugging Face the two paths share a token system, so the credential management problem is identical either way. That is the part that needs production-grade infrastructure, and it is the part that decides whether the agent survives a second tenant.
Browse the Scalekit Hugging Face connector in the docs and on the connector page. To see per-user tool calling in a full build, start from the Scalekit agent templates, and compare plans on the pricing page.
Building a Hugging Face agent now and want a second pair of eyes on the auth model? Join the Scalekit Slack community, or use the Talk to us page for immediate help.
Recommended reading: single vs multi-tenant tool calling, agent tool-calling observability, and secure token management for AI agents.
