Skip to content
Back to search

hf-mcp-server

Hugging Face MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/huggingface/hf-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/huggingface/hf-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/huggingface--hf-mcp-server/badge.svg)](/listings/huggingface--hf-mcp-server)

HTML

<a href="/listings/huggingface--hf-mcp-server"><img src="/api/listings/huggingface--hf-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Follow the instructions below to get started:

<details> <summary>Install in <b>Claude Desktop</b> or <b>claude.ai</b></summary> <br />

Click [here](https://claude.ai/redirect/website.v1.67274164-23df-4883-8166-3c93ced276be/directory/37ed56d5-9d61-4fd4-ad00-b9134c694296) to add the Hugging Face connector to your account.

Alternatively, navigate to [https://claude.ai/settings/connectors](https://claude.ai/settings/connectors), and add "Hugging Face" from the gallery.

</details>

<details> <summary>Install in <b>Claude Code</b></summary> <br />

Enter the command below to install in <b>Claude Code</b>:

claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login

Then start `claude` and follow the instructions to complete authentication.

claude mcp add hf-mcp-server \
  -t http https://huggingface.co/mcp \
  -H "Authorization: Bearer <YOUR_HF_TOKEN>"

</details>

<details> <summary>Install in <b>Gemini CLI</b></summary> <br />

Enter the command below to install in <b>Gemini CLI</b>:

gemini mcp add -t http huggingface https://huggingface.co/mcp?login

Then start `gemini` and follow the instructions to complete authentication.

</details>

<details>

<summary>Install in <b>VSCode</b></summary> <br />

Click <a href="vscode:mcp/install?%7B%22name%22%3A%22huggingface%22%2C%22gallery%22%3Atrue%2C%22url%22%3A%22https%3A%2F%2Fhuggingface.co%2Fmcp%3Flogin%22%7D">here</a> to add the Hugging Face connector directly to VSCode. Alternatively, install from the gallery at [https://code.visualstudio.com/mcp](https://code.visualstudio.com/mcp):

If you prefer to configure manually or use an auth token, add the snippet below to your `mcp.json` configuration:

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }

</details>

<details> <summary>Install in <b>Cursor</b></summary> <br />

Click <a href="https://cursor.com/en/install-mcp?name=Hugging%20Face&config=eyJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcD9sb2dpbiJ9">here</a> to install the Hugging Face MCP Server directly in <b>Cursor</b>.

If you prefer to use configure manually or specify an Authorization Token, use the snippet below:

"huggingface": {
    "url": "https://huggingface.co/mcp",
    "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }

</details>

Once installed, navigate to https://huggingface.co/settings/mcp to configure your Tools and Spaces.

> [!TIP] > Add ?no_image_content=true to the URL to remove ImageContent blocks from Gradio Servers.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 391 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Hugging Face Official MCP Server
  2. <img src='https://github.com/evalstate/hf-mcp-server/blob/main/hf-logo.svg' width='100'>
  3. Welcome to the official Hugging Face MCP Server 🤗. Connect your LLM to the Hugging Face Hub and thousands of Gradio AI Applications.
  4. ## Installing the MCP Server
  5. Follow the instructions below to get started:
  6. <details>
  7. <summary>Install in <b>Claude Desktop</b> or <b>claude.ai</b></summary>
  8. <br />
  9. Click [here](https://claude.ai/redirect/website.v1.67274164-23df-4883-8166-3c93ced276be/directory/37ed56d5-9d61-4fd4-ad00-b9134c694296) to add the Hugging Face connector to your account.
  10. Alternatively, navigate to [https://claude.ai/settings/connectors](https://claude.ai/settings/connectors), and add "Hugging Face" from the gallery.
  11. <img src='docs/claude-badge.png' width='50%' align='center' />
  12. </details>
  13. <details>
  14. <summary>Install in <b>Claude Code</b></summary>
  15. <br />
  16. Enter the command below to install in <b>Claude Code</b>:
  17. ```bash
  18. claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login
  19. ```
  20. Then start `claude` and follow the instructions to complete authentication.
  21. ```bash
  22. claude mcp add hf-mcp-server \
  23. -t http https://huggingface.co/mcp \
  24. -H "Authorization: Bearer <YOUR_HF_TOKEN>"
  25. ```
  26. </details>
  27. <details>
  28. <summary>Install in <b>Gemini CLI</b></summary>
  29. <br />
  30. Enter the command below to install in <b>Gemini CLI</b>:
  31. ```bash
  32. gemini mcp add -t http huggingface https://huggingface.co/mcp?login
  33. ```
  34. Then start `gemini` and follow the instructions to complete authentication.
  35. </details>
  36. <details>
  37. <summary>Install in <b>VSCode</b></summary>
  38. <br />
  39. Click <a href="vscode:mcp/install?%7B%22name%22%3A%22huggingface%22%2C%22gallery%22%3Atrue%2C%22url%22%3A%22https%3A%2F%2Fhuggingface.co%2Fmcp%3Flogin%22%7D">here</a> to add the Hugging Face connector directly to VSCode. Alternatively, install from the gallery at [https://code.visualstudio.com/mcp](https://code.visualstudio.com/mcp):
  40. <img src='docs/vscode-badge.png' width='50%' align='center' />
  41. If you prefer to configure manually or use an auth token, add the snippet below to your `mcp.json` configuration:
  42. ```JSON
  43. "huggingface": {
  44. "url": "https://huggingface.co/mcp",
  45. "headers": {
  46. "Authorization": "Bearer <YOUR_HF_TOKEN>"
  47. }
  48. ```
  49. </details>
  50. <details>
  51. <summary>Install in <b>Cursor</b></summary>
  52. <br />
  53. Click <a href="https://cursor.com/en/install-mcp?name=Hugging%20Face&config=eyJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcD9sb2dpbiJ9">here</a> to install the Hugging Face MCP Server directly in <b>Cursor</b>.
  54. If you prefer to use configure manually or specify an Authorization Token, use the snippet below:
  55. ```JSON
  56. "huggingface": {
  57. "url": "https://huggingface.co/mcp",
  58. "headers": {
  59. "Authorization": "Bearer <YOUR_HF_TOKEN>"
  60. }
  61. ```
  62. </details>
  63. Once installed, navigate to https://huggingface.co/settings/mcp to configure your Tools and Spaces.
  64. > [!TIP]
  65. > Add ?no_image_content=true to the URL to remove ImageContent blocks from Gradio Servers.
  66. ![hf_mcp_server_small](https://github.com/user-attachments/assets/d30f9f56-b08c-4dfc-a68f-a164a93db564)
  67. ## Quick Guide (Repository Packages)
  68. This repo contains:
  69. - (`/mcp`) MCP Implementations of Hub API and Search endpoints for integration with MCP Servers.
  70. - (`/app`) An MCP Server and Web Application for deploying endpoints.
  71. ### MCP Server
  72. The following transports are supported:
  73. - STDIO
  74. - StreamableHTTP in Stateless JSON Mode (**StreamableHTTPJson**)
  75. The Web Application and HTTP Transports start by default on Port 3000.
  76. The StreamableHTTP service is available at `/mcp`. Although not strictly enforced by the specification, this is a common convention.
  77. The public Streamable HTTP deployment serves its MCP Server Card at `/mcp/server-card`. The public card advertises the canonical `https://huggingface.co/mcp` endpoint without authentication-specific query parameters; loopback deployments and explicit non-Hugging Face hosts in `MCP_ALLOWED_HOSTS` advertise their own `/mcp` endpoint. Card responses support cache revalidation with an `ETag`.
  78. The Web Application at `/metrics` reports server status and MCP method metrics.
  79. The **Skills** tab shows process-local catalog health and live Skills activity, filtered by time window (15m/1h/24h), client name/version, method, and outcome. It separates metadata probes (`skills/list`, `skills/get`, directory reads) from successful `SKILL.md` and supporting-file content reads; retrieval does not prove execution or complete installation. Client names/versions are self-reported. Activity is capped at 10,000 events and 24 hours, resets on restart, and flags incomplete coverage. It is independent of `LOG_SKILL_EVENTS`; historical events remain in the configured dataset's `skills/YYYY-MM-DD/` logs. Live activity currently covers the `streamableHttpJson` transport. Health polling never loads/refreshes the catalog and explicitly warns that manifest byte-size verification is not yet implemented. Skills dashboard telemetry contains no target URIs, user hashes, session IDs, or file contents.
  80. The Management Web interface can be placed behind an optional lightweight shared-password gate using `METRICS_PAGE_PASSWORD`. Browser visits to `/` redirect to the MCP welcome page at `/mcp`. Tool selection is resolved independently for each request from the optional Hugging Face user configuration API and the `bouquet`/`mix` query parameters. Note to security researches and bots, this is intentionally lightweight and not considered sensitive or protected data.
  81. Use `?bouquet=openai` to expose Hub filesystem, repository search, details and creation, dynamic Space, Jobs, and sandbox tools. Repository creation, Jobs, dynamic Space, and sandbox tools require Hugging Face authentication.
  82. Use `?bouquet=ptc` (or `?bouquet=codemode`) for the programmatic tool calling (PTC) toolset: 53
  83. typed functions (discovery, repository files, dataset rows, papers, collections, docs, callable
  84. Spaces, repository writes, Jobs and sandboxes) with structured results linked by `hf://` URIs.
  85. Every tool the request's token can use is listed (anonymous: public reads; read token: plus
  86. account/job reads; write token: everything) and clients search them. The profile has its own
  87. one-line instructions; user API settings are bypassed and `gradio` is ignored. Mixing is rejected (including
  88. `mix=ptc` or `mix=codemode` on other bouquets), and no legacy tool is registered. Usage is
  89. shown on the **PTC** tab of the management page (`/api/ptc-metrics`). See [PTC bouquet](docs/ptc.md).
  90. ### Running Locally
  91. You can run the MCP Server locally with either `npx` or `docker`.
  92. ```bash
  93. npx @llmindset/hf-mcp-server # Start in STDIO mode
  94. npx @llmindset/hf-mcp-server-http # Start in stateless Streamable HTTP JSON mode
  95. ```
  96. To run with docker:
  97. ```bash
  98. docker pull ghcr.io/evalstate/hf-mcp-server:latest
  99. docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest
  100. ```
  101. ![image](https://github.com/user-attachments/assets/2fc0ef58-2c7a-4fae-82b5-e6442bfcbd99)
  102. All commands above start the Management Web interface on http://localhost:3000/metrics. Browser visits to http://localhost:3000/ redirect to the MCP welcome page at http://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.
  103. ## Development
  104. This project uses `pnpm` for build and development. Corepack is used to ensure everyone uses the same pnpm version (10.12.3).
  105. For OAuth discovery, dynamic registration, or Client ID Metadata Document diagnostics, see
  106. [`docs/oauth-diagnostics.md`](docs/oauth-diagnostics.md) and run `pnpm oauth:diagnose`.
  107. Benchmark harnesses, historical results, and optimization plans are maintained
  108. in the separate [`hf-mcp-optimise`](docs/benchmarking.md) workspace.
  109. ```bash
  110. # Install dependencies
  111. pnpm install
  112. # Build all packages
  113. pnpm build
  114. ```
  115. ### Build Commands
  116. `pnpm run clean` -> clean build artifacts
  117. `pnpm run build` -> build packages
  118. `pnpm run start` -> start the mcp server application
  119. `pnpm run buildrun` -> clean, build and start
  120. `pnpm run dev` -> concurrently watch `mcp` and start dev server with HMR
  121. ## Docker Build
  122. Build the image:
  123. ```bash
  124. docker build -t hf-mcp-server .
  125. ```
  126. Run with default settings (Streaming HTTP JSON Mode), with the dashboard at `/metrics` on Port 3000.
  127. HTTP clients must send a Hugging Face token in the `Authorization: Bearer` header:
  128. ```bash
  129. docker run --rm -p 3000:3000 hf-mcp-server
  130. ```
  131. Run STDIO MCP Server:
  132. ```bash
  133. docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server
  134. ```
  135. `TRANSPORT` can be `stdio` or `streamableHttpJson` (default).
  136. ### Transport Endpoints
  137. The different transport types use the following endpoints:
  138. - Stateless Streamable HTTP JSON: `/mcp`
  139. - MCP Server Card for Streamable HTTP JSON: `/mcp/server-card`
  140. - STDIO: Uses stdin/stdout directly, no HTTP endpoint
  141. ### Environment Variables
  142. The server respects the following environment variables:
  143. - `TRANSPORT`: The transport type to use (`stdio` or `streamableHttpJson`)
  144. - `DEFAULT_HF_TOKEN`: Default token for local STDIO deployments. HTTP transports do not use this as a fallback for requests without an `Authorization: Bearer` header.
  145. - If running with `stdio` transport, `HF_TOKEN` is used if `DEFAULT_HF_TOKEN` is not set.
  146. - `MCP_ALLOWED_HOSTS`: Additional comma-separated Host allowlist for MCP and API routes. Loopback hosts `localhost,127.0.0.1,::1` are always allowed. Use exact hostnames or leading wildcard entries such as `*.example.com`.
  147. - `HF_API_TIMEOUT`: Timeout for Hugging Face API requests in milliseconds (default: 12500ms / 12.5 seconds)
  148. - `USER_CONFIG_API`: Optional URL for the per-user discovery projection returned by `tools/list`, including configured
  149. Spaces. These settings control which deployed tools are advertised, not whether a direct `tools/call` to a known tool
  150. may execute. Generated Gradio aliases still use the configured Space mapping. When unset, immutable built-in defaults
  151. are used.
  152. - `ALLOW_INTERNAL_ADDRESS_HOSTS`: Optional comma-separated host allowlist to permit internal/reserved DNS resolutions for trusted domains during outbound checks (supports exact hosts and `*.` wildcards, for example: `huggingface.co,*.hf.space`).
  153. - `MCP_STRICT_COMPLIANCE`: set to True for GET 405 rejects in JSON Mode (default serves a welcome page).
  154. - `MCP_STRICT_TOKEN`: set to `true` to reject token-less Streamable HTTP connections with `401` before any server instance is built. Default (unset or any other value) keeps the current behavior: token-less requests continue with the anonymous tool set. Supplied tokens must pass `whoami` validation: invalid tokens return `401`, and unavailable validation (including network errors and upstream failures) returns `503` without allowing the request to proceed. With strict mode disabled, validation failures other than `401` retain the existing fail-open behavior.
  155. - `DISABLE_TOOLS`: Optional comma-separated tool names to hide from `tools/list` and reject if called, for example `hub_repo_search,hf_fs`. Rejected calls remain visible as errors in the MCP dashboard tool-call statistics.
  156. - `PTC_CURSOR_SECRET`: Optional secret that signs PTC `nextCursor` values (HMAC-SHA256 over the call's arguments, token and position). Set it, with the same value on every replica, to make cursors unforgeable. When unset, a fixed built-in key is used: cursors still work across replicas and restarts and reject accidental edits or reuse with other arguments or another token, but are not protected against deliberate forgery.
  157. - `DEFINITION_TAGS`: Set to `off` to disable definition tags, tag checks, and associated cache hints. Enabled by default for eligible HTTP requests; see [definition tags](packages/app/src/server/definition-tags/README.md).
  158. - `DEFINITION_TAGS_TTL_MS`: Cache-hint TTL for eligible tool-list and discovery results (default: `300000`; `0` allowed). Cache scope is always private.
  159. - `DEFINITION_TAGS_SALT`: Optional deploy-wide tag salt. Changing it invalidates known tags; use the same value across replicas.
  160. - `DEFINITION_TAGS_TEST`: Set to `true` to enable the dashboard Caching tab and runtime salt/statistics controls under `/api/definition-tags`. Leave disabled in production. Controls are per-process and protected only when `METRICS_PAGE_PASSWORD` is configured.
  161. - `PROXY_TOOLS_CSV`: Optional CSV that defines Streamable HTTP proxy tool sources (see below).
  162. - `PROXY_TOKEN`: Optional token used only for startup authentication while discovering `PROXY_TOOLS_CSV` schemas.
  163. - `GRADIO_SKIP_INITIALIZE`: When set to `true`, Gradio MCP calls skip the `initialize` handshake and issue `tools/call` directly.
  164. - `METRICS_PAGE_PASSWORD`: Optional shared password for the Management Web interface at `/metrics` and its `/api/*` endpoints. When unset or empty, the interface remains public. This does not protect `/mcp` or `/mcp/server-card`.
  165. - `HF_SKILLS_DIR`: Local directory containing a prebuilt [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) skills snapshot: `skills.json` carries each skill's `uri`, complete `frontmatter`, and per-file `{uri,digest}` resource manifest, alongside the expanded skill directories. On HTTP transports, the server verifies every raw SHA-256 digest and checks the actual `SKILL.md` frontmatter before atomically retaining all files in memory. Each skill is limited to 512 files and 16 MiB of raw content, including `SKILL.md` and nested/shared files; a snapshot exceeding either limit is rejected without replacing the last verified snapshot. Directory reads include empty directories. Snapshots have a three-hour freshness TTL; stale requests keep using the last valid snapshot while one background refresh is loaded and verified, and refresh failures retain that verified snapshot with a five-minute retry delay. The HTTP server implements `skills/list`, `skills/get`, `resources/read`, and optional `resources/directory/read`, and advertises `io.modelcontextprotocol/skills` with `directoryRead: true` only when a valid snapshot is available. Skills are not exposed over the long-lived STDIO transport. Defaults to `/mnt/hf-skills/distribution/latest`, intended for a Hugging Face Space volume mounted from `hf://buckets/huggingface/skills`.
  166. - `LOG_SKILL_EVENTS`: Enables historical product-usage logging for SEP-2640 Skills probes when `LOGGING_DATASET_ID` and a logging token are configured (default: `true`). Events are written under `skills/YYYY-MM-DD/`, separately from tool queries, and contain client/protocol correlation, success, duration, cursor presence, aggregate result counts, and the requested `skill://` URI for targeted get/read operations. Cursor values, frontmatter, resource content, response bodies, and error messages are not recorded.
  167. - `SHUTDOWN_GRACE_MS`: Upper bound for a graceful shutdown on `SIGTERM`/`SIGINT` (default: `25000`). The server drains in-flight HTTP requests for at most `min(5s, grace/3)`, then flushes buffered dataset logs, then exits. Keep it below the platform's stop timeout.
  168. - `RUNTIME_METRICS_LOG_INTERVAL_MS`: Interval for writing a `runtime_sample` record (event-loop utilisation, CPU, event-loop delay, memory, connection reuse, `X-Forwarded-For` hop counts) to the System dataset stream (default: `60000`; `0` disables). Requires system event logging to be enabled. The same data is shown live in the dashboard's Process runtime card.
  169. #### Optional Management Interface Password
  170. Set `METRICS_PAGE_PASSWORD` to a non-empty value to enable a lightweight shared-password gate for the Management Web interface and its API endpoints:
  171. - Browser visits to `/` redirect to `/mcp`. Visits to `/metrics` are redirected to `/metrics/login` until the password is accepted.
  172. - A successful login redirects back to `/metrics`.
  173. - A successful login stores a signed, 30-day `HttpOnly`, `SameSite=Lax` cookie. HTTPS requests also receive the `Secure` cookie attribute.
  174. - `/api/transport`, `/api/sessions`, `/api/transport-metrics`, and `/api/skills-metrics` require the cookie or a valid scraper credential.
  175. - `/mcp` and the public `/mcp/server-card` are not affected.
  176. This is intended only to discourage casual browsing. It has no users, roles, rate limiting, or audit trail and is **not a substitute for real authentication, HTTPS, or access control at the platform/reverse-proxy layer**.
  177. When HTTPS terminates at a reverse proxy, the proxy must overwrite `X-Forwarded-Proto` with the actual client protocol so the application can apply the cookie's `Secure` attribute correctly.
  178. For a Hugging Face Space, configure this as a **Space secret** in the Space settings. A GitHub Actions secret is not automatically passed to a running Space by this repository's workflows. With the Hugging Face CLI, the equivalent command is:
  179. ```bash
  180. hf spaces secrets add <org>/<space> -s METRICS_PAGE_PASSWORD='<shared-password>'
  181. ```
  182. Automated scrapers can send the password in a header:
  183. ```bash
  184. curl --fail-with-body --silent --show-error \
  185. -H "X-Metrics-Password: ${METRICS_PAGE_PASSWORD}" \
  186. https://your-space.hf.space/api/transport-metrics
  187. ```
  188. For simple URL-based jobs, a URL-encoded query parameter is also accepted:
  189. ```bash
  190. curl --fail-with-body --silent --show-error --get \
  191. --data-urlencode "metrics_password=${METRICS_PAGE_PASSWORD}" \
  192. https://your-space.hf.space/api/transport-metrics
  193. ```
  194. Prefer the header where possible. Query-string passwords can be retained in reverse-proxy or access logs, monitoring systems, shell process listings, and browser history even though the application does not log the credential itself.
  195. To expose the shared Hugging Face skills catalog from a Space, mount the bucket and keep `HF_SKILLS_DIR` pointed at its latest distribution directory:
  196. ```bash
  197. hf spaces volumes set <org>/<space> -v hf://buckets/huggingface/skills:/mnt/hf-skills:ro
  198. hf spaces variables add <org>/<space> -e HF_SKILLS_DIR=/mnt/hf-skills/distribution/latest
  199. ```
  200. ### Proxy tools (Streamable HTTP via CSV)
  201. You can load proxy tool definitions at startup by setting `PROXY_TOOLS_CSV` to a **HTTPS URL** or a **local file path**.
  202. If those proxy servers require authentication, set `PROXY_TOKEN`. User, default, and logging tokens are never used
  203. for startup proxy schema discovery.
  204. The server fetches each MCP endpoint once on startup, runs `initialize` + `tools/list` (10s timeout), and registers any tools returned.
  205. If a source fails or returns no tools, it is skipped (no startup failure).
  206. **CSV format**
  207. ```
  208. proxy_id,url,response_type,allow_anonymous,forward_hf_token
  209. papers,https://evalstate-hf-papers.hf.space/mcp,SSE,false,true
  210. news,https://example.com/mcp,JSON,false,true
  211. hfnlweb,https://rvguha-hfnlwebdemo.hf.space/mcp/,SSE,true,false
  212. ```
  213. - `proxy_id` (also accepted as `tool_name` in the header): local tool name for single-tool upstreams; identifier for
  214. the proxy source when the upstream exposes multiple tools.
  215. - `url`: Streamable HTTP MCP endpoint.
  216. - `response_type`: legacy compatibility field; `SSE` and `JSON` are both accepted. Proxy calls can still consume
  217. upstream Streamable HTTP responses, while this server always returns direct JSON-RPC responses to its clients.
  218. - `allow_anonymous`: optional boolean, default `false`. Allows unauthenticated clients to discover **and call** this
  219. source's tools when selected. It does not automatically add the tools to the default discovery selection.
  220. - `forward_hf_token`: optional boolean, default `true` for compatibility. Set to `false` to omit the caller's HF
  221. credential from both `Authorization` and `X-HF-Authorization` on upstream tool calls and MCP App resource reads.
  222. The client may still authenticate to this MCP server; disabling forwarding does not change that authentication.
  223. Columns are positional in the order shown. Existing three-column rows remain supported. Missing or blank policy fields
  224. use the defaults above; nonempty values must be `true` or `false` (case-insensitive). Invalid policy values cause the
  225. whole row to be skipped, rather than silently enabling forwarding. Both policies apply to every tool from that source.
  226. `PROXY_TOKEN` is a separate, explicitly configured startup discovery credential and is **not** controlled by
  227. `forward_hf_token`. If set, it is sent to downstream sources during startup schema discovery, including public sources.
  228. Leave it unset when no startup credential should be sent. Caller credentials and `HF_TOKEN` / `DEFAULT_HF_TOKEN` are
  229. never used as startup discovery fallbacks.
  230. For the public HFNLWebDemo endpoint, use `true,false` as shown above. The trailing slash in `/mcp/` is required.
  231. CSV changes take effect after restarting the server. Deploy a version supporting these policy columns **before**
  232. relying on them: older versions ignore the extra columns and retain authenticated-only access with token forwarding.
  233. **Tool naming**
  234. Tool naming depends on how many tools the upstream MCP endpoint returns:
  235. - Single upstream tool: the exposed tool name is the first CSV column.
  236. - Multiple upstream tools: the exposed tool names are the upstream tool names.
  237. If an exposed proxy tool name collides with an already-registered tool, the proxy tool is skipped and a warning is
  238. logged.
  239. You can include these tool names in bouquets or mixes to advertise them through `tools/list`.
  240. Use `bouquet=proxy` or `mix=proxy` to advertise all proxy tools loaded from `PROXY_TOOLS_CSV` (in addition to the base
  241. built-in tools). Direct calls to a known startup-configured proxy tool do not depend on that discovery selection,
  242. but still enforce `allow_anonymous` and `DISABLE_TOOLS`.
  243. **Selecting proxy tools through the settings API**
  244. An upstream `USER_CONFIG_API` response can select an already-loaded proxy source using its ID in `builtInTools`:
  245. ```json
  246. {
  247. "builtInTools": ["hfnlweb"],
  248. "spaceTools": []
  249. }
  250. ```
  251. For this multi-tool source, `hfnlweb` selects both `ask` and `list_sites`; individual tool names can also be selected.
  252. The upstream API must accept those IDs in its own validation. Source URLs, `allow_anonymous`, and `forward_hf_token`
  253. remain trusted server-catalog settings, not user settings: the settings API selects tools but cannot grant anonymous
  254. access or override credential forwarding. Sources must be loaded successfully at startup before the API can select them.
  255. ### Dynamic Space health checks
  256. `monitor/distribution/bin/monitor.py --check` is a read-only CSV health check for the catalog configured by
  257. `DYNAMIC_SPACE_DATA`. It checks Hub runtime state and each runnable Space's Gradio MCP schema, but never invokes a
  258. tool, restarts a Space, or opens a PR. Run it locally with:
  259. ```bash
  260. pnpm health:dynamic-spaces
  261. ```
  262. It uses Python 3 and the standard library. The catalog URL must be public. It uses `HF_TOKEN`, then
  263. `DEFAULT_HF_TOKEN`, for private Space metadata and schema requests. Sleeping Spaces are accepted from Hub metadata
  264. without waking them unless `HEALTH_PROBE_SLEEPING=true`.
  265. For the eight-hour repair schedule and read-only dashboard, follow [`monitor/README.md`](monitor/README.md).
  266. The Bucket preserves reports and the atomic ledger.
  267. `HF_TOKEN` (falling back to `DEFAULT_HF_TOKEN`) is the parent Hub credential for health reads, restarts, and
  268. PR creation; both repair actions are enabled when it is present. `RESPONSES_API_KEY` (or its `OPENAI_API_KEY`
  269. fallback) is the Doctor model credential. `MONITOR_HF_TOKEN`, if set, is a separate read-only token passed only to
  270. the Doctor. Omit `HF_TOKEN` for a public read-only monitor. Job logs contain one status line per Space and a final
  271. summary.
  272. Exit code `0` means every Space is healthy and `1` means at least one Space is unhealthy or degraded. Invalid catalog
  273. or configuration is reported as exit code `2`. Optional tuning variables are `HEALTH_TIMEOUT_SECONDS`,
  274. `HEALTH_ATTEMPTS`, `HEALTH_RETRY_DELAY_SECONDS`, and `HEALTH_PROBE_SLEEPING`. See
  275. [`monitor/README.md`](monitor/README.md) for retry and manual-reset policy.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.