HuggingFace MCP Architecture
The HuggingFace MCP server provides AI agents with direct access to the Hugging Face Hub — the largest open-source ML model registry. It exposes 16 MCP tools and 4 prompts that enable searching, inspecting, and interacting with models, datasets, Spaces, papers, and documentation hosted on Hugging Face.
Built by evalstate / LLMindset and adopted
as the official Hugging Face MCP server, this Node.js application supports stdio,
Streamable HTTP, and SSE transports. On rod-server it runs as a pre-built Docker
container using Streamable HTTP transport on port 3000 within the hosting_web
Docker network.
No local source code. This is a pre-built container image
(
ghcr.io/evalstate/hf-mcp-server:latest). The architecture below is
derived from container inspection and in-container file analysis.
Tools
16
Prompts
4
Transport
Streamable HTTP
Runtime
Node.js 22
Version
0.3.5
Image Built
2026-03-20
2. Runtime Architecture
Diagram A: Runtime Request Flow
Request Flow
- An MCP client (Claude Code, Claude.ai, VSCode) sends a tool call request via Streamable HTTP to port 3000.
- The HF MCP Server receives the request and dispatches to the appropriate tool module from
@llmindset/hf-mcp. - The tool module constructs the appropriate API call to the HuggingFace Hub API, Gradio Space endpoint, or documentation search.
- Results are formatted as structured Markdown and returned to the MCP client as tool results.
Transport Modes
| Transport | Env Var | Entry Point | Use Case |
|---|---|---|---|
streamableHttp |
TRANSPORT=streamableHttp |
dist/server/streamableHttp.js |
Docker deployment (current config on rod-server) |
stdio |
TRANSPORT=stdio |
dist/server/stdio.js |
Direct CLI integration (Claude Code native) |
streamableHttpJson |
TRANSPORT=streamableHttpJson |
dist/server/streamableHttp.js --json |
JSON response mode for structured consumers |
5. Public Interfaces (MCP Tools & Prompts)
The server exposes 16 tools and 4 prompts via the MCP protocol. Tools are organized into functional groups.
Search Tools
| Tool ID | Description | Key Parameters |
|---|---|---|
model_search |
Search ML models on HuggingFace Hub. Returns downloads, likes, tags, and direct links. | query, author, task, library, sort, limit |
dataset_search |
Search datasets on HuggingFace Hub with filtering by author and task. | query, author, sort, limit |
space_search |
Semantic search for Spaces (Gradio/Streamlit apps) on HuggingFace. | q, sdk, filter |
repo_search |
General repository search across all HuggingFace repo types. | query, type |
paper_search |
Search ML research papers indexed on HuggingFace. | query, limit |
docs_semantic_search |
Semantic search over HuggingFace documentation. | query |
Detail / Inspection Tools
| Tool ID | Description | Key Parameters |
|---|---|---|
model_detail |
Get detailed information about a specific model including model card, config, and metadata. | model_id |
dataset_detail |
Get detailed information about a specific dataset including card and schema. | dataset_id |
hub_repo_details |
Inspect any HuggingFace repository (model, dataset, or space) for metadata and files. | repo_id, type |
space_info |
Get metadata and runtime status for a HuggingFace Space. | space_id |
space_files |
List files in a HuggingFace Space repository. | space_id |
doc_fetch |
Fetch a specific documentation page from HuggingFace docs. | url |
Action Tools
| Tool ID | Description | Key Parameters |
|---|---|---|
duplicate_space |
Duplicate (fork) an existing HuggingFace Space to your account. | space_id |
use_space |
Invoke a Gradio Space as an API endpoint, sending inputs and receiving outputs. | space_id, inputs |
hf_jobs |
Manage HuggingFace Jobs (serverless inference tasks). | action, job_id |
dynamic_space |
Dynamically interact with Gradio Space APIs by discovering and calling endpoints. | space_id, endpoint |
MCP Prompts
| Prompt ID | Description |
|---|---|
user_summary |
Generate a summary of a HuggingFace user's profile, repos, and contributions. |
paper_summary |
Generate a structured summary of an ML research paper. |
model_detail_prompt |
Provide a detailed model analysis prompt with model card and metadata context. |
dataset_detail_prompt |
Provide a detailed dataset analysis prompt with card and schema context. |
Tool Groups
Tools are organized into logical groups for bouquet configurations:
| Group | Tools |
|---|---|
search | space_search, repo_search, paper_search, docs_semantic_search |
spaces | space_search, duplicate_space, space_info, space_files, use_space |
detail | model_detail, dataset_detail, hub_repo_details |
docs | docs_semantic_search, doc_fetch |
hf_api | space_search, repo_search, paper_search, hub_repo_details, docs_semantic_search |
all | All 16 tools |
6. Internal Structure
The application is a pnpm monorepo with three packages:
| Package | Path | Purpose |
|---|---|---|
@llmindset/hf-mcp |
/app/packages/mcp/ |
Core library: tool definitions, HF API client, Zod schemas, result formatters |
@llmindset/hf-mcp-server |
/app/packages/app/ |
Server application: transport handlers (stdio, streamableHttp), MCP protocol bridge, web server |
e2e-python |
/app/packages/e2e-python/ |
End-to-end Python test suite |
Key Source Files (inside container)
| File | Role |
|---|---|
/app/start.sh | Entrypoint script: selects transport mode and starts Node.js |
/app/packages/app/src/server/mcp-server.ts | MCP server registration: binds tools and prompts |
/app/packages/app/src/server/streamableHttp.ts | Streamable HTTP transport handler |
/app/packages/app/src/server/stdio.ts | stdio transport handler |
/app/packages/mcp/src/tool-ids.ts | Canonical tool ID registry (single source of truth) |
/app/packages/mcp/src/hf-api-call.ts | HuggingFace API HTTP client wrapper |
/app/packages/mcp/src/model-search.ts | Model search tool implementation |
/app/packages/mcp/src/space-search.ts | Space semantic search tool |
/app/packages/mcp/src/use-space.ts | Gradio Space invocation tool |
7. Deployment & Operations
Container Configuration
| Property | Value |
|---|---|
| Image | ghcr.io/evalstate/hf-mcp-server:latest |
| Container Name | huggingface-mcp |
| Compose File | /home/rod/_rod/_mcp-tools/docker-compose.yml |
| Network | hosting_web |
| Internal Port | 3000 |
| Restart Policy | unless-stopped |
| Traefik | Disabled (no public routing) |
| Node.js | v22.22.0 |
| Package Manager | pnpm 10.29.2 |
Environment Variables
| Variable | Value / Source | Purpose |
|---|---|---|
DEFAULT_HF_TOKEN |
${HF_TOKEN} from .env |
Default HuggingFace API token for authenticated requests. Enables access to gated models and higher rate limits. |
TRANSPORT |
streamableHttp |
Transport protocol. Options: stdio, streamableHttp, streamableHttpJson |
PORT |
3000 |
HTTP listener port |
Operations
# Check container status docker ps --filter name=huggingface-mcp # View logs docker logs -f huggingface-mcp # Restart cd /home/rod/_rod/_mcp-tools && docker compose restart huggingface-mcp # Update to latest image cd /home/rod/_rod/_mcp-tools && docker compose pull huggingface-mcp && docker compose up -d huggingface-mcp # Test MCP endpoint (from within Docker network) curl -s http://huggingface-mcp:3000/mcp # Peek inside container docker exec huggingface-mcp ls /app/packages/mcp/src/
Claude Code Integration
The MCP server is accessed by Claude Code via the Hugging_Face_2 connector
configured in ~/.claude/.mcp.json. The available deferred tools correspond
to the MCP tools listed in Section 5.
Authentication: The
DEFAULT_HF_TOKEN environment variable
provides a default token for all requests. Individual clients can also pass their own
token via the MCP protocol for per-user authentication.
8. Dependencies
External Services
| Dependency | Type | Endpoint | Purpose | Impact if Down |
|---|---|---|---|---|
| HuggingFace Hub API | Critical | https://huggingface.co/api/ |
Model, dataset, space, and paper metadata | All search and detail tools fail |
| HuggingFace Docs | Secondary | https://huggingface.co/docs/ |
Documentation semantic search and fetch | Only docs tools affected |
| Gradio Space APIs | Secondary | https://*.hf.space/ |
Interactive Space invocation via use_space and dynamic_space tools | Only space interaction tools affected |
Internal Dependencies
| Dependency | Type | Purpose |
|---|---|---|
Docker Network (hosting_web) |
Infrastructure | Network connectivity for container |
HF_TOKEN (from .env) |
Config | API authentication for gated content and rate limits |
Runtime Dependencies (in container)
| Package | Version | Purpose |
|---|---|---|
| Node.js | 22.22.0 | JavaScript runtime |
| pnpm | 10.29.2 | Package manager (monorepo workspaces) |
| Zod | * | Schema validation for tool inputs |
| TypeScript | * | Source language (compiled to JS at build time) |
9. Constraints & Risks
| Item | Severity | Description | Mitigation |
|---|---|---|---|
| HuggingFace API rate limits | Medium | Unauthenticated requests are heavily rate-limited. Even authenticated requests have quotas. | HF_TOKEN is configured for authenticated access with higher limits. |
| No local caching | Medium | Every tool call hits the HuggingFace API. Repeated queries for the same model/dataset are not cached. | Accept as-is; HF API is fast and reliable. |
| External dependency | Medium | 100% dependent on HuggingFace infrastructure. No offline capability. | Monitor HuggingFace status page. Service is non-critical for infrastructure operations. |
| Token exposure in environment | Low | DEFAULT_HF_TOKEN is visible in container env. This is a read-only token. |
Token scoped to read-only access. Container is on internal network only. |
| No Traefik routing | Info | Service has no public-facing route (traefik.enable=false). Access is container-to-container only. |
By design. MCP clients connect via Docker network or stdio. |
| Pre-built image (no source control) | Low | No local source code to audit or patch. Updates require pulling new image from GHCR. | Image is from the official HuggingFace repository. Pin version tags for stability. |