> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Hugging face MCP server

The Hugging face MCP connector routes your AI agent's tool calls to Hugging face's own MCP server through Scalekit. Each user signs in to Hugging face once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 11 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** AI, Developer Tools
**Tools:** 11: 8 read, 3 write, 0 destructive
**Users sign in with:** OAuth
**OAuth app:** Scalekit's or your own
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=HUGGINGFACEMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Hugging face MCP connection

   In **AgentKit > Connections**, create a Hugging face MCP connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

   Scalekit credentials are available for Hugging face MCP server, so you don't need to register an OAuth app.

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'huggingfacemcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Hugging face MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'huggingfacemcp_hf_whoami',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "huggingfacemcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Hugging face MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="huggingfacemcp_hf_whoami",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'huggingfacemcp_hf_doc_fetch',
  toolInput: {
    doc_url: '<doc_url>',
  },
  connector: 'huggingfacemcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="huggingfacemcp_hf_doc_fetch",
    tool_input={
        "doc_url": "<doc_url>",
    },
    connection_name="huggingfacemcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `huggingfacemcp_hf_doc_fetch`

Hf Doc Fetch · Read-only

Fetch the content of a Hugging Face documentation page by URL, with optional character offset for pagination.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `doc_url` (`string`, required): Full URL of the Hugging Face or Gradio documentation page to fetch.
- `offset` (`number`, optional): Token offset for paginating large documents. Use the offset value from the truncation message to fetch the next chunk.

Example input: `{"doc_url":"<doc_url>"}`

### `huggingfacemcp_hf_doc_search`

Hf Doc Search · Read-only

Search Hugging Face documentation across all products or a specific product by query.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `query` (`string`, required): Semantic search query. Use an empty string to explore structure and navigation tips, or provide a specific query to find targeted documentation.
- `product` (`string`, optional): Hugging Face product or library to filter results by. Provide when known to narrow the search.

Example input: `{"query":"<query>"}`

### `huggingfacemcp_hf_fs`

Hf Fs · Read-only

Navigate and search Hugging Face Hub resources (models, datasets, spaces, buckets, collections, papers, and documentation) through a virtual filesystem interface over hf:// URIs, using ls, cat, attach, stat, find, and search commands.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `args` (`array`, required): Command arguments; each array item is one grammar token (e.g. the URI, flags, or query terms for the chosen command).
- `cmd` (`string`, required): Command to execute: ls, cat, attach, stat, find, or search. One of: `ls`, `cat`, `attach`, `stat`, `find`, `search`.

Example input: `{"args":[],"cmd":"ls"}`

### `huggingfacemcp_hf_whoami`

Hf Whoami · Read-only

Return the currently authenticated Hugging Face user's profile information.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs: none.

Example input: `{}`

### `huggingfacemcp_hub_repo_details`

Hub Repo Details · Read-only

Retrieve details for one or more Hugging Face Hub repositories by their IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `repo_ids` (`array`, required): One or more repository IDs in "author/name" format. Supports models, datasets, and spaces.
- `config` (`string`, optional): Dataset Viewer config name. Required for dataset_preview when the dataset has multiple configs. Discover available configs via dataset_structure.
- `limit` (`integer`, optional): Number of rows to return for dataset_preview. Defaults to 5; clamped between 1 and 100.
- `offset` (`integer`, optional): Row offset for dataset_preview pagination. Defaults to 0.
- `operations` (`array`, optional): Details to return. Defaults to ["overview"]. For datasets, use ["overview", "dataset_structure"] first, then ["dataset_preview"] with config and split.
- `repo_type` (`string`, optional): Repository type to look up. Auto-detected when omitted. One of: `model`, `dataset`, `space`.
- `split` (`string`, optional): Dataset split name. Required for dataset_preview when the dataset has multiple splits. Discover available splits via dataset_structure.

Example input: `{"repo_ids":[]}`

### `huggingfacemcp_hub_repo_search`

Hub Repo Search · Read-only

Search the Hugging Face Hub for models, datasets, or spaces with optional filters for author, task, and sort order.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `author` (`string`, optional): Organization or user namespace to filter results by.
- `filters` (`array`, optional): Hub filter tags to apply to each selected repo type. Supports task tags, language codes, and framework tags.
- `limit` (`number`, optional): Maximum number of results to return per selected repository type. Clamped between 1 and 100. Default: `20`.
- `query` (`string`, optional): Search term for repositories. Leave blank with sort + limit set to browse trending or recent repos.
- `repo_types` (`array`, optional): Repository types to include in the search. Defaults to model and dataset. space uses keyword search.
- `sort` (`string`, optional): Sort order for results, applied in descending order. One of: `trendingScore`, `downloads`, `likes`, `createdAt`, `lastModified`.

Example input: `{}`

### `huggingfacemcp_paper_search`

Paper Search · Read-only

Search Hugging Face Papers by query and return matching papers with abstracts and author information.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `query` (`string`, required): Semantic search query for finding ML research papers.
- `concise_only` (`boolean`, optional): Return a 2-sentence abstract summary instead of the full text. Recommended for broad queries that return many results. Default: `false`.
- `results_limit` (`number`, optional): Maximum number of paper results to return. Default: `12`.

Example input: `{"query":"<query>"}`

### `huggingfacemcp_space_search`

Space Search · Read-only

Search Hugging Face Spaces by query and return matching spaces with relevance scores.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `query` (`string`, required): Semantic search query for finding Hugging Face Spaces.
- `limit` (`number`, optional): Maximum number of Space results to return. Default: `10`.
- `mcp` (`boolean`, optional): Set to true to return only MCP Server-enabled Spaces. Required when using results with dynamic_space. Default: `false`.

Example input: `{"query":"<query>"}`

### `huggingfacemcp_dynamic_space`

Dynamic Space · Write

Call a Hugging Face MCP-enabled Space dynamically. Use 'discover' to list available MCP spaces, 'view_parameters' to inspect a space's tools, or 'invoke' to call a specific tool.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `operation` (`string`, optional): Action to perform: discover lists available tasks, view_parameters inspects a space, invoke runs it. One of: `discover`, `view_parameters`, `invoke`.
- `parameters` (`string`, optional): JSON string of input parameters. Used only with the "invoke" operation.
- `space_name` (`string`, optional): Space ID in "username/space-name" format. Required for "view_parameters" and "invoke" operations.

Example input: `{}`

### `huggingfacemcp_gr1_z_image_turbo_generate`

Gr1 Z Image Turbo Generate · Write

Generate an image from a text prompt using the Image Turbo model hosted on Hugging Face Spaces.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `prompt` (`string`, optional): Text prompt describing the desired image content
- `random_seed` (`boolean`, optional): Generate a new random seed for each run. Set to false to use the value in the seed field. Default: `true`.
- `resolution` (`string`, optional): Output resolution in "WIDTHxHEIGHT ( RATIO )" format. One of: `1024x1024 ( 1:1 )`, `1152x896 ( 9:7 )`, `896x1152 ( 7:9 )`, `1152x864 ( 4:3 )`, `864x1152 ( 3:4 )`, `1248x832 ( 3:2 )`, `832x1248 ( 2:3 )`, `1280x720 ( 16:9 )`, `720x1280 ( 9:16 )`, `1344x576 ( 21:9 )`, `576x1344 ( 9:21 )`, `1280x1280 ( 1:1 )`, `1440x1120 ( 9:7 )`, `1120x1440 ( 7:9 )`, `1472x1104 ( 4:3 )`, `1104x1472 ( 3:4 )`, `1536x1024 ( 3:2 )`, `1024x1536 ( 2:3 )`, `1536x864 ( 16:9 )`, `864x1536 ( 9:16 )`, `1680x720 ( 21:9 )`, `720x1680 ( 9:21 )`, `1536x1536 ( 1:1 )`, `1728x1344 ( 9:7 )`, `1344x1728 ( 7:9 )`, `1728x1296 ( 4:3 )`, `1296x1728 ( 3:4 )`, `1872x1248 ( 3:2 )`, `1248x1872 ( 2:3 )`, `2048x1152 ( 16:9 )`, `1152x2048 ( 9:16 )`, `2016x864 ( 21:9 )`, `864x2016 ( 9:21 )`. Default: `1024x1024 ( 1:1 )`.
- `seed` (`integer`, optional): Seed value for reproducible image generation. Ignored when random_seed is true. Default: `42`.
- `shift` (`number`, optional): Time shift parameter for the flow matching scheduler. Controls generation quality. Default: `3`.
- `steps` (`number`, optional): Number of inference steps for the diffusion process. Higher values improve quality but take longer. Default: `8`.

Example input: `{}`

### `huggingfacemcp_hf_hub_query`

Hf Hub Query · Write

Ask a natural language question about the Hugging Face Hub and get an AI-generated answer.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `message` (`string`, required): Natural language query to run against the Hugging Face Hub.

Example input: `{"message":"<message>"}`

## Related

Other AI connectors ([all 116](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 49 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |